Merchant Tools

Shopping Cart Interface (SCI)

The Shopping Cart Interface is an easy way to accept HD-Money on your website with little or no coding experience necessary.

Setup

You can add as many SCI interfaces as you require.
First you need to login to your HD-Money Account and go to Merchant Tools then click the Create an SCI link. Fill in the simple form according to the following table:

Name	Description	Example Value
Name	The name you will use to call the SCI	`SCI01`
Security Word	This will be used as part of the Hash to secure the transaction	`8Tf4a84LDXlFtf`
Callback URL	This will be the url HD-Money will call to pass you the payment notification	`http://www.yoursite.com/payment_process.php`
Callback Method	The method that will be used when HD-Money accesses the Callback URL	`POST or GET`
Success URL	The url the user will be redirected to when a payment is complete	`http://www.yoursite.com/payment_success.html`
Failure URL	The url the user will be redirected to when a payment has failed or was incomplete	`http://www.yoursite.com/payment_failure.html`

How does it work?

Calling Form

The Shopping Cart Interface gives users a simple platform to start receiving payments on their website.
All you need is to create a form on your website based on the following example:

<form action="https://www.hd-money.com/sci/Payment.aspx" method="post">
    <input type="hidden" name="hd_recipient" value="HD1234567" />
    <input type="hidden" name="hd_sci_name" value="MySCI" />
    <input type="hidden" name="hd_amount" value="10" />
    <input type="hidden" name="hd_identifier" value="unique_id_1234" />
    <input type="hidden" name="hd_item_name" value="some good" />
    <input type="hidden" name="hd_description" value="something about the good" />
    <input type="hidden" name="hd_sender" value="HD7654321" />
    <input type="hidden" name="hd_callback_url" value="http://www.mywebsite.com/hd-processor.php" />
    <input type="hidden" name="hd_callback_method" value="post" />
    <input type="hidden" name="hd_success_url" value="http://www.mywebsite.com/payment-success.html" />
    <input type="hidden" name="hd_failure_url" value="http://www.mywebsite.com/payment-failure.html" />
    <input type="hidden" name="hd_var1" value="something" />
    <input type="hidden" name="hd_var2" value="8392" />
    <input type="submit" value="Pay Now!" />
</form>

The required fields are explained below:

Name	Required	Type	Description	Example Value
hd_recipient		string	Your HD-Money Account number, where the money will be sent to	`HD1234567`
hd_sci_name		string	Name of the SCI you defined in HD-Money Account	`MySCI`
hd_amount		decimal	The amount that will be sent with or without decimal values	`10`
hd_identifier		string	A unique identifier defining the product	`order19283`
hd_item_name		string	The name of the item or service that is being purchased	`some good`
hd_description		string	The description of the item	`something about the good`
hd_sender		string	The HD-Money Account number of the sender - If used, this will prevent the user from using an alternative account number	`HD7654321`
hd_callback_url		string	The URL used to communicate with your website	`http://www.mywebsite.com/hd-processor.php`
hd_callback_method		get/post	The method of communication you wish to use	`post`
hd_success_url		string	The URL on your website where users will be redirected when payment is complete	`http://www.mywebsite.com/payment-success.html`
hd_failure_url		string	The URL on your website where users will be redirected after a failed, incomplete or aborted payment	`http://www.mywebsite.com/payment-failure.html`
hd_varX		string	Up to 5 user-defined variables	`323,AM4,...`

Please note that the following fields can be set up in the SCI setup screen but can be overridden by the form:

hd_callback_url

hd_callback_method

hd_success_url

hd_failure_url

Callback

After the user has identified himself on the HD-Money website, he will need to confirm the payment and enter his PAK number to finalise the transaction.
Once the transaction is approved the HD-Money server will communicate details of the payment back to your own server using the Callback URL you provided in the SCI setup or in the form.
Depending whether you chose to have the data sent to you using the GET or POST methods, the following fields will be transmitted to you:

Name	Type	Description	Example Value
hd_sender	string	The HD-Money Account number of the Sender	`HD7654321`
hd_sender_name	string	The Name of the HD-Money Account that sent you the money	`MySCI`
hd_recipient	string	The HD-Money Account of the Recipient	`HD1234567`
hd_amount	decimal	The amount that has been sent to you, 2 decimal values	`10.00`
hd_identifier	string	The unique identifier you have set up	`item1033`
hd_sci_name	string	The name of the SCI that was used	`MySCI`
hd_transaction	string	The HD-Money transaction number for further reference	`00257431`
hd_hash	string	The Hash generated by the server to authenticate the transaction	`2e87567a54f2a0a5bb8ec463459f7933`
hd_varX	string	Any of the User defined variables you passed to HD-Money in the calling form	`323,AM4,...`

Validation checks

In order to make sure the data you received in your callback script is correct, you need to check that what you need to get from the server is the actual data you are waiting for.
For instance, you can confirm that the recipient account is indeed your own account, that the SCI used is the one you setup, etc. To enhance the security of the transaction, a Hash has been added to the variables posted.
This hash is built like so:

MD5(HDSender:HDRecipient:Amount:TransactionID:MD5(SecurityWord))

HDSender and HDRecipient are the HD-Money Account numbers for both the sender and recipient (all uppercase); the Amount has 2 decimal values no matter what amount is sent - eg. 3.00; TransactionID is the 8 character string Transaction Number generated by the HD-Money Server
The Hash of the Security word is then appended.
A practical example would be as follows:

HD Sender: HD58725510
HD Recipient: HD81253018
Amount: 2.53
Transaction ID: 00257431
Security Word for this SCI: BgssTZmOByWJGj

Security Word MD5 Hash: 35b5407f3f25baa2502244a094f1ae6d
Prepared string: HD58725510:HD81253018:2.53:00257431:35b5407f3f25baa2502244a094f1ae6d

Final MD5 Hash: 8abeef35bf8a53858bf2dc57338f64f5

Building the MD5 Hash on your site and verifying that it matches the one coming from HD-Money is a good way of confirming that the transaction is genuine. Of course you should check as many parameters as possible to ensure tight security.

Back to your site

Once a transaction has been successfully completed and the Success URL has been set on the SCI, users will be redirected to your site. If you omit this URL, users will stay on the HD-Money website.
Same goes for the Failure URL, if there was a problem or if the user decides not to proceed with the transaction, they will be redirected to your site if this is set.

Application Programming Interface (API)

The HD-Money API™ uses the XML messaging system between the client and the server for both the Request and the Response. The message protocol must be strictly followed, to ensure successful operation.

What is it?

With the HD-Money API™ you can perform several operations from your HD-Money Account. You can transfer funds from your account to any other HD-Money account, check your balances or check an account.

API Setup

To begin, login to your HD-Money Account, select Merchant Tools and then click the Create an API link. You will be redirected to a simple form to complete.
The API will be set up using:

a Name, which will be referenced by the Request
a Security Word (that can be auto-generated by the site). Choose you security word wisely:
- the longer the security word is the more secure it will be
- avoid common words
if you want to be able to transfer money with this API, please choose which balance to use
if you want to check your balances or verify another HD-Money Account, tick the relevant boxes
for additional security, you can bind the IP (this feature is optional). This will restrict API to the IP provided
make sure the Enabled check-box is checked
enter your PAK to confirm

Your new API is ready to use.

Each HD-Money API call is made to a particular script on the website, please refer to each API for explanation and example.
Please be aware that the server uses SSL™ and will not accept your request if it does not start with https://
The XML Request needs to be passed to each of the scripts using the xmlData parameter. We recommend using the POST method to transfer the XML Request but the GET method will work as well.

Constructing a Request

The HD-Money API uses a different XML structure for each different operation you wish to perform. However the authentication part is common to all the API calls.

Authentication

The Authentication on the HD-Money API requires 3 fields which are your HD-Money Account number, the API Name you created and a MD5 Hash Key.
The XML is defined as follow:

<Auth>
    <Account>HD1234567</Account>
    <ApiName>MyAPI</ApiName>
    <Key>538fe9ea6e50fc6b276b12c9a0b91ae2</Key>
</Auth>

The following table explains the fields required for the authentication to work

Name	Type	Description	Example Value
Account	string	Your HD-Money Account number	`HD1234567`
APIName	string	Name of the API you defined in HD-Money Account	`MyAPI`
Key	string	MD5 hash	`538fe9ea6e50fc6b276b12c9a0b91ae2`

The MD5 Hash Key has been put in place to make your API call secure. It is simply created by using:

MD5(SecurityKeyWord:UTC Month:UTC Day:UTC Hour)

The Hour and Minute are in UTC format; the full MD5 Hash should be lowercase.
As an example, using the security word Secured123Api and the day is 4^th of June 2010 - 16:37:51 GMT the hash would be constructed as MD5("Secured123API:6:4:16") which gives 5e9b325dd71c8646d3336d234427e0e5

Transfer some money

The HD-Money API can be used to tansfer money from your account to other HD-Money Account holders.
To call this API, you need to send your request to https://www.hd-money.com/api/HDTransfer.ashx?xmlData=<xml request>

<HdmApiRequest>
    <Auth>
        <Account>HD1234567</Account>
        <ApiName>MyAPI</ApiName>
        <Key>538fe9ea6e50fc6b276b12c9a0b91ae2</Key>
    </Auth>
    <Transfers>
        <Transfer>
            <To>HD7654321</To>
            <Amount>3.14</Amount>
            <TransferId>order01</TransferId>
            <Memo>Payment for something</Memo>
        </Transfer>
        <Transfer>
            <To>HD6373872</To>
            <Amount>20</Amount>
            <TransferId>order02</TransferId>
            <Memo>Payment for something else</Memo>
        </Transfer>
        ...
    </Transfers>
</HdmApiRequest>

The API protocols allows you to send multiple payments to multiple recipients with just one call. The following table explains what the different elements are:

Name	Type	Description	Example Value
Auth	See Authentication
To	string	HD-Money Account number of the recipient	`HD7654321`
Amount	decimal	Amount to be sent to the recipient, 2 decimal values	`3.14`
TransferId	string	Your custom identifier	`order01`
Memo	string	If you wish to add a Memo to the transaction	`Payment for something`

The HD-Money response generated will be in XML format with the following structure:

<HdmApiResponse>
    <StatusCode>0</StatusCode>
    <Transfers>
        <Transfer>
            <StatusCode>0</StatusCode>
            <From>HD1234567</From>
            <To>HD7654321</To>
            <Date>17/03/2010 23:53:12</Date>
            <Amount>3.14</Amount>
            <Balance>85.74</Balance>
            <AccountType>HDM</AccountType>
            <TransferId>order01</TransferId>
            <TransactionId>000002491</TransactionId>
            <Memo>Payment for something</Memo>
        </Transfer>
        <Transfer>
            <StatusCode>0</StatusCode>
            <From>HD1234567</From>
            <To>HD6373872</To>
            <Date>17/03/2010 23:53:13</Date>
            <Amount>20</Amount>
            <Balance>65.74</Balance>
            <AccountType>HDM</AccountType>
            <TransferId>order02</TransferId>
            <TransactionId>000002492</TransactionId>
            <Memo>Payment for something else</Memo>
        </Transfer>
        ...
    </Transfers>
</HdmApiResponse>

Each Transfer element in the request has a matching Transfer element in the Response. The Request Status indicates the outcome of the request. Please check the API Status Codes table for a full list Status codes.
The following table explains response elements:

Name	Type	Description	Example Value
StatusCode	integer	Status Code from the API core or one of the transfers	`0`
From	string	HD-Money Account number of the sender (you!)	`HD1234567`
To	string	HD-Money Account number of the recipient	`HD7654321`
Date	datetime	Date Time of the transaction in UTC Format	`17/03/2010 23:53:12`
Amount	decimal	Amount to be sent to the recipient, 2 decimal values	`3.14`
Balance	decimal	The Balance from your account after the transaction has been completed, 2 decimal values	`85.74`
TransferId	string	Your custom identifier	`order01`
TransactionId	string	The ID of the transaction that was created in the System	`000002491`
Memo	string	If you wish to add a Memo to the transaction	`Payment for something`

Check your balance

The HD-Money API allows you to quickly check your balances in a quick call. You simply need to authenticate yourself using the following XML (refer to the Authentication part) and send it to https://www.hd-money.com/api/HDBalance.ashx?xmlData=<xml request>

<HdmApiRequestBalance>
    <Auth>
        <Account>HD1234567</Account>
        <ApiName>MyAPI</ApiName>
        <Key>538fe9ea6e50fc6b276b12c9a0b91ae2</Key>
    </Auth>
</HdmApiRequestBalance>

The HD-Money response generated will be in XML format with the following structure:

<HdmApiResponseBalance>
    <StatusCode>0</StatusCode>
    <HdmBalance>13.65</HdmBalance>
    
</HdmApiResponseBalance>

Name	Type	Description	Example Value
StatusCode	integer	Status Code from the API call	`1`
HdmBalance	decimal	Your HDM Balance, 2 decimal values	`13.65`

Verify an Account

The HD-Money API allows you to verify the name of any HD-Money account. Send the following XML to https://www.hd-money.com/api/HDVerify.ashx?xmlData=<xml request>

<HdmApiRequestVerify>
    <Auth>
        <Account>HD1234567</Account>
        <ApiName>MyAPI</ApiName>
        <Key>538fe9ea6e50fc6b276b12c9a0b91ae2</Key>
    </Auth>
    <HdAccountNo>HD7654321</HdAccountNo>
</HdmApiRequestVerify>

The HD-Money response generated will be in XML format with the following structure:

<HdmApiResponseVerify>
    <StatusCode>0</StatusCode>
    <HdAccountName>Test Account</HdAccountName>
</HdmApiResponseVerify>

Name	Type	Description	Example Value
StatusCode	integer	Status Code from the API call	`1`
HdAccountName	string	The Account name tied to the HD-Money Account	`Test Account`

Get Transaction History

You can get the Transaction History using the HD-Money API. Sending the following XML to https://www.hd-money.com/api/HDHistory.ashx?xmlData=<xml request> will generate a list of the last 10 transactions made on your account.

<HdmApiRequestHistory>
    <Auth>
        <Account>HD1234567</Account>
        <ApiName>MyAPI</ApiName>
        <Key>538fe9ea6e50fc6b276b12c9a0b91ae2</Key>
    </Auth>
</HdmApiRequestHistory>

It is possible to refine the results using a set of filters, each mutually exclusive:

<HdmApiRequestHistory>
    <Auth>
        <Account>HD1234567</Account>
        <ApiName>MyAPI</ApiName>
        <Key>538fe9ea6e50fc6b276b12c9a0b91ae2</Key>
    </Auth>
    <Filter>
        <DateFrom>6/11/2010</DateFrom>
        <DateTo>6/15/2010</DateTo>
        <Direction>in</Direction>
        <AccountType>hdm</AccountType>
        <Status>completed</Status>
        <Method>api</Method>
        <WithAccount>HD7654321</WithAccount>
        <TransactionId>00022342</TransactionId>
        <Count>15</Count>
    </Filter>
</HdmApiRequestHistory>

Please note that these filters are optional and mutually exclusive:

Name	Type	Description	Example Value
Auth	See Authentication
DateFrom	date	The date you want to check your history from	`6/11/2010`
DateTo	date	The date you want to check your history up to	`6/18/2010`
Direction	TO/FROM	Determine whether the transactions to retrieve should be incoming or outgoing transfers	`TO or FROM`
Method	string	The Method that was used to do the transactions	`WEB or API or SCI`
WithAccount	string	HD-Money Account Number you made transactions to or from	`HD7654321`
TransactionId	string	HD-Money Transaction ID - 8 digits	`00022342`
Count	integer	How many transactions to be returned in the response	`15`

The HD-Money response generated will be in XML format with the following structure:

<HdmApiResponseHistory>
    <StatusCode>0</StatusCode>
    <Transactions>
        <Transaction>
            <From>HD1234567</From>
            <To>HD7654321</To> 
            <DateTime>18/06/2010 21:20:13</DateTime> 
            <Amount>1.37</Amount> 
            <NetAmount>1.35</NetAmount> 
            <TransactionId>00510114</TransactionId> 
            <AccountType>hdm</AccountType> 
            <TransactionStatus>Completed</TransactionStatus> 
            <Method>api</Method> 
            <Memo>This is an API transaction</Memo> 
        </Transaction>
        ...
    </Transactions>
</HdmApiResponseHistory>

Name	Type	Description	Example Value
StatusCode	integer	Status Code from the API call	`1`
From	string	The HD-Money Account number that sent the payment	`HD1234567`
To	string	The HD-Money Account number that received the payment	`HD7654321`
DateTime	datetime	The date & time of the transaction	`18/06/2010 21:20:13`
Amount	decimal	The Amount of the transfer, 2 decimal values	`1.35`
NetAmount	decimal	The Net Amount of the transfer, 2 decimal values	`1.35`
TransactionId	string	The HD-Money Transaction ID generated by the server	`00510114`
AccountType	string	The type of transaction made	`hdm`
TransactionStatus	string	The Status of the Transaction that was made	`Completed`
Method	string	The Method that was used to make the transfer	`api`
Memo	string	If the a Memo has been entered during the transaction	`This is a Memo`

Additionally, the Shopping Cart Interface (SCI) transactions will return the following 3 fields:

Name	Type	Description	Example Value
ItemName	string	The ItemName specified from the Form	`Purchase 123`
Identifier	string	The unique identifier referencing an item on your site	`order122434`
Description	string	The description of the item/service being purchased	`A beautiful red bus-shaped teapot`

Status Codes

The API Status Codes will help with troubleshooting. Below is the list of API status codes used by the HD-Money API:

Code	Description
`0`	No errors to report
`101`	The HD-Money Account used was not found or is invalid
`102`	The HD-Money Account is not active
`103`	The API could not be found for this HD-Money Account
`104`	The API is not Enabled
`105`	Hash Key invalid (read more on authentication)
`106`	The API is bound to an IP address which was not matched
`107`	Error parsing the Authentication section of the XML Request
`108`	Error parsing the XML Request
`201`	The requested Operation is not enabled in your API
`202`	The recipient Account could not be found
`203`	The recipient Account is disabled
`204`	You do not have enough money to perform this transfer
`205`	The Memo field is longer than 50 characters
`206`	Error Parsing the XML Transfer section
`207`	Error saving the Transaction
`208`	The same HD-Money Account is used for recipient and sender
`209`	API Verify Account failed - HD-Money Account not found
`210`	API Balance failed
`211`	API History failed