Introduction

This document describes how to interface a World Wide Web-based “shopping cart” system to the World Wide Web-based e-gold^®payment system. This interface uses standard HTML forms to provide a simple way for online merchants to integrate e-gold^®as a method of payment for their merchandise or services. Once reached via the shopping cart interface, web pages hosted by e-gold Ltd’s server allow an online buyer to pay out of his e-gold^®account directly to the merchant’s e-gold^®account.

This document also includes an example HTML form for interfacing to the e-gold^®payment system. This form is functionally equivalent to one that merchants will need to provide within their shopping cart check-out system to interface to the e-gold^®payment system. Finally, examples of the forms submitted back to a merchant’s server are shown.

1.1 Intended Audience

This document is intended to be utilized by technical personnel supporting online merchants. These are expected to be webmasters or software engineers having a working knowledge of HTML forms.

1.2 Terminology

For the purposes of this document, the term “merchant” refers to an individual or business that utilizes the World Wide Web as a means for selling its products or services. Moreover, this individual or business is understood to have a valid e-gold^®account.

For the purposes of this document, the term “buyer” refers to an individual that purchases products or services from a merchant over the Internet (World Wide Web). The buyer may or may not have an e-gold^®account.

The Shopping Cart Interface is abbreviated with the acronym SCI.

1.3 Overview of e-gold^®Shopping Cart Interface

1.3.1 Identification

The e-gold^®Shopping Cart Interface (SCI) is an HTML forms-based interface that merchants can incorporate into their web-based shopping cart systems to allow buyers to pay for online purchases with e-gold^®.The SCI supports secure data transfer using Secure Sockets Layer (SSL).

1.3.2 Objectives

A brief discussion of the objectives for the e-gold^®SCI will probably provide insight as to why it was implemented the way it was. There were several objectives for the e-gold^®Shopping Cart Interface:

Simplicity - the SCI must be relatively easy (i.e. low cost) for merchants to implement so as to encourage wide spread adoption.

Platform Independence - the merchant side of the SCI must use a platform/vendor independent technology to ensure compatibility with the largest possible number of merchant systems.

Security and Reliability - the SCI must utilize proven, widely available and understood technology. Encryption must be supported for all data communications.

Accountability - the SCI must provide merchants specific, accountable confirmation of each e-gold^®payment transaction made.

Flexibility - the SCI must be flexible enough to support merchants’ unique shopping cart software requirements.

1.3.3 Implementation

The e-gold^®Shopping Cart Interface interacts with a merchant’s Web server as shown in Figure 1: Simplistic View of Shopping Cart Interface. This simplistic figure shows how an online buyer is diverted from the merchant’s normal shopping cart web server to the e-gold web server to accomplish (or abort) an e-gold^®payment to the merchant. The basic scheme is explained here, however a more detailed description is provided in subsequent sections of this document.

Please note that all of the buyer’s web browser communications with the e-gold^®server are secure since they are encrypted using the Secure Sockets Layer (SSL).

To interface to the e-gold^®payment system using the Shopping Cart interface, a merchant must modify his current check out process to include e-gold as a payment method. Then, when a buyer selects e-gold^®as a payment method during check out, he is actually submitting an HTML form containing purchase information to the e-gold^®Web server (Figure 1: Simplistic View of Shopping Cart Interface, step 1). The submitted form tells the e-gold^®system the merchant’s e-gold^®account number, the amount of the purchase, etc. Other merchant-specific information, such as order number, etc. can be included along on this form in hidden text fields.

The e-gold^®system then provides a user interface via HTML forms (see Figure 1: Simplistic View of Shopping Cart Interface) to the buyer to allow the payment transaction to be completed or aborted. The e-gold^®system returns control to the merchant’s shopping cart system by causing the buyer to submit a form (or to simply follow a hypertext link) back to the merchant server system at one of two configurable target URLs (shown as web pages X and Y in the figure), depending upon whether the payment transaction was successful or unsuccessful/cancelled by the buyer (Figure 1: Simplistic View of Shopping Cart Interface, steps 2 or 3 respectively).

Additionally, if and when a successful payment is made to the merchant by the buyer, payment information can be sent directly by the e-gold^®server via one of several means, as configured by the Merchant using the STATUS_URL input field:

a) an HTML form can be submitted (POST or GET method) directly by the e-gold^® web server to the merchant’s web server. This HTML form contains payment transaction information as well as all the merchant-specific information that was provided by the merchant’s system in Figure 1: Simplistic View of Shopping Cart Interface, Step 1.

b) payment information can be sent via e-mail to an e-mail address provided by the merchant. This method is used if the STATUS_URL contains a mailto: link.

To support Merchant validation of the critical payment information, the e-gold^®server generates an MD5 hash value from the critical payment data and a “shared secret” and includes this 128 bit hash along with the payment information. Software tools are available to the Merchant to check the received MD5 hash value against the expected MD5 hash value. If the MD5 hash values match, the Merchant can be fairly confident that:

a) the payment confirmation information originated from the e-gold^®server

b) the payment data was received as it was sent by the e-gold^®server (no data tampering took place)

It is important to note that payment confirmation information is not sent when a payment is aborted or fails, since in those cases the buyer is returned to the merchant’s shopping cart web pages (see Figure 1: Simplistic View of Shopping Cart Interface, step 3) where he is typically allowed to select an alternate payment method.

Figure 1: Simplistic View of Shopping Cart Interface

Strictly speaking, the Shopping Cart Interface in Figure 1: Simplistic View of Shopping Cart Interface is incomplete since it fails to show there are really three elements in the Shopping Cart Interface:

The Merchant’s Web Server
The e-gold^®Web Server
The Buyer’s Web Browser

A more accurate top-level interface diagram is shown in Figure 2. This diagram is intended to emphasize that the buyer’s web browser is involved in transferring purchase information between the merchant’s server and the e-gold^®system and vice-versa.

Figure 2: Top-Level SCI Diagram

Shopping Cart Interface Details

This section provides detailed information to allow a merchant to interface his Shopping Cart check-out system with the e-gold payment system.

1.4 Entry Form into the e-gold^®Payment System

To gain access to the e-gold^®payment system a merchant must first modify his shopping cart checkout system to include e-gold^®as a possible payment method. The payment method selection for e-gold should be implemented on the merchant’s web page as a form submit button, or other means which causes an HTML form to be submitted to the e-gold^®web server when clicked/chosen by a buyer.

The form thereby submitted to the e-gold^®web server by the buyer’s web browser contains sufficient data to fully describe the current purchase to the e-gold^®payment system. This form also contains other hidden text fields to control how the e-gold^®server interacts with the Merchant’s server(s) once payment is completed or aborted. This form is called the SCI Entry Form, since it is the means by which a buyer using a merchant’s shopping cart system gains entry into the e-gold^®payment system. The specifications for the Entry Form are provided in this section.

1.4.1 Entry Form ACTION

The Merchant must set his/her form ACTION to:
“https://www.e-gold.com/sci_asp/payments.asp”.
This is a secure (Secure Sockets Layer) link to the Active Server Page on the e-gold^®Web server that handles shopping cart interface (SCI) payments.

1.4.2 Entry Form METHOD

The Merchant should set his/her form METHOD to POST. Setting this method allows the e-gold^®active server pages to retrieve the hidden text field values properly from the submitted form.

1.4.3 Entry Form Hidden Text Fields

Hidden text fields are used on the entry form to convey information about the buyer’s purchase as well as other merchant-specific information. The entry form must contain the required fields, but it may also contain optional merchant-specific hidden text fields as explained below.

1.4.3.1 Required and Associated Optional Hidden Text Fields

Table 1 shows the required hidden text field names and associated values and usage.

Field Name	Field Value and Usage
PAYEE_ACCOUNT	The merchant’s e-gold^®account number to which the payment is to be made.
PAYEE_NAME	The name the merchant wishes to have displayed as the Payee on the e-gold^®payment form. An example field value is “High Tech Widgets, Inc.”.
PAYMENT_AMOUNT	The total amount of the purchase, in payment units (see below). Example values are 345.23 and 0.00012. The amount may contain up to 6 digits to the right of the decimal point to allow for very small payments and extreme accuracy.
PAYMENT_UNITS	A designator which specifies the units in which the PAYMENT_AMOUNT value is expressed. Possible units include many international currencies and two units of weight. See Table 2 for the complete set of possible values. Note that if payment units are Troy Ounces or Grams, then it’s imperative that the PAYMENT_METAL_ID not be set to zero (0).
PAYMENT_METAL_ID	The numeric code for the metal in which the payment is to be made (see Table 3).
PAYMENT_ID	(Optional) The value of this field can be used by the merchant for the order number or any other reference number he wishes. This field is accounted for in the MD5 message digest sent with payment acknowledgement. If the field in not present on the SCI entry form, the string “NULL” is used as its value when computing the MD5 message digest.
STATUS_URL	(Optional) Controls whether and how payment status is returned by the e-gold server to the merchant. No payment status is returned to the merchant if this field is not present or if its value is set to “NULL”. Otherwise the field value determines how and where the payment status is sent as described below. Payment status in e-mail: Payment status is sent in the form of e-mail when the value field is set to an e-mail address prefixed by “mailto:”. An example value field for this method is “mailto:honcho@sweatshop.com”. Note that “mailto:” must be specified in lower case, however case is unimportant for the e-mail address itself. Payment status in Form Post: Payment status is submitted as an HTML form if the URL is specified as the value of the STATUS_URL field. The form is submitted to the URL with the POST method by the e-gold server upon successful completion of an e-gold payment. Thus, the target URL would normally be that of a cgi program or other form processor. This URL can specify a secure protocol such as https. An example value for having the payment status sent as a form is: “https://www.sweatshop.com/orderpayment.asp .”
PAYMENT_URL	The URL to which a form is submitted or to which a hypertext link is taken by the buyer’s browser upon successful e-gold^®payment to the merchant. This is the buyer’s normal return path into the merchant’s shopping cart system. This URL can specify a secure protocol such as https. By default, this URL is assumed to be a target for a form POST operation, however other actions are possible when the optional PAYMENT_URL_METHOD field is specified (see below).
PAYMENT_URL_METHOD	(Optional) This field controls how the value for the PAYMENT_URL field is used. The PAYMENT_URL_METHOD field value can be “POST” or “GET” or “LINK”, and must be specified in upper case. The actions taken for each are as follows: “POST” – The payment status is sent to the PAYMENT URL in an HTML form using the POST method. “GET” - The payment status is sent to the PAYMENT URL in an HTML form using the GET method. “LINK” – When payment is made, a simple hypertext link is used to return to the PAYMENT_URL.
NOPAYMENT_URL	The URL to which a form is submitted or to which a hypertext link is taken by the buyer’s browser upon an unsuccessful or cancelled e-gold^®payment to the merchant. This is the buyer’s alternate return path into the merchant’s shopping cart system when an e-gold^®payment cannot be made or is cancelled. Note that this URL can be the same as that provided for PAYMENT_URL, since status is provided on the form in hidden text fields to distinguish between the two payment outcomes. This URL can specify a secure protocol such as https. By default, this URL is assumed to be a target for a form POST operation, however other actions are possible when the optional NOPAYMENT_URL_METHOD field is specified (see below).
NOPAYMENT_URL_METHOD	(Optional) This field controls how the value for the NOPAYMENT_URL field is used. The NOPAYMENT_URL_METHOD field value can be “POST” or “GET” or “LINK”, and must be specified in upper case. The actions taken for each are as follows: “POST” – The unsuccessful status is sent to the NOPAYMENT URL in an HTML form using the POST method. “GET” - The unsuccessful status is sent to the NOPAYMENT URL in an HTML form using the GET method. “LINK” – upon an unsuccessful or cancelled e-gold™ payment to the merchant, a simple hypertext link is used to pass control to the NOPAYMENT_URL.
BAGGAGE_FIELDS	A space delimited list of hidden text field names used exclusively by the merchant for his own purposes. An example value is: “KEY_CODE CUSTOMER_ID BATCH_NUM”. If the merchant requires no additional fields then the value of BAGGAGE_FIELDS should be set to an empty string (“”).

Table 1: Required and Associated Optional Hidden Text Fields

1.4.3.2 Optional Merchant-specific Hidden Text Fields

Other optional hidden text fields can be included by the merchant on the submitted form for items of interest to the merchant such as the Order number, Customer number, etc., however these field names must be declared in the value of the text field called BAGGAGE_FIELDS. Optional field name/value pairs are carried along by the e-gold^®system during the payment process and eventually passed back to the merchant’s web site with their original values intact. Thus, if a merchant expects to have his hidden fields carried along, he must list those field names in the BAGGAGE_FIELDS value.

In other words, the e-gold^®system only propagates merchant-specific hidden text fields when their field names are listed in the value of the BAGGAGE_FIELDS field.

Note also that each field name listed in the BAGGAGE_FIELDS value must appear on the entry form or it will generate an error when the form is submitted to the e-gold^®web server.

When a buyer clicks the e-gold^®payment button on the merchant’s page, this form is submitted (Figure 1: Simplistic View of Shopping Cart Interface, step 1) to the SCI payment Active Server Page on the e-gold^®web server. The target Active Server Page dynamically generates a customized e-gold^®e-metal payment form back to the buyer. This payment form appears with the following data items already filled-in:

a) Payee (merchant’s name as specified in PAYEE_NAME)

b) Payee Account number (as specified in PAYEE_ACCOUNT)

c) Payment amount (as specified in PAYMENT_AMOUNT)

d) Payment units (as specified in PAYMENT_UNITS). Payment units can be any one of the values shown in Table 2. Note that support for additional currency units may be added in the future.

e) Payment metal (as specified by PAYMENT_METAL_ID). This is the name of the metal in which payment is to be made. Note that a value of zero (0) means that the buyer is allowed to select the metal for payment himself during the e-gold payment process. Otherwise, payment can only be made with the specified type of metal. Table 3 shows the PAYMENT_METAL_ID values for the supported types of metals.

Payment Units (Abbreviation)	PAYMENT_UNITS Value
US Dollar (USD)	1
Canadian Dollar (CAD)	2
French Franc (FRF)	33
Swiss Francs (CHF)	41
Gt. Britain Pound (GPB)	44
Deutschemark (DEM)	49
Australian Dollar (AUD)	61
Japanese Yen (JPY)	81
Gram (g)	8888
Troy Ounce (oz)	9999

Table 2: Supported Payment Units

Metal for Payment	PAYMENT_METAL_ID Value
Buyer’s Choice	0
Gold	1
Silver	2
Platinum	3
Palladium	4

Table 3: Payment Metals

1.5 Buyer Interaction With the e-gold^®Payment System

Once the buyer’s browser has submitted the initial form to the e-gold^®payment system, the user interface seen by the buyer is quite similar to the normal e-gold^®e-metal payment process. An outline of the process is described below:

1. An e-metal Payment Order Form similar to that shown in Figure 3 appears. This form allows the buyer to enter an optional memo, and his e-gold account number and password to authorize the payment. If the merchant has specified that the buyer can choose the payment metal, then a list box appears for that purpose. Once the buyer has completed the form he can then elect to click the Preview button to preview the payment transaction or instead click the Cancel button to cancel the payment process. Clicking the Cancel button causes the buyer’s web browser to submit a form (or simply link to) a URL specified by the merchant. This URL is predefined by the merchant to specify a web page or a cgi program or other HTML form processor program (could be an Active Server Page or Perl script) to handle the buyer’s transition back into the merchant’s shopping cart check-out area.

2. If the Preview button is clicked, the Payment Order Form is submitted to the e-gold^®web server. Upon receiving this form, the e-gold^®system performs the following processing:

a) The payer’s account number and password are validated

b) The payee’s account number is validated

c) The payer’s e-gold^®account balance is checked to make sure that the metal balance is sufficient to cover the current payment

Figure 3: Example Payment Order Form

3. Assuming no error conditions are encountered, the e-gold^®system presents the buyer with the payment preview screen. This page displays the following information:

a) Payee’s name and account number

b) Payer’s name and account number

c) Value of the payment (expressed in the units specified by PAYMENT_UNITS)

d) The type of metal for the payment

e) Total metal amount (weight) to be deducted from payer’s e-gold^®account if the payment transaction is confirmed

f) A button to confirm the payment

g) A button to cancel the payment

4. If the buyer clicks the Confirm button, the payment preview page is submitted to the e-gold^®web server. Upon receipt of this form, the e-gold^®server repeats all of the previous validation and, if no exception is found, commits the payment transaction to the e-gold^®database.

5. Once the payment transaction is secured, the e-gold^®server optionally sends payment transaction status to the merchant’s server in one of several ways:

a) as an HTML form directed to a form processing program on the merchant’s web server. The specific target URL (FORM ACTION) is specified by the merchant as part of the shopping cart interface. Specifically, the URL is taken from the hidden text field named STATUS_URL. The form is submitted via the POST method. Any response from the merchant’s system to the submitted form is ignored by the e-gold^®system.

b) as e-mail sent to the e-mail address provided in the STATUS_URL field value.

6. Next, a payment confirmation page is sent to the buyer by the e-gold^®system. This page (see Figure 4) contains:

a) A summary of the payment

b) The e-gold Payment Reference Number for the payment transaction

c) A button labeled “Continue”. Clicking this button causes the buyer’s browser to submit a form to (or simply link to) the URL specified by the PAYMENT_URL field. This is the normal return path into the merchant’s system.

Figure 4: Example Payment Confirmation Page

d) If the buyer elects to cancel the payment process at any point, his clicking on the “Cancel” button (actually a submit button) causes his browser to submit a form to (or simply link to) the URL specified by the NOPAYMENT_URL field. This is the alternate return path into the merchant’s system.

e) If an error is detected by the e-gold^®system during the payment process, an appropriate response page is presented by the e-gold^®system to the buyer. When this response page is dismissed by the buyer (by clicking on a button labeled “Return to Merchant” or other similar phrase), it causes his browser to submit a form to (or simply link to) the URL specified by the NOPAYMENT_URL field.

3.1 e-gold^®Payment System Interaction with Merchant System

The e-gold^®Payment System interacts with the Merchant system when payment is completed, or when payment is not completed due to cancellation or some other reason. The e-gold^®Payment System interacts in these ways:

a) once payment has been made it returns the Buyer to a Merchant-specified web page (usually on the Merchant’s web site).

b) if payment was not made for any reason it returns the Buyer to a Merchant-specified web page (again, usually on the Merchant’s web site).

c) In the event that payment was made, it provides payment confirmation information to the Merchant by posting an HTML form to the Merchant’s server, or by sending e-mail to the Merchant.

3.1.1 Forms Sent to the Merchant System

By default there are three distinct HTML forms that are submitted to the Merchant’s Web Server, each serving a different purpose. A summary of these forms is shown in Table 4.

New features now allow a Merchant to configure his entry form to the SCI to override these default actions of the SCI. The options now available can be used to cause the SCI to:

a) use simple hypertext links instead of forms to return control to the Merchant’s server once payment or nonpayment has occurred

b) send payment confirmation as e-mail (instead of a form)

c) suppress payment confirmation entirely if desired

Form Name	Sent by	To URL Specified by	Purpose
Payment Transaction Form	e-gold^®server	STATUS_URL	Provides Confirmation of a Payment Transaction
Buyer Normal Return Form	Buyer’s browser	PAYMENT_URL	Initiates Buyer’s normal transition from e-gold^®payment system back into merchant’s shopping cart system (if payment has been made).
Buyer Alternate Return Form	Buyer’s browser	NOPAYMENT_URL	Initiates Buyer’s alternate transition from e-gold^®payment system back into merchant’s shopping cart system (if no payment has been made).

Table 4: Forms Sent Back to Merchant System

A buyer’s interaction with the e-gold^®payment process completes with one of three outcomes:

1. The payment was completed successfully. In this case:

a) the Payment Transaction Form is always submitted by the e-gold^®server to confirm that a payment was made and to provide the associated e-gold batch number.

b) the Buyer Normal Return Form is usually submitted by the buyer’s browser. Status information embedded in the form indicates that the payment was made and the associated e-gold^®transaction batch number.

2. The payment was attempted but failed for some reason. In this case:

a) the Buyer Alternate Return Form is usually submitted by the buyer’s browser. Status information embedded in the form indicates that the payment wasn’t made.

3. The buyer cancelled the payment process. In this case:

a) the Buyer Alternate Return Form is usually submitted by the buyer’s browser. Status information embedded in the form indicates that the payment wasn’t made.

Please note that only when payment succeeds does the e-gold^®server submit a form directly to the merchant’s web server to indicate payment has been made. This form carries payment transaction status from the e-gold^®system back to the merchant system in hidden text fields.

This form may seem superfluous until you consider that relying on the buyer’s browser to relay payment transaction data back to the merchant’s server is unreliable and unwise. Why?

a) The buyer may not follow the expected path to complete the transition back into the merchant’s shopping cart system. He may, for example, recall a saved HTTP link to jump to and browse a different web site.

b) The buyer could modify the HTML forms sent to his browser before submitting them to the merchant’s system.

3.1.1.1 Payment Transaction Form

Table 5 shows the hidden text fields that will always be present on the Payment Transaction Form sent directly to the merchant’s system by the e-gold^®server.

Note that the PAYEE_ACCOUNT field value returned should match the account number placed on the SCI entry form by the merchant’s system, however it is possible for a buyer to tamper with the PAYEE_ACCOUNT field value prior to submitting the entry form to the e-gold^®server. Thus, a merchant may find it prudent to check this field to ensure that the e-gold^®payment was indeed made to the expected account number.

Also included on this form are the hidden text field/value pairs (if any) specified earlier by the BAGGAGE_FIELDS field value.

This Form is submitted using the POST method to the URL provided previously to e-gold^® system in the hidden text field called STATUS_URL. This URL is typically that of a cgi program that reads and acts upon the hidden text fields present on the form. It is likely that the program will store the order information and the e-gold transaction information for accounting purposes.

No response is expected from the merchant system when this form is submitted, however if any HTML is returned it is simply ignored and discarded. Note that the e-gold^®server is designed to resubmit the Payment Transaction Form until it obtains a valid http(s) status response (indicating a successful post) or until the configured retries have been exhausted. Because of this, under certain communication error conditions it may be possible for the Merchant’s server to receive a duplicate Payment Transaction Form.

Hidden Text Field Name	Hidden Text Field Value
PAYEE_ACCOUNT	Same value sent by merchant system
PAYMENT_ID	Same value sent by merchant system, or “NULL” if not sent by merchant.
PAYMENT_AMOUNT	Same value sent by merchant system
PAYMENT_UNITS	Same value sent by merchant system
PAYMENT_METAL_ID	Value 1,2,3, or 4 indicating actual metal (Gold, Silver, Platinum, Palladium) used in purchase.
PAYMENT_BATCH_NUM	The e-gold^®payment transaction Batch Number (32 bit nonzero positive integer)
PAYER_ACCOUNT	The Buyer’s e-gold^®Account number
HANDSHAKE_HASH	128 bit MD5 message digest value (formatted as 32 uppercase hex digits). See V2_HASH below for a more complete hash.
ACTUAL_PAYMENT_OUNCES	Actual weight of payment in troy ounces made in metal specified by PAYMENT_METAL_ID. Formatted to 6 decimal places. (0.000000)
USD_PER_OUNCE	Exchange Rate in effect for purchase. Given in US Dollars per ounce and formatted to 2 decimal places. (0.00)
FEEWEIGHT	The weight in ounces of the receive payment fee charged to the recipient of the payment (normally the merchant). This is the 1% of total weight capped at 50 cents maximum. This field, along with the field ACTUAL_PAYMENT_OUNCES can be used to calculate the NET weight received: NET_WEIGHT = ACTUAL_PAYMENT_OUNCES – FEEWEIGHT Formatted to 6 decimal places. (0.000000)
TIMESTAMPGMT	A time tag of when the transaction took place on the e-gold system. It delivered as the number of seconds since January 1, 1970 GMT (Greenwich Mean Time).
V2_HASH	128 bit MD5 message digest value (formatted as 32 uppercase hex digits)

Table 5: Hidden Text Fields Always Present on the Payment Transaction Form

3.1.1.1.1 The MD5 Hash Value

A hidden text field called “V2_HASH” is included on the payment form submitted to the merchant’s server. The value of this field is a 128 bit message digest, expressed as a string of thirty two hexadecimal digits in uppercase. The V2_HASH is constructed by performing an MD5 calculation on a string built up by concatenating the other fields returned to the STATUS_URL with inter-field delimiter of a ":" character, specifically the MD5 hash of :

PAYMENT_ID:PAYEE_ACCOUNT:PAYMENT_AMOUNT:PAYMENT_UNITS:PAYMENT_METAL_ID:PAYMENT_BATCH_NUM:PAYER_ACCOUNT:AlternateMerchantPassphraseHash:ACTUAL_PAYMENT_OUNCES:USD_PER_OUNCE:FEEWEIGHT:TIMESTAMPGMT

Important: If a PAYMENT_ID field is not provided by the merchant, use NULL as its value in the above string.

A merchant can validate the integrity of the data values received in the payment form by performing his own MD5 calculation on the same field values. If the merchant’s calculated MD5 value matches the V2_HASH field value then it’s fairly safe to assume that the payment form data is valid.

Example of V2_HASH

Assume input from merchant using e-gold account 123456 of:
PAYMENT_ID = AB-123
Has an alternate passphrase of “ohboyi’msogood1”.
This merchant receives a payment via the e-gold^®shopping cart for $300.00 USD worth of gold from e-gold account 456789. The values returned from the e-gold^®system to the merchant via his STATUS_URL input are:
PAYMENT_ID = AB-123
PAYEE_ACCOUNT = 123456
PAYMENT_AMOUNT = 300.00
PAYMENT_UNITS = 1
PAYMENT_METAL_ID = 1
PAYMENT_BATCH_NUMBER = 789012
PAYER_ACCOUNT = 456789
ACTUAL_PAYMENT_OUNCES = 2.000000
USD_PER_OUNCE = 600.00
FEEWEIGHT = 0.000833
TIMESTAMPGMT = 876543210

First we compute the MD5 hash of the merchants alternate passphrase. It is:
67C305DCE49D430D540FCB3D6D2E13B0
We can now build our concatenated string to hash for a comparison with the V2_HASH returned from e-gold^®. The concatenated string is:

AB-123:123456:300.00:1:1:789012:456789:67C305DCE49D430D540FCB3D6D2E13B0:2.000000:600.00:0.000833:876543210

When we perform an MD5 hash on this string we get:
7F8FAF7DB12315BC2B4B06E163F78D31
And that is the expected value that should arrive in the V2_HASH field from e-gold.

An earlier version of the hash field is also provided to maintain backward compatibility. It is not recommended to be used; use V2_HASH instead.

Old hash information:

A hidden text field called “HANDSHAKE_HASH” is included on the payment form submitted to the merchant’s server. The value of this field is a 128 bit message digest, expressed as a string of thirty two hexadecimal digits in uppercase. This 128-bit hash value represents the MD5 messages digest of the following values, concatenated together in the order shown:

a) PAYMENT_ID

b) PAYEE_ACCOUNT

c) PAYMENT_AMOUNT

d) PAYMENT_UNITS

e) PAYMENT_METAL_ID

f) PAYMENT_BATCH_NUM

g) PAYER_ACCOUNT

h) MD5 hash value of Payee’s e-gold emergency password.

3.1.1.2 Buyer Normal Return Form

Table 6 shows the hidden text fields that will always be present on the Buyer Normal Return Form sent to the merchant’s system by the buyer’s web browser.

Also included on this form are the hidden text field/value pairs (if any) specified earlier by the BAGGAGE_FIELDS field value.

This Form is submitted using the POST method to the URL provided previously to e-gold^®system in the hidden text field called PAYMENT_URL. This URL is typically that of a cgi program that reads and acts upon the hidden text fields present on the form and creates a web page to allow the buyer to complete the check-out process (since payment has been made).

Hidden Text Field Name	Hidden Text Field Value
PAYEE_ACCOUNT	Same value sent by merchant system
PAYMENT_AMOUNT	Same value sent by merchant system
PAYMENT_UNITS	Same value sent by merchant system
PAYMENT_METAL_ID	Value 1,2,3 or 4 indicating actual metal type (Gold, Silver, Platinum, or Palladium) using in purchase.
PAYMENT_BATCH_NUM	The e-gold payment transaction Batch Number (32 bit nonzero positive integer)
PAYER_ACCOUNT	The Buyer’s e-gold Account number

Table 6: Hidden Text Fields Always Present on the Buyer Normal Return Form

3.1.1.3 Buyer Alternate Return Form

Table 7 shows the hidden text fields that will always be present on the Buyer Alternate Return Form sent to the merchant’s system by the buyer’s web browser. In addition, in some cases the Buyer’s e-gold^®Account number may be present in a hidden text field.

Also included on this form are the hidden text field/value pairs (if any) specified earlier by the BAGGAGE_FIELDS field value.

This Form is submitted using the POST method to the URL provided previously to e-gold^®system in the hidden text field called NOPAYMENT_URL. This URL is typically that of a cgi program that reads and acts upon the hidden text fields present on the form and creates a web page to allow the buyer to select an alternative payment method to complete the check-out process (since payment has not yet been made).

Hidden Text Field Name	Hidden Text Field Value
PAYEE_ACCOUNT	Same value sent by merchant system
PAYMENT_AMOUNT	Same value sent by merchant system
PAYMENT_UNITS	Same value sent by merchant system
PAYMENT_METAL_ID	Same value sent by merchant.
PAYMENT_BATCH_NUM	Zero (0)

Table 7: Hidden Text Fields Always Present on the Buyer Alternate Return Form

Example Forms

This section provides several example forms for a hypothetical purchase made by James Bond from High-Tech Widgets:

a) an HTML Entry Form to illustrate how to interface to the e-gold^®payment system

b) a Payment Transaction Form such as that sent by the e-gold^®server to the merchant server when a payment has been made

c) a Buyer Normal Return Form such as that sent by a buyer’s browser to the merchant server when an e-gold^®payment has been made

d) a Buyer Alternate Return Form such as that sent by a buyer’s browser to the merchant server when no e-gold^®payment has been made for whatever reason

3.2 Example Entry Form Into the e-gold^®Payment System

The form presented in Figure 5 is an example of a merchant’s page for check-out on which the buyer selects the method of payment. The page is comprised of several independent forms, one for each possible payment method. For clarity, the forms for the Visa card and Discover card are merely stubs, however the form for selecting e-gold (shown in boldfaced font) as a payment method is complete and would be acceptable to the e-gold^®SCI system. Note the following in this example:

a) The purchase is for 109.99 US Dollars worth of Gold. The merchant has specified that only Gold is acceptable as payment since the PAYMENT_METAL_ID is set explicitly to 1 (Gold).

b) The merchant is using two “baggage fields” to maintain the state of the order. These are declared in the BAGGAGE_FIELDS field:

an order number (“ORDER_NUM”) of 9801121

a customer number (“CUST_NUM”) of 2067609

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">

<html>

<head>

content="text/html; charset=iso-8859-1">

<title>High Tech Widgets Check Out</title>

</head>

<p align="center"><font color="#000000" size="6"><strong>High

Tech Widgets Check Out</strong></font></p>

<p><font color="#000000" size="4">Select the Payment Method to

use for your purchase:</font></p>

<p><input type="submit" name="PAYMENT_METHOD"

value="Visa Card"></p>

</form>

<p><input type="submit" name="PAYMENT_METHOD"

value="Discover Card"></p>

</form>

<form action="https://www.e-gold.com/sci_asp/payments.asp" method="POST">

<p>

<input type="hidden" name="PAYEE_ACCOUNT" value="900123">

<input type="hidden" name="PAYEE_NAME" value="High Tech Widgets">

<input type="hidden" name="PAYMENT_AMOUNT" value="109.99">

<input type="hidden" name="PAYMENT_UNITS" value="1">

<input type="hidden" name="PAYMENT_METAL_ID" value="1">

<input type="hidden" name="STATUS_URL"

value="https://www.high-tech.com/cgi-bin/xact.exe">

<input type="hidden" name="PAYMENT_URL"

value="https://www.high-tech.com/cgi-bin/chkout1.exe">

<input type="hidden" name="NOPAYMENT_URL"

value="https://www.high-tech.com/cgi-bin/chkout2.exe">

<input type="hidden" name="BAGGAGE_FIELDS"

value="ORDER_NUM CUST_NUM">

<input type=”hidden” name=”ORDER_NUM” value=”9801121”>

<input type=”hidden” name=”CUST_NUM” value=”2067609”>

<input type="submit" name="PAYMENT_METHOD" value="e-gold account">

</p>

</form>

<p align="center"><input type="submit" name="CANCEL"

value="CANCEL"></p>

</form>

</body>

</html>

Figure 5: Example HTML Entry Form

a) If payment is made successfully, the transaction response form is to be submitted to the following URL: https://www.high-tech.com/cgi-bin/xact.exe

b) If payment is made successfully, the buyer’s browser will send an HTML form to URL: https://www.high-tech.com/cgi-bin/chkout1.exe

c) If payment is not made successfully or is cancelled, the buyer’s browser will send an HTML form to URL: https://www.high-tech.com/cgi-bin/chkout2.exe

3.3 Example Payment Transaction Form

Figure 6 shows how an example Payment Transaction Form might look for our hypothetical purchase by James Bond. The e-gold system would submit this form directly to the High Tech Widgets server to confirm Mr. Bond’s successful e-gold payment transaction. The value of the PAYMENT_BATCH_NUM field is the same confirmation number that Mr. Bond sees on the e-gold payment confirmation page.

<FORM ACTION="https://www.high-tech.com/cgi-bin/xact.exe" METHOD=”POST”>

<P>

<input type="hidden" name="PAYEE_ACCOUNT" value="900123">

<input type="hidden" name="PAYMENT_AMOUNT" value="109.99">

<input type="hidden" name="PAYMENT_UNITS" value="1">

<input type="hidden" name="PAYMENT_METAL_ID" value="1">

<input type="hidden" name="PAYMENT_BATCH_NUM" value="680">

<input type="hidden" name="PAYER_ACCOUNT" value="110007">

<input type=”hidden” name=”ORDER_NUM” value=”9801121”>

<input type=”hidden” name=”CUST_NUM” value=”2067609”>

<input type=”hidden” name=”USD_PER_OUNCE” value=”295.00”>

<input type=”hidden” name=”PAYMENT_ID” value=”NULL”>

<input type=”hidden” name=”ACTUAL_PAYMENT_OUNCES” value=”0.372847”>

</P>

</FORM>

Figure 6: Example Payment Transaction Form

3.4 Example Buyer Normal Return Form

An example Buyer Normal Return Form, based again upon our hypothetical James Bond purchase, is shown in Figure 7. This form would be sent by Mr. Bond’s browser to the merchant’s server once he successfully completed the e-gold payment process. Note that this form contains virtually the same information the Payment Transaction Form shown above, except it is sent to a different URL and is used to bring Mr. Bond’s browser back into the merchant’s shopping cart system to complete the check-out process.

<FORM ACTION="https://www.high-tech.com/cgi-bin/chkout1.exe" METHOD=”POST”>

<P>

<input type="hidden" name="PAYEE_ACCOUNT" value="900123">

<input type="hidden" name="PAYMENT_AMOUNT" value="109.99">

<input type="hidden" name="PAYMENT_UNITS" value="1">

<input type="hidden" name="PAYMENT_METAL_ID" value="1">

<input type="hidden" name="PAYMENT_BATCH_NUM" value="680">

<input type="hidden" name="PAYER_ACCOUNT" value="110007">

<input type="hidden" name="PAYMENT_ID" value="NULL">

<input type=”hidden” name=”ORDER_NUM” value=”9801121”>

<input type=”hidden” name=”CUST_NUM” value=”2067609”>

</P>

</FORM>

Figure 7: Example Buyer Normal Return Form

3.5 Example Buyer Alternate Return Form

An example Buyer Alternate Return Form, also based upon our hypothetical James Bond purchase, is shown in Figure 8. This form would be sent by Mr. Bond’s browser to the merchant’s server if he failed to complete the e-gold payment process for any reason. Note that this form contains almost the same information as the Buyer Normal Return Form shown above, except that the PAYMENT_BATCH_NUM is 0, which indicates that payment did not occur. Note too, that this form is submitted to a different URL to bring Mr. Bond’s browser back into the merchant’s shopping cart system where he can select another payment method. Finally, note that the buyer’s e-gold account number is not present on the form. This situation is possible when payment processing is terminated prior to a buyer’s entry of his e-gold^®account number.

<FORM ACTION="https://www.high-tech.com/cgi-bin/chkout2.exe" METHOD=”POST”>

<P>

<input type="hidden" name="PAYEE_ACCOUNT" value="900123">

<input type="hidden" name="PAYMENT_AMOUNT" value="109.99">

<input type="hidden" name="PAYMENT_UNITS" value="1">

<input type="hidden" name="PAYMENT_METAL_ID" value="1">

<input type="hidden" name="PAYMENT_BATCH_NUM" value="0">

<input type="hidden" name="PAYMENT_ID" value="NULL">

<input type=”hidden” name=”ORDER_NUM” value=”9801121”>

<input type=”hidden” name=”CUST_NUM” value=”2067609”>

</P>

</FORM>

Figure 8: Example Buyer Alternate Return Form

Testing Your e-gold^®Shopping Cart Interface

3.6 Methods of testing your SCI Setup

The recommended method of testing your is to use very small purchase amounts (e.g. 0.01 USD equivalent). This will allow you to prove SCI functionality with connectivity to the live e-gold site. Before live deployment, the PAYMENT_AMOUNT can then be upped to the actual value in your entry form.

For special case testing or advise, please contact sci@e-gold.com.

Date	Description of Changes	Affected Sections
January 25, 2001	Corrected currency ISO codes for CHF and FRF.	1.4.3.2
October 6, 2000	Modified email contact to be: sci@e-gold.com. Version 2 hash field (V2_HASH) added.	Cover, 4.1, 2.3.1.X
November 4, 1999	Remove any lingering obsolete “sendto:” in STATUS_URL. Must be “mailto:”. Clarify payment hash is uppercase and ACTUAL_PAYMENT_AMOUNT being is weight paid (and does not include fees).	2.3.1.1
June 22, 1999	Note 6 decimal places used on all weights. PAYMENT_METAL_ID returned in status reflects actual metal used. (i.e. 0 will not be returned).	2.3.1.X. Misc clean ups.
June 4, 1999	Updated testing section to not access demo server.	4.
April 2, 1999	Payment confirmation can now be sent to merchant via http(s) form POST, GET, or via e-mail. It can also be suppressed completely if desired. MD5 message digest of critical e-gold payment confirmation information is now sent with confirmation data for enhanced security.	Numerous
April 20, 1998	Document Released	Not applicable
April 19, 1998	Updated status of e-gold servers in terms of SCI support.	4.
February 6, 1998	Buyer’s e-gold account number is now returned in hidden text field.	3.1.1.1, 3.1.1.2, 3.1.1.3, 3.3, 3.4, 3.5

1.3 Overview of e-gold® Shopping Cart Interface

1.4 Entry Form into the e-gold® Payment System

1.5 Buyer Interaction With the e-gold® Payment System

3.1 e-gold® Payment System Interaction with Merchant System

3.2 Example Entry Form Into the e-gold® Payment System

Testing Your e-gold® Shopping Cart Interface

1.3 Overview of e-gold^®Shopping Cart Interface

1.4 Entry Form into the e-gold^®Payment System

1.5 Buyer Interaction With the e-gold^®Payment System

3.1 e-gold^®Payment System Interaction with Merchant System

3.2 Example Entry Form Into the e-gold^®Payment System

Testing Your e-gold^®Shopping Cart Interface