Figure 1: Simplistic View of Shopping Cart Interface.............................................................. 3

Figure 2: Top-Level SCI Diagram.......................................................................................... 4

Figure 3: Example Payment Order Form.............................................................................. 11

Figure 4: Example Payment Confirmation Page..................................................................... 12

Figure 5: Example HTML Entry Form.................................................................................. 20

Figure 6: Example Payment Transaction Form...................................................................... 21

Figure 7: Example Buyer Normal Return Form..................................................................... 22

Figure 8: Example Buyer Alternate Return Form................................................................... 22

LIST OF TABLES

Table 1: Required and Associated Optional Hidden Text Fields.............................................. 8

Table 2: Supported Payment Units......................................................................................... 9

Table 3: Payment Metals...................................................................................................... 10

Table 4: Forms Sent Back to Merchant System.................................................................... 13

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

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

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

Date	Description of Changes	Affected Sections
April 5, 2007	Add currencies: XAF (CFA Franc BEAC), XOF (CFA Franc BCEAO).	Table 2
September 23, 2004	Modified contact instructions (email).	Cover, changes, 3.6
January 10, 2003	Search and destroy on lingering typos. Incorporated up front notes into main document body. Added a Security Guidelines section.	Various. 3.8
December 23, 2001	Additional currencies for spend denominations including EUR.	Table 2
June 21, 2001	Optional FORCED_PAYER_ACCOUNT and SUGGESTED_MEMO input fields added.	Table 1
April 23, 2001	Reference to MD5 checking page (https://www.e-gold.com/acct/md5check.html) added.	3.1.1.1.1
January 25, 2001	Corrected currency ISO codes for CHF and FRF.	1.4.3.2
October 6, 2000	Modified email contact. 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

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