iGolds.net - Shopping Cart Interface Specification

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

The iGolds Shopping Cart Interface interacts with a merchant's Web server as shown in Figure 1:

This simplistic figure shows how an online buyer is diverted from the merchant's normal shopping cart web server to the iGolds web server to accomplish (or abort) an iGolds payment to the merchant. The basic scheme is explained here, however a more detailed description is provided in subsequent sections of this document. All of the buyer's web browser communications with the iGolds server are secure since they are encrypted using the Secure Sockets Layer (SSL).

To interface to the iGolds payment system using the Shopping Cart interface, a merchant must modify his current check out process to include iGolds as a payment method. Then, when a buyer selects iGolds as a payment method during check out, he is actually submitting an HTML form containing purchase information to the iGolds Web server (Step 1 in figure 1). The submitted form tells the iGolds system the merchant's iGolds 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 iGolds system then provides a user interface via HTML forms (see Figure 1) to the buyer to allow the payment transaction to be completed or aborted. The iGolds 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, depending upon whether the payment transaction was successful or unsuccessful/cancelled by the buyer (Steps 2 or 3 respectively in Figure 1).

Additionally, Once a successful payment is made to the merchant by the buyer, payment information can be submitted (POST or GET method) directly by the iGolds 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.

To support Merchant validation of the critical payment information, the iGolds server generates an SHA1 hash value from the critical payment data and a "shared secret" and includes this hash along with the payment information. Merchant's web server checks the received SHA1 hash value against the expected SHA1 hash value, if the SHA1 hash values match, the Merchant can be fairly confident that the payment confirmation information originated from the iGolds server and the payment data was received as it was sent by the iGolds server (no data tampering took place).

Payment confirmation information is not sent when a payment is aborted or fails.

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 iGolds system and vice-versa.

3. Shopping Cart Interface Details

To gain access to the iGolds payment system a merchant must first modify his shopping cart checkout system to include iGolds as a possible payment method. The payment method selection for iGolds 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 iGolds web server when clicked/chosen by a buyer.

The form thereby submitted to the iGolds web server by the buyer's web browser contains sufficient data to fully describe the current purchase to the iGolds payment system. This form also contains other hidden text fields to control how the iGolds server interacts with the Merchant's server(s) once payment is completed or aborted. This form is called the SCI Entry Form.

3.1. Entry Form into the iGolds Payment System

3.1.1. Entry Form ACTION

The Merchant must set his/her form ACTION to:

https://www.igolds.net/sci_payment.html

This is a secure (Secure Sockets Layer) link to the Active Server Page on the iGolds Web server that handles shopping cart interface (SCI) payments.

3.1.2. Entry Form METHOD

The Merchant may set his/her form METHOD to GET or POST.

3.1.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.

Required and Associated Optional Hidden Text Fields:

Field Name	Field Value and Usage
IGS_PAYEE_ACCOUNT	The merchant's iGolds account id to which the payment is to be made. Max 8 digits (e.g. 123456)
IGS_CURRENCY	[Optional] The numeric code for the currency in which the payment is to be made. 1 means RMB, 2 means USD. 1 or 2 (e.g. 1)
IGS_AMOUNT	[Optional] The total amount of the purchase 2 digits to the right of the decimal point (e.g. 105.06)
IGS_PAYMENT_ID	[Optional] Payment id. The value of this field can be used by the merchant for the order number, invoice identifier or any other reference number. This field is included in the SHA1 message digest sent with payment acknowledgement. Max 16 digits (e.g. 20080205000191)
IGS_PAYER_ACCOUNT	[Optional] The buyer's iGolds account id from which the payment is to be made. Max 8 digits (e.g. 234567)
IGS_VERIFY_URL	[Optional] The URL to which a payment information is submitted as an HTML form. The form is submitted to the URL with the POST method by the iGolds server upon successful completion of an iGolds 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. The URL starting with http:// or https:// (e.g. http://www.myonlineshop.com/order_process.cgi or https://www.myonlineshop.com/order_process.cgi)
IGS_SUCCESS_URL	[Optional] The URL to which a payment status is submitted as an HTML form. The form is submitted to the URL with the POST method by the iGolds server upon successful completion of an iGolds payment. This URL can specify a secure protocol such as https. The URL starting with http:// or https:// (e.g. http://www.myonlineshop.com/payment_success.cgi or https://www.myonlineshop.com/payment_success.cgi)
IGS_FAIL_URL	[Optional] The URL to which a payment status is submitted as an HTML form. The form is submitted to the URL with the POST method by the iGolds server upon an unsuccessful or cancelled iGolds payment to the merchant. This URL can specify a secure protocol such as https. The URL starting with http:// or https:// (e.g. http://www.myonlineshop.com/payment_fail.cgi or https://www.myonlineshop.com/payment_fail.cgi)
IGS_MEMO	[Optional] Memo. Once a successful payment completed, the value of the field will be in the history of machant's account and payer's account. Max 64 characters (e.g. Pay for the software)

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, SKU Number, etc. Optional field name/value pairs are carried along by the iGolds system during the payment process and eventually passed back to the merchant's web site with their original values intact.

An optional field name must start with IGS_CUSTOM_, e.g. IGS_CUSTOM_ORDERNUMBER

3.2. Buyer Interaction With the iGolds Payment System

Once the buyer's browser has submitted the initial form to the iGolds payment system, the user interface seen by the buyer is quite similar to the normal iGolds payment process. An outline of the process is described below:
1) An iGolds Payment Form similar to that shown in Figure 3 appears:

This form allows the buyer to enter his/her iGolds account id and password to authorize the payment.

. If the IGS_CURRENCY field is not specified by the merchant, the payer is required to choice a currency in which the payment is to be made.
. If the IGS_AMOUNT field is not specified by the merchant, the payer is required to enter amount of the purchase.
. If the IGS_PAYER_ACCOUNT field is not specified by the merchant, the payer is required to enter his/her iGolds account id.
. If the IGS_MEMO field is not specified by the merchant, the payer is allowed to enter an optional memo about the payment.

Once the buyer has completed the form he/she can then elect to click the Pay 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 to a URL (specified by the IGS_FAIL_URL field). This URL is predefined by the merchant to specify a web page or a cgi program or other HTML form processor program to handle the buyer's transition back into the merchant's shopping cart check-out area.

If the Pay button is clicked, the Payment Form is submitted to the iGolds web server. Assuming no error conditions are encountered, the iGolds system presents the buyer with the Payment Confirmation Page:

2) An iGolds Payment Confirmation Page similar to that shown in Figure 4 appears:

This page displays the following information:

. Payee's account id and account name
. Payer's account id and account name
. Currency in which the payment is to be made
. Amount to be deducted from payer's iGolds account if the payment transaction is confirmed
. Memo

If the buyer clicks the Confirm button, a specified amount of money is to be sent to payee's account from payer's account, the iGolds system presents the buyer with the Payment Completion Page and sends a payment receipt to the Payee's e-mail address. If the buyer elects to cancel the payment process at any point, his/her clicking on the Cancel button causes his/her web browser to submit a form to the URL specified by the IGS_FAIL_URL field. This is the alternate return path into the merchant's system.

3) An iGolds Payment Completion Page similar to that shown in Figure 5 appears:

This page displays the following information:

. Transaction id
. Payee's account id and account name
. Payer's account id and account name
. Amount sent
. Currency in which the payment was made
. Memo

3.3. iGolds Payment System Interaction with Merchant System

The iGolds 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 iGolds Payment System interacts in these ways:

1) 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 (specified by the IGS_VERIFY_URL field).
2) Once payment has been made it returns the Buyer to a Merchant-specified web page (specified by the IGS_SUCCESS_URL field).
3) If payment was not made for any reason it returns the Buyer to a Merchant-specified web page (specified by the IGS_FAIL_URL field).

3.3.1. Payment Notification Form Sent to the Merchant System

Once payment has been made, iGolds payment system posts a payment notification form to the Merchant-specified CGI (specified by the IGS_SUCCESS_URL field). The Merchant-specified CGI should verify the payment notification information, if everything is right the Merchant processes advanced actions such as shiping, adding credits to buyer's account, etc.

Hidden text fields are used to convey information about the payment notification information as explained below.

Field Name	Field Value and Usage
IGS_PAYEE_ACCOUNT	The payee's iGolds account id to which the payment was made. Max 8 digits (e.g. 123456)
IGS_CURRENCY	The numeric code for the currency in which the payment was made. 1 means RMB, 2 means USD. 1 or 2 (e.g. 1)
IGS_AMOUNT	The total amount of the money sent. 2 digits to the right of the decimal point (e.g. 105.06)
IGS_TRANSACTION_ID	Transaction id. Max 10 digits (e.g. 45678901)
IGS_PAYMENT_ID	Payment id, from the field IGS_PAYMENT_ID on SCI Entry Form. Max 16 digits (e.g. 20080205000191)
IGS_PAYER_ACCOUNT	The buyer's iGolds account id from which the payment was made. Max 8 digits (e.g. 234567)
IGS_TIME_STAMP	A time tag of when the transaction took place on the iGolds system. It delivered as the number of seconds since January 1, 1970 GMT. 10 digits (e.g. 1204112062)
IGS_HASH	SHA1 hash value of the payment information. For details see validate the Payment Notification Form. 40 uppercase hexadecimal digits (e.g. BCD2260A690BA11CDB26A76674EFB16EC193CBCD)
IGS_CUSTOM_*	Merchant-specific fields. From SCI Entry Form.

Validate the Payment Notification form

A hidden text field called "IGS_HASH" is included on the payment notification form submitted to the merchant's server, the merchant may use the value of the field to validate the payment notification form.

IGS_HASH is constructed by iGolds Payment System, the value of this field is a 160 bit message digest, expressed as a string of 40 hexadecimal digits in uppercase. The IGS_HASH is constructed by performing an SHA1 calculation on a string built up by concatenating the other fields returned to the IGS_VERIFY_URL with inter-field delimiter of a "," character, specifically the SHA1 hash (in uppercase) of:

IGS_PAYEE_ACCOUNT,IGS_CURRENCY,IGS_AMOUNT,IGS_TRANSACTION_ID,IGS_PAYMENT_ID,IGS_PAYER_ACCOUNT,IGS_TIME_STAMP,PASS2

PASS2 is the merchant's Merchant Password.

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

Example of IGS_HASH

Assume input from merchant using iGolds account 123456 of:
IGS_PAYMENT_ID = 20080205000191
Has an merchant password of "my store".
This merchant receives a payment via the iGolds shopping cart for 105.06 RMB from iGolds account 234567. The values returned from the iGolds system to the merchant via his IGS_VERIFY_URL input are:

IGS_PAYEE_ACCOUNT = 123456
IGS_CURRENCY = 1
IGS_AMOUNT = 105.06
IGS_TRANSACTION_ID = 45678901
IGS_PAYMENT_ID = 20080205000191
IGS_PAYER_ACCOUNT = 234567
IGS_TIME_STAMP = 1204112062

First We build our concatenated string to hash for a comparison with the IGS_HASH returned from iGolds. The concatenated string is:

123456,1,105.06,45678901,20080205000191,234567,1204112062,my store

When we perform an SHA1 hash on this string we get:

480BA5330E954B14CFCD7520E837AE32180A5263

And that is the expected value that should arrive in the IGS_HASH field from iGolds.

3.3.2. Payment Return Form

Hidden text fields that will always be present on the Payment Return Form sent to the merchant's system by the buyer's web browser. This Form is submitted using the POST method to the URL provided previously to iGolds system in the hidden text field called IGS_SUCCESS_URL (if payment has been made) or in the hidden text field called IGS_FAIL_URL (if payment has been canceled or failed). 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.

Hidden text fields are used to convey information about the payment Return form as explained below.

Field Name	Field Value and Usage
IGS_STATUS_SUCCESS	The numeric code for the payment made. 1 means that the payment has been made, 0 means that the payment has been cancel or failed. 0 or 1 (e.g. 1)
IGS_PAYEE_ACCOUNT	The payee's iGolds account id to which the payment was made. Max 8 digits (e.g. 123456)
IGS_CURRENCY	The numeric code for the currency in which the payment was made. 1 means RMB, 2 means USD. 1 or 2 (e.g. 1)
IGS_AMOUNT	The total amount of the money sent. 2 digits to the right of the decimal point (e.g. 105.06)
IGS_TRANSACTION_ID	Transaction id. Tt's 0 if the value of the field IGS_STATUS_SUCCESS is 0 Max 10 digits (e.g. 45678901)
IGS_PAYMENT_ID	Payment id, from the field IGS_PAYMENT_ID on SCI Entry Form. Max 16 digits (e.g. 20080205000191)
IGS_PAYER_ACCOUNT	The buyer's iGolds account id from which the payment was made. Max 8 digits (e.g. 234567)
IGS_CUSTOM_*	Merchant-specific fields. From SCI Entry Form.

4. Example Forms

4.1. Example Entry Form Into the iGolds Payment System

4.1.1. Example Entry Form Into the iGolds Payment System with POST method

4.1.2. Example Entry Form Into the iGolds Payment System with GET method

https://www.igolds.net/sci_payment.html?IGS_PAYEE_ACCOUNT=123456&IGS_CURRENCY=1&IGS_AMOUNT=105.06

4.2. Example Payment Notification Form

4.3. Example Payment Return Form

4.3.1. Example Payment Return Form for a successful payment

4.3.2. Example Payment Return Form for a failed/canceled payment