iGolds Automation Interface Specification

1. Introduction

2. Overview of iGolds Automation Interface

2.1. iGolds spend

2.2. iGolds account balance

2.3. iGolds account history

3. iGolds Automation Interface Details

3.1. Interface to iGolds spend

3.2. Interface to iGolds account balance

3.3. Interface to iGolds account history

4. Example iGolds Automation

4.1. Example to make iGolds spend

4.2. Example to display iGolds balance

4.3. Example to retrieve iGolds history

1. Introduction

This document describes how to programmatically interact with the iGolds web site (located at http://www.igolds.net). Interaction of this sort might be useful to those desiring to automate iGolds payments, check iGolds account balance, or verify a particular transaction has occurred. This document describes the fields and parameters required for interfacing to the iGolds system to perform these actions.

This document is intended to be utilized by technical personnel with programming knowledge; specifically with a working knowledge of HTML forms.

[Terminology]
AI: the Automation Interface is abbreviated with the acronym AI
User: the iGolds account holder, his/her account is used to call iGolds automation functions

2. Overview of iGolds Automation Interface

iGolds Automation Interface (AI) is a HTML forms-based interface that users can incorporate into their scripts/softwares to allow scripts/software to automactic spend, check balance, or retrieve history. The AI supports secure data transfer using Secure Sockets Layer (SSL).

AI includes several functions listed below:

2.1. iGolds spend

The iGolds spend is a transaction initiated by the owner of an iGolds account to transfer iGolds to another iGolds account. Normally, an iGolds spend is performed interactively by the account holder using a web (or PCS/WAP phone) browser to submit payment information via HTML (HDML/WML) form input. The user interested in automation of this task may require unattended spending, or repetitive spending without the manual data re-entry this would require using the browser method.

2.2. iGolds account balance

The iGolds account balance for a particular account is the current amount of available money held in the account. The balance is normally viewed using a browser. The user interested in automation of balance may wish to display their balance or derived information on their web site.

2.3. iGolds account history

The iGolds account history for a particular account contains all the transactions for the account. This act of viewing this history is normally performed interactively via a web browser. The user interested in automation of this task may require verification of a particular transaction (possibly an automated spend, or receipt of payment via the iGolds shopping cart interface [SCI]).

3. iGolds Automation Interface Details

In general, input fields are provided to the given URL via either an HTML form of the POST or GET variety. For instance a GET style request to retrieve the balance of iGolds account 10245 might look like:

https://www.igolds.net/ai_balance.html?IGS_ACCOUNT=10245&IGS_PASSWORD=mypassword

The data is returned in comma delimited format to the requestor. The balance, spend, and history URLs return result data in hidden fields embedded in normal HTML. For example, the above balance request might return:

......
<input type="hidden" name="IGS_BALANCE_RMB" value="789.57001">
<input type="hidden" name="IGS_BALANCE_USD" value="359.12000">
......

The caller can ignore all the HTML fields and pull out the return values from the hidden fields.

3.1. Interface to iGolds spend

3.1.1. The URL

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

3.1.2. The method of form

An iGolds spend may be performed by doing an HTML form post of GET or POST variety to the URL.

3.1.3. The input fields should be used

Field Name	Field Value and Usage
IGS_ACCOUNT	The user's iGolds account id from which the payment is to be made. Max 8 digits (e.g. 10245)
IGS_PASSWORD	The password to the user's iGolds account. Max 64 characters (e.g. mypassword)
IGS_PAYEE_ACCOUNT	The peyee's iGolds account id to which the payment is to be made. Max 8 digits (e.g. 10246)
IGS_CURRENCY	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	The amount of money is to be transfered. 2 digits to the right of the decimal point (e.g. 105.06)
IGS_PAYMENT_ID	[Optional] Payment id Max 16 digits (e.g. 20080205000191)
IGS_MEMO	[Optional] Memo. Once a successful payment completed, the value of the field will be in the history of payee's account and payer's account. Max 64 characters (e.g. Pay for the software)

3.1.4. The data returned

Output from the page will include HTML with embedded hidden form fields for retrieving results of the spend. These are:

Field Name	Field Value and Usage
IGS_ERROR	Text description of error. Spend did not occur if this field present. Text (e.g. IGS_ACCOUNT or IGS_PASSWORD is wrong)
IGS_TRANSACTION_ID	Transaction id. This field is not present if an error occured. Max 10 digits (e.g. 45678901)
IGS_PAYEE_ACCOUNT	The peyee's iGolds account id to which the payment was made. Max 8 digits (e.g. 10246)
IGS_PAYER_ACCOUNT	The peyer's iGolds account id from which the payment was made. Max 8 digits (e.g. 10245)
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 amount of money was transfered. 2 digits to the right of the decimal point (e.g. 105.06)
IGS_PAYMENT_ID	Payment id. Max 16 digits (e.g. 20080205000191)

3.2. Interface to iGolds account balance

3.2.1. The URL

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

3.2.2. The method of form

An iGolds account balance may be performed by doing an HTML form post of GET or POST variety to the URL.

3.2.3. The input fields should be used

Field Name	Field Value and Usage
IGS_ACCOUNT	The user's iGolds account id. Max 8 digits (e.g. 10245)
IGS_PASSWORD	The password to the user's iGolds account. Max 64 characters (e.g. mypassword)

3.2.4. The data returned

Output from the page will include HTML with embedded hidden form fields for retrieving results of the account balance. These are:

Field Name	Field Value and Usage
IGS_ERROR	Text description of error. An error occurs if this field present. Text (e.g. IGS_ACCOUNT or IGS_PASSWORD is wrong)
IGS_BALANCE_RMB	RMB balance. This field is not present if an error occured. 5 digits to the right of the decimal point (e.g. 789.57001)
IGS_BALANCE_USD	USD balance. This field is not present if an error occured. 5 digits to the right of the decimal point (e.g. 359.12000)

3.3. Interface to iGolds account history

3.3.1. The URL

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

3.3.2. The method of form

An iGolds account history may be performed by doing an HTML form post of GET or POST variety to the URL.

3.3.3. The input fields should be used

Field Name	Field Value and Usage
IGS_ACCOUNT	The user's iGolds account id. Max 8 digits (e.g. 10245)
IGS_PASSWORD	The password to the user's iGolds account. Max 64 characters (e.g. mypassword)
IGS_TRANSACTION_ID	Transaction id¡£The id is to be used to search transaction in account history records. Max 10 digits (e.g. 45678901)

3.2.4. The data returned

Output from the page will include HTML with embedded hidden form fields for retrieving results of the account history. These are:

Field Name	Field Value and Usage
IGS_ERROR	Text description of error. An error occurs if this field present. Text (e.g. IGS_ACCOUNT or IGS_PASSWORD is wrong)
IGS_TRANSACTION_ID	Transaction id Max 10 digits (e.g. 45678901)
IGS_CURRENCY	Currency: 1 means RMB, 2 means USD. 1 or 2 (e.g. 1)
IGS_AMOUNT	Amount of be spent. 5 digits to the right of the decimal point (e.g. 105.06000)
IGS_PAYEE_ACCOUNT	Payee's iGolds account id Max 8 digits (e.g. 10246)
IGS_PAYER_ACCOUNT	Payer's iGolds account id Max 8 digits (e.g. 10245)
IGS_TRANSACTION_TYPE	Type of this transaction. "send" means that the money was sent from the user's account, "receive" means that the money was sent to the user's account. Text (e.g. receive)
IGS_PAYMENT_ID	Payment id. Max 16 digits (e.g. 20080205000191)
IGS_DATE	Time of transaction in GMT. The format is YYYY-MM-DD hh:mm:ss 19 characters (e.g. 2008-01-29 18:04:39)
IGS_MEMO	Memo corresponding to this transaction. Max 64 characters (e.g. pay for the software)

4. Example iGolds Automation

4.1. Example to make iGolds spend

4.1.1. Example to make iGolds spend with the POST method

4.1.2. Example to make iGolds spend with the GET method

https://www.igolds.net/ai_payment.html?IGS_ACCOUNT=10245&IGS_PASSWORD=mypassword&IGS_PAYEE_ACCOUNT=10246&IGS_CURRENCY=1&IGS_AMOUNT=105.06

4.1.3. Example data returned

4.2. Example to display iGolds balance

4.2.1. Example to display iGolds balance with the POST method

4.2.2. Example to display iGolds balance with the GET method

https://www.igolds.net/ai_balance.html?IGS_ACCOUNT=10245&IGS_PASSWORD=mypassword

4.2.3. Example data returned

4.3. Example to retrieve iGolds history

4.3.1. Example to retrieve iGolds history with the POST method

4.3.2. Example to retrieve iGolds history with the GET method

https://www.igolds.net/ai_history.html?IGS_ACCOUNT=10245&IGS_PASSWORD=mypassword&IGS_TRANSACTION_ID=45678901

4.3.3. Example data returned