GoldMoney's Online Merchant Interface

Home

Why Buy Gold & Silver?

Online Merchant Interface

Revision History
Version	Date	Description
2.0	2004-Oct-29	Released version 2.0 of the OMI, with the following major improvements and changes compared to the previous release (1.5): An OMI log is now available to merchants with which they can keep track of OMI-related activity in their Holdings. This log is accessible after logging in to a Holding. The OMI no longer performs a "test ping" prior to sending the Payment Notification Form to the merchant system. The primary reason for deactivating this is that the OMI log enables troubleshooting. GoldMoney now has to authorise the use of the OMI for a particular Holding, and can also limit access so that only test payments can be performed via the OMI for that Holding. The maximum length of the Result URL, Success URL and Fail URL has now been increased to 255 characters each. The URL of the main OMI page has been changed from https://www.goldmoney.com/omi/omipmt.asp to https://secure.goldmoney.com/omi/omipmt.php (this must be set on the merchant's checkout page). Since a storage fee (now called a vault fee) is no longer charged when a payment is made, it has been removed from the Payment Notification Form, and is also no longer included in the payment details that are hashed and sent to the merchant system. The Holding numbers sent in the email (when the Result URL is an email address) are now masked for security reasons. If the merchant's checkout page "identifies itself" to the OMI via the HTTP referrer field, its URL will be included as a new field on the Payment Success and Payment Failure forms. If the checkout page does not "identify itself", then this URL will be set to the home page URL of GoldMoney. A merchant can now control whether or not the OMI should verify the certificate issuer and the common name in the certificate if the Payment Notification Form is sent to the Result URL via HTTPS.

Index

List of Figures
List of Tables

1. Introduction
1.1 Registered Trademarks
1.2 Audience
1.3 Terminology
1.4 Design Principles

2. Online Merchant Interface Process

3. Online Merchant Interface Details
3.1 Merchant Holding OMI Properties
3.2 HTML Forms
3.2.1 Payment Request Form
3.2.2 Payment Notification Form
3.2.3 Payment Success Form
3.2.4 Payment Failure Form
3.3 Validation of Critical Payment Information
3.3.1 Verify Payment Notification Source
3.3.2 Verify Integrity of Payment Notification Details
3.3.3 Verify Amount Received
3.3.4 Verify Payee Holding Number
3.3.5 Verify Real or Simulated Payment
3.3.6 Conclusion

4. Online Merchant Interface Testing

Appendix A. Hash Algorithms
Appendix A.1 Message Digest 5 (MD5)
Appendix A.2 Secure Hash Algorithm (SHA-1)

List of Figures

Figure 1: GoldMoney Online Merchant Interface

List of Tables

Table 1: Merchant Holding OMI Properties
Table 2: Payment Request Form Fields
Table 3: Currency Codes
Table 4: Payment Notification Form Fields
Table 5: Payment Success Form Fields
Table 6: Payment Notification Details Hash Fields Example
Table 7: Controlling Simulated Payments

1. Introduction

The objective of this document is to provide an overview of the GoldMoney Online Merchant Interface, as well as to explain in detail how to integrate a merchant's existing web site with this interface to enable the merchant to offer customers the ability to pay for products and/or services in GoldGrams.

1.1 Registered Trademarks

The GoldMoney name and the GoldGram currency are registered trademarks of GoldMoney.com.

1.2 Audience

This document is aimed at the technical personnel who will perform the integration of a merchant's web site with the GoldMoney Online Merchant Interface.

1.3 Terminology

GoldMoney Merchant: A GoldMoney merchant is defined as the owner of a GoldMoney Holding (as per the GoldMoney User Agreement) that will operate the Holding as a merchant Holding - operating a Holding as a merchant Holding implies that the merchant will utilize the Holding as a payee Holding in context of the GoldMoney Online Merchant Interface. Furthermore, it is assumed that the merchant offers products and/or services for sale via the Internet, and therefore already has an existing web site. The terms "merchant" and "GoldMoney merchant" are used interchangeably throughout this document and have the same meaning.

Customer: A customer is defined, in the context of this document, as an individual that owns a GoldMoney Holding, and that wishes to pay GoldMoney merchants in GoldGrams for products and/or services that the merchants sell via the Internet.

OMI: The GoldMoney "O"nline "M"erchant "I"nterface is abbreviated with the acronym "OMI".

Web Site and System: The merchant's web site is hereafter also referred to as the "merchant system". Similarly, the GoldMoney web site is hereafter also referred to as the "GoldMoney system", "GoldMoney OMI" or simply "OMI".

The GoldMoney OMI was designed with the following key design principles in mind:

Simplify the integration effort required to integrate merchant systems with the OMI - use existing concepts, technologies and processes as far as possible, and provide viable implementation alternatives where sensible;
Provide adequate security measures where necessary to identify, authenticate and authorise different parties, as well as to protect data confidentiality and ensure data integrity;
Promote a transparent or seamless customer experience.

2. Online Merchant Interface Process

This section provides an overview of the GoldMoney Online Merchant Interface (OMI). The following figure depicts the process that will enable merchants to receive payments in GoldGrams using the OMI:

Figure 1: GoldMoney Online Merchant Interface

The process depicted in the figure above consists of the following steps:

Step 1: The customer browses the products and services offered by the merchant, and adds items to a shopping cart if provided by the merchant web site;
Step 2: After the customer has completed his/her selection of the merchant's products and services, he/she proceeds by selecting the checkout option provided by the merchant web site;
Step 3: On the merchant's checkout page, the customer indicates that he/she wishes to pay the merchant in GoldGrams. This page should present the total amount that the merchant wishes to be paid, and can be given in various currencies, including GoldGrams (if given in a currency other than GoldGrams, the OMI will convert the total amount to GoldGrams);
Step 4: If the customer agrees to pay the merchant the specified amount, he/she proceeds with the merchant checkout process;
Step 5: The customer's browser sends the required information to the GoldMoney OMI;
Step 6: The OMI uses the information sent to it by the customer's browser to generate a payment details page for presentation to the customer, and also to verify the OMI properties of the merchant;
Step 7: The customer is presented with a GoldMoney page requesting payment details that are required to effect payment from the customer Holding to the merchant Holding. The customer can abort the payment process at this point if desired, and will then be redirected to a merchant page informing him/her that the payment was not effected;
Step 8: The customer (payer) enters the required payment details (customer's Holding number, passphrase and an optional memo), and clicks to proceed;
Step 9: The payment details the customer entered in the previous step are passed to the GoldMoney OMI;
Step 10: The OMI performs validation of the payment details, such as checking whether the specified passphrase is the valid passphrase for the specified payer Holding, and whether the specified payee (merchant) Holding is a valid Holding. The OMI then sends a payment confirmation page for presentation to the customer;
Step 11: The customer is presented with a GoldMoney page that confirms the details of the payment to be made. The customer can click to abort the payment process, and will then be redirected to a merchant page informing him/her that the payment was not effected;
Step 12: The customer reviews the payment details, and clicks to make the payment;
Step 13: The OMI receives the payment request, it verifies the payment details, and performs the payment if the payment details are valid. The customer's Holding (payer) will be charged the GoldMoney fee associated with the payment;
Step 14: In the case of a successful payment, the OMI notifies the merchant system that the payment has been effected, and also sends it some details regarding the payment. The payment details hash that is passed from the OMI to the merchant system enables the merchant to verify that the payment notification was indeed generated by the OMI (i.e. the source of the notification can be authenticated because the hash contains a shared secret key), and enables the merchant to check whether the details of the payment have not been modified unknowingly (the integrity of the payment details can be verified);
Step 15: The OMI informs the customer directly of the outcome of the payment;
Step 16: The customer views the outcome of the payment as presented by the GoldMoney OMI;
Step 17: After the customer has viewed the payment result page, he/she proceeds and is redirected to the merchant web site. Depending on whether the payment was successful or not, the merchant may decide to redirect the customer to different pages (successful payment page or failed payment page) based on the outcome of the payment;
Step 18: The merchant may request some information from the customer's browser to be sent to the merchant system so that it can present the customer with details relating to the order - this can be done in both cases (for successful and failed payments) if required, or just in the case of a successful payment;
Step 19: The order details are sent to the customer's browser (if so desired by the merchant);
Step 20: The customer views a merchant page in the context of a successful payment;
Step 21: The customer views a merchant page in the context of a failed payment.

3. Online Merchant Interface Details

This section provides the details of how to integrate a merchant system with the GoldMoney OMI.

3.1 Merchant Holding OMI Properties

In order for a merchant to become a GoldMoney merchant, the merchant will have to open and maintain at least one Holding within the OMI into which customers can transfer (pay) GoldGrams from their respective Holdings.

Once the merchant has opened a Holding, he/she must request GoldMoney to activate the OMI for that particular Holding. This can be done using the secure messaging facility that is available once logged in to a Holding.

As soon as GoldMoney activates the OMI for a particular Holding, the merchant will be able to configure the following set of OMI properties for that Holding:

Table 1: Merchant Holding OMI Properties
Property Name	Maximum Length	Description
Result URL	255 characters (case sensitive)	The URL (on the merchant system) that the OMI will send (HTTP POST) the details of a successful payment to. If this URL is not specified by the merchant, the merchant will not be notified by the OMI when payments are made to the merchant's Holding. Alternatively, if this field starts with "email:", the payment details will be sent via email to the specified address, for example "email:pay@shopper.com". This URL must start with "http://", "https://" or "email:". Please note that URLs can only point to ports 80 and 443 on the merchant system. All other ports will be rejected and the payment notification will not be sent.
Success URL	255 characters (case sensitive)	The URL (on the merchant system) that the user's browser will be redirected to once the user has completed viewing the result of a successful payment as presented by the GoldMoney web site. This URL must start with "http://" or "https://".
Success URL Method	-	The HTTP method (POST, GET or LINK) that will be used to link to the Success URL.
Fail URL	255 characters (case sensitive)	The URL (on the merchant system) that the user's browser will be redirected to once the user has completed viewing the result of a failed payment as presented by the GoldMoney web site. This URL must start with "http://" or "https://".
Fail URL Method	-	The HTTP method (POST, GET or LINK) that will be used to link to the Fail URL.
Payment Details Hash Method	-	The algorithm that the OMI should use when hashing the payment details that it will send to the merchant system in step 14 of Figure 1. The supported hash algorithms are MD5 and SHA-1. Because SHA-1 is more secure, GoldMoney recommends the use of SHA-1 rather than MD5. See Appendix A for an overview of the different hash algorithms that are supported.
Test/Live Flag	-	A flag that will enable the merchant to test the integration of the merchant system with the OMI without effecting real payments. If this flag is set to Test, the OMI will send simulated payment details to the merchant system, which will not relate to actual payments made within the OMI. When this flag is set to Test, only the merchant's Holding can be specified as the payer Holding (i.e. when testing, the payer and the payee Holding must be the same Holding).
Active/Inactive Flag	-	A flag that will enable the merchant to completely deactivate the OMI. If this flag is set to Inactive, the OMI will always return an error message to the user when it receives a payment request for the benefit of the merchant that deactivated the OMI. This flag can be used when the merchant system is experiencing prolonged unexpected or planned downtime. The OMI will never effect a payment to the merchant if the payment relates to a merchant Holding that has this flag set to an Inactive state.
Secret Key	255 characters (case sensitive)	A secret string of characters that the OMI will include in a hash as part of the payment details sent to the merchant system, after completion of a successful payment to the merchant's Holding. This key will enable the authentication of the source and the validation of integrity of the payment details sent to the merchant system.
Send Secret Key Flag	-	A flag that will instruct the OMI to send the Secret Key separately from the normal payment details hash to the merchant system whenever it sends the Payment Notification Form. This will relieve the merchant from having to perform a hash on the payment details sent by the OMI to the merchant system in order to verify their source - the integrity of the payment details is inherently ensured by the SSL protocol as long as the Result URL is secure, so a hash of the payment details is not required to verify their integrity. This flag is only used when the Result URL is secure (starts with "https://").
Omit Payment Details Flag	-	A flag that will instruct the OMI to either include the payment details in, or exclude certain payment details from the email message it will send to the Result URL (this only applies if the Result URL is an email address).
Allow URL Overrides from Payment Request Form	-	A flag that will indicate to the OMI whether the values of the Result URL, Success URL, Success URL Method, Fail URL and Fail URL Method may be overridden from the Payment Request Form.
Verify the SSL Certificate of the Result URL	-	This flag controls the behaviour of the OMI when the Result URL is secure (starts with "https://") and when the Payment Notification Form is sent to the merchant system. If the SSL certificate must be verified, then the OMI will verify that the SSL certificate at the Result URL was signed by a known certificate authority (CA), and that the common name in the certificate matches the domain name in the Result URL. If this verification fails, then the OMI will not send the Payment Notification Form to the Result URL. Merchants have the option to ignore this verification process, for example if they know that their SSL certificate was not issued by a known certificate authority (in other words if it was self-issued).
Authorised by GoldMoney for Use	-	This flag is set exclusively by the GoldMoney administrator, and controls whether the OMI of a particular Holding is authorised for testing purposes only, or whether it is authorised to facilitate real payments. If a merchant Holding's OMI has not been fully authorised, it will not be able to process real payments until such time as it is fully authorised - it will only be able to effect test (simulated) payments.

3.2 HTML Forms

The OMI utilizes the following key HTML forms:

Payment Request Form - this form is generated by the merchant system for receipt by the GoldMoney system, and is sent via the customer's browser;
Payment Notification Form - this form is generated by the OMI for receipt by the merchant's web site;
Payment Success Form - this form is generated by the OMI for receipt by the merchant system, and is sent via the customer's browser;
Payment Failure Form - this form is generated by the OMI for receipt by the merchant system, and is sent via the customer's browser.

3.2.1 Payment Request Form

This form is submitted by the merchant system to the GoldMoney system (via the customer's browser) in step 5 of Figure 1.

Action - the form action must be set to the following URL: https://secure.goldmoney.com/omi/omipmt.php
Method - the form method must be set to POST or GET.

The following table describes the fields on the Payment Request Form:

Table 2: Payment Request Form Fields
Field Name	HTML Field Name	Required?	Description
Merchant Holding Number	OMI_MERCHANT_HLD_NO	Yes	The Holding number (format '99-99-99-X') of the merchant that the payment must be made to (payee Holding). Note that the dashes in the number must be included (if there are any), but the number can be in either uppercase or lowercase.
Currency Amount	OMI_CURRENCY_AMT	Yes	The amount that the merchant wishes to be paid by the customer. The amount must be greater than zero, and must be a valid number.
Currency Code	OMI_CURRENCY_CODE	Yes	The code of the currency that the above amount is specified in. See Table 3 for a list of valid currency codes.
Test Type Indicator	OMI_SIM_MODE	No	An optional test indicator that indicates the type of payment simulation the merchant wants to effect in Test mode: 0 or not specified: All simulated payments will succeed; 1: All simulated payments will fail; 2: Approximately 80% of simulated payments will succeed, and therefore approximately 20% of simulated payments will fail. The presence (or absence) of this field and its value has no effect in Live mode.
Merchant Reference Number	OMI_MERCHANT_REF_NO	No	A field that the merchant can specify to associate the customer order with. The reference number will be included in the memo associated with the payment. The GoldMoney system will eventually pass this field back to the merchant system (steps 14 and 18 of Figure 1). GoldMoney recommends that merchants use this field to identify and keep track of each order. The maximum length allowed for this field is 50 characters.
Result URL Override	OMI_RESULT_URL	No	This field enables the merchant to temporarily override the Result URL OMI property as set in the merchant's Holding. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to true, and both this field as well as all of the four other override fields contain values, then the value of this field will be used in place of the Result URL OMI property. The value of this field is validated against the same rules that apply for the Result URL. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to false, then this field will be ignored regardless of whether it is present or not, or whether it contains a value or not. The maximum length allowed for this field is 255 characters.
Success URL Override	OMI_SUCCESS_URL	No	This field enables the merchant to temporarily override the Success URL OMI property as set in the merchant's Holding. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to true, and both this field as well as all of the four other override fields contain values, then the value of this field will be used in place of the Success URL OMI property. The value of this field is validated against the same rules that apply for the Success URL. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to false, then this field will be ignored regardless of whether it is present or not, or whether it contains a value or not. The maximum length allowed for this field is 255 characters.
Success URL Method Override	OMI_SUCCESS_URL_METHOD	No	This field enables the merchant to temporarily override the Success URL Method OMI property as set in the merchant's Holding. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to true, and both this field as well as all of the four other override fields contain values, then the value of this field will be used in place of the Success URL Method OMI property. The value of this field can be set to "POST", "GET" or "LINK". If the value of the Allow URL Overrides from Payment Request Form OMI property is set to false, then this field will be ignored regardless of whether it is present or not, or whether it contains a value or not.
Fail URL Override	OMI_FAIL_URL	No	This field enables the merchant to temporarily override the Fail URL OMI property as set in the merchant's Holding. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to true, and both this field as well as all of the four other override fields contain values, then the value of this field will be used in place of the Fail URL OMI property. The value of this field is validated against the same rules that apply for the Fail URL. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to false, then this field will be ignored regardless of whether it is present or not, or whether it contains a value or not. The maximum length allowed for this field is 255 characters.
Fail URL Method Override	OMI_FAIL_URL_METHOD	No	This field enables the merchant to temporarily override the Fail URL Method OMI property as set in the merchant's Holding. If the value of the Allow URL Overrides from Payment Request Form OMI property is set to true, and both this field as well as all of the four other override fields contain values, then the value of this field will be used in place of the Fail URL Method OMI property. The value of this field can be set to "POST", "GET" or "LINK". If the value of the Allow URL Overrides from Payment Request Form OMI property is set to false, then this field will be ignored regardless of whether it is present or not, or whether it contains a value or not.
Default Payment Memo	OMI_MERCHANT_MEMO	No	If specified, the OMI will default the memo to be associated with the payment to the value of this field (the customer will however be able to override this default value). The OMI will automatically prefix the memo with the Merchant Reference Number (if specified) upon payment. The OMI will insert whitespace in order to split any continuous character sequences of 20 characters or longer it finds in the memo field. The maximum length allowed for this field is 200 characters, but the OMI will truncate this field if it exceeds the maximum length allowed for payment memos in the GoldMoney system.
Merchant Parameters	As specified by the merchant	No	The OMI will automatically retrieve all remaining hidden fields (of which the field names do not start with "OMI_") that the merchant may have specified on the form, and eventually pass them back to the merchant system (in steps 14 and 18 of Figure 1). Note that submit buttons on HTML forms are also inadvertently passed along, because the OMI cannot distinghuish among the different types of HTML input fields it retrieves from the Payment Request Form.

The following table lists the valid currency codes that the OMI will accept on the Payment Request Form:

Table 3: Currency Codes
Currency Name	Currency Code
GoldGram (XGG)	0 (zero)
Australian Dollar (AUD)	36
Brazilian Real (BRL)	986
British Pound (GBP)	826
Canadian Dollar (CAD)	124
Chinese Yuan (CNY)	156
Deutsche Mark (DEM)	280
European Currency Unit (EUR)	978
French Franc (FRF)	250
Hong Kong Dollar (HKD)	344
Indian Rupee (INR)	356
Italian Lira (ITL)	380
Japanese Yen (JPY)	392
Kuwaiti Dinar (KWD)	414
Mexican Peso (MXN)	484
New Zealand Dollar (NZD)	554
Russian Ruble (RUR)	810
South African Rand (ZAR)	710
Swiss Franc (CHF)	756
Turkish Lira (TRL)	792
United States Dollar (USD)	840

If the specified currency code is not zero (in other words, it is a currency code other than GoldGrams), the OMI will convert the specified amount into GoldGrams on behalf of the merchant using GoldMoney's exchange rates that are provided through the currency converter. These exchange rates are updated frequently, and when specifying a currency code other than zero, the merchant acknowledges that GoldMoney's exchange rate will be satisfactory.

The merchant acknowledges that GoldMoney provides GoldGram exchange rates for convenience only. While GoldMoney believes these exchange rates to be accurate, GoldMoney does not accept any responsibility for the accuracy of these rates because they are provided by third parties and are beyond the control of GoldMoney.

If the merchant does not wish to rely on GoldMoney to perform the conversion of the specified amount to GoldGrams, the merchant system will have to perform this conversion prior to submitting the Payment Request Form. In this case the currency code must be set to zero to indicate that the specified amount is already a GoldGram amount.

The following is an example extract of a Payment Request Form in which the URLs are not being overridden:

The following is an example extract of a Payment Request Form in which the URLs are being overridden:

3.2.2 Payment Notification Form

This form is submitted by the OMI to the merchant system in step 14 of Figure 1. The OMI will only send this form once a successful payment (or simulated payment) has been effected.

Action - the form action will be set to the Result URL.
Method - the form method will be set to POST.

The following table describes the fields on the Payment Notification Form:

Table 4: Payment Notification Form Fields
Field Name	HTML Field Name	Description
Merchant Reference Number	OMI_MERCHANT_REF_NO	A reference number specified by the merchant that is associated with the payment. If the merchant did not specify a reference number, this field will still be sent, but will just have an empty value. This field is always treated as case sensitive.
Test/Live Mode Flag	OMI_MODE	Indicates whether the payment notification relates to a real payment or a test (simulated) payment. This is the value of the Test/Live Flag OMI property as set for the merchant Holding, and will be set to either "TEST" or "LIVE". This field is always in uppercase.
Merchant Holding Number	OMI_MERCHANT_HLD_NO	The Holding number that the payment was effected to (the payee), in the format "99-99-99-X". This field is always in uppercase.
Payer Holding Number	OMI_PAYER_HLD_NO	The Holding number that the payment was effected from (the payer), in the format "99-99-99-X". This field is always in uppercase.
Currency Code	OMI_CURRENCY_CODE	The code of the currency, as given in Table 3, that the payment amount was converted from into GoldGrams. This field is always numeric.
Currency Amount	OMI_CURRENCY_AMT	The amount, in the above currency, that was paid to the specified merchant Holding. This field is always numeric.
GoldGram Amount	OMI_GOLDGRAM_AMT	The amount, in GoldGrams, that was paid from the specified payer Holding to the specified merchant Holding. This field is always numeric.
Transaction ID	OMI_TXN_ID	The unique GoldMoney transaction ID that is associated with the payment. This field is always in uppercase.
Transaction Date and Time	OMI_TXN_DATETIME	The date and time (GMT) that the OMI effected the payment, in the format "YYYY-Mon-DD HH24:MI:SS". This field is always treated as case sensitive.
Secret Key	OMI_SECRET_KEY	The Secret Key that is only known by the merchant and the OMI. This field will always be empty if the Result URL is not secure, if the Send Secret Key Flag OMI property is set to indicates that it should not be sent, or if the Result URL is being overridden. This field is always treated as case sensitive.
Payment Details Hash	OMI_HASH	A hash of the above payment notification details using the hash method as specified by the Payment Details Hash Method OMI property. This field is always in uppercase.
Merchant Parameters	As specified by the merchant	All merchant-specific fields as specified by the merchant on the Payment Request Form.

Very Important:

If the Result URL is not an email address, in other words the Result URL starts with either "http://" or "https://", then the OMI will assume that the Payment Notification Form was successfully sent to the merchant if and only if the merchant system returns the string "200 OK" in response to the Payment Notification message.
It will be prudent of the merchant to verify both the source and the integrity of the above payment notification details sent in the Payment Notification Form as described in section 3.3.

The following is an example of a Payment Notification Form:

<form action="<Result URL>" method="post">
<input type="hidden" name="OMI_MERCHANT_REF_NO" value="12-ABCDEF-34-xyz">
<input type="hidden" name="OMI_MODE" value="LIVE">
<input type="hidden" name="OMI_MERCHANT_HLD_NO" value="50-01-00-H">
<input type="hidden" name="OMI_PAYER_HLD_NO" value="50-04-00-N">
<input type="hidden" name="OMI_CURRENCY_CODE" value="840">
<input type="hidden" name="OMI_CURRENCY_AMT" value="100.45">
<input type="hidden" name="OMI_GOLDGRAM_AMT" value="10.430">
<input type="hidden" name="OMI_TXN_ID" value="R56TMKF">
<input type="hidden" name="OMI_TXN_DATETIME" value="2001-Feb-03 15:02:18">
<input type="hidden" name="OMI_SECRET_KEY" value="Q34rf764GT5r">
<input type="hidden" name="OMI_HASH" value="84AF9B4D4A06ECD097033A170F12D2EF">
<input type="hidden" name="MERCHANT_FIELD_1" value="VALUE_1">
<input type="hidden" name="MERCHANT_FIELD_2" value="VALUE_2">
...
<input type="hidden" name="MERCHANT_FIELD_X" value="VALUE_X">
</form>

If the Result URL is an email address (starts with "email:"), then the fields on the Payment Notification Form will be sent by the OMI to the merchant system via email to the specified email address.

If the Result URL is an email address, and the value of the Omit Payment Details Flag is set to true, then the OMI will only include the following fields from the Payment Notification Form in the email message:

Merchant Holding Number (masked);
Transaction ID;
Merchant Reference Number.

3.2.3 Payment Success Form

This form is submitted by the OMI to the merchant system (via the customer's browser) in step 18 of Figure 1, if a successful payment (or simulated payment) was effected by the OMI.

Action - the form action will be set to the Success URL.
Method - the form method will be set to POST, GET or LINK, depending on the value of the merchant-specified Success URL Method. In the case of a LINK, the OMI will not send a form (via the customer's browser) to the Success URL, but will only provide a link to it.

The following table describes the fields on the Payment Success Form:

Table 5: Payment Success Form Fields
Field Name	HTML Field Name	Description
Merchant Reference Number	OMI_MERCHANT_REF_NO	The merchant reference number as specified on the Payment Request Form. If the merchant did not specify a reference number, this field will still be sent, but will just have an empty value.
Merchant Referrer URL	OMI_MERCHANT_URL	If the merchant's checkout page identified itself via the HTTP referrer field in step 5 of Figure 1, this field will contain that referrer URL, otherwise it will contain the URL of GoldMoney's home page.
Transaction ID	OMI_TXN_ID	The unique GoldMoney transaction ID that is associated with the payment.
Merchant Parameters	As specified by the merchant	All merchant-specific fields as specified by the merchant on the Payment Request Form.

The following is an example of a Payment Success Form:

<form action="<Success URL>" method="<Success URL Method>">
<input type="hidden" name="OMI_MERCHANT_REF_NO" value="12-ABCDEF-34-xyz">
<input type="hidden" name="OMI_MERCHANT_URL" value="https://www.merchant.com/checkout.asp">
<input type="hidden" name="OMI_TXN_ID" value="R56TMKF">
<input type="hidden" name="MERCHANT_FIELD_1" value="VALUE_1">
<input type="hidden" name="MERCHANT_FIELD_2" value="VALUE_2">
...
<input type="hidden" name="MERCHANT_FIELD_X" value="VALUE_X">
</form>

3.2.4 Payment Failure Form

This form is submitted by the OMI to the merchant system (via the customer's browser) in step 18 of Figure 1 if the OMI was unable to effect a successful payment (or simulated payment), or if the payment notification (step 14 in Figure 1) failed.

Action - the form action will be set to the Fail URL.
Method - the form method will be set to POST, GET or LINK, depending on the value of the merchant-specified Fail URL Method. In the case of a LINK, the OMI will not send a form (via the customer's browser) to the Fail URL, but will only provide a link to it.

The fields on the Payment Failure Form are identical to those on the Payment Success Form (see Table 5).

The following is an example of a Payment Failure Form:

<form action="<Fail URL>" method="<Fail URL Method>">
<input type="hidden" name="OMI_MERCHANT_REF_NO" value="12-ABCDEF-34-xyz">
<input type="hidden" name="OMI_MERCHANT_URL" value="https://www.merchant.com/checkout.asp">
<input type="hidden" name="OMI_TXN_ID" value="">
<input type="hidden" name="MERCHANT_FIELD_1" value="VALUE_1">
<input type="hidden" name="MERCHANT_FIELD_2" value="VALUE_2">
...
<input type="hidden" name="MERCHANT_FIELD_X" value="VALUE_X">
</form>

Note that the OMI_TXN_ID field on the Payment Failure Form will contain a value in the case where the OMI effected a successful payment from the payer Holding to the merchant Holding, but the subsequent payment notification of that payment failed for whatever reason (in step 14 of Figure 1). However, in most cases the value of the OMI_TXN_ID field on the Payment Failure Form will be empty, indicating failure of the payment (in which case a payment notification will not have been sent either).

3.3 Validation of Critical Payment Information

Upon successful payment (or simulated payment) from a customer Holding to a merchant Holding, the OMI will attempt to notify the merchant system of such a payment (step 14 in Figure 1) by sending the payment notification details (via the Payment Notification Form) to the Result URL.

Although a merchant is not required to execute any of the following validations, GoldMoney recommends that, upon receipt of a Payment Notification Form, the merchant system performs the following:

Verify whether the payment notification was in fact sent by the OMI (verify the payment notification source);
Verify the integrity of the payment notification details sent by the OMI (verify that no data tampering took place);
Verify the amount received;
Verify that the PAYEE Holding number is the same as the merchant Holding number;
Verify whether the payment relates to a real or a simulated payment.

Each of the above steps is described in more detail in the following sections.

3.3.1 Verify Payment Notification Source

As mentioned before, the Secret Key OMI property should only be known by the merchant Holding and the OMI (this will always be the case, unless it was somehow compromised by the merchant or the merchant system). Because of this, the Secret Key enables the authentication of the payment notification source to the merchant system. The merchant can authenticate the source in one of several ways, depending on whether the Result URL is secure or not:

Result URL is Secure, and Result URL is not overridden

If the Result URL is secure (starts with "https://"), and if the merchant requests the Secret Key to be sent to the Result URL, and if the Result URL is NOT overridden from the Payment Request Form, then the merchant has the following options:

If the merchant does not wish to perform a hash (that must include the Secret Key) in order to verify the payment notification source, the merchant can set the Send Secret Key Flag OMI property to true, and then the OMI will send the merchant system the Secret Key directly (in the OMI_SECRET_KEY field of the Payment Notification Form). The merchant system can then compare its own copy of the Secret Key with the one sent by the OMI, and if they are the same, then the merchant system can deduct that the payment notification source was indeed the GoldMoney OMI;
If the merchant wishes to perform a hash (that must include the Secret Key) in order to verify the payment notification source, the merchant system will, by generating the hash and comparing it to the hash sent by the OMI, verify the payment notification source, as the hash must include the Secret Key. Although it would not make much of a difference in this case, the Send Secret Key Flag OMI property can be set to false.

Result URL is not Secure, or Result URL is overridden

If the Result URL is not secure (does not start with "https://", or is an email address), or if the merchant does not want the Secret Key to be sent to the Result URL, or if the Result URL is overridden from the Payment Request Form, then the OMI will never send the Secret Key directly to the merchant system via the OMI_SECRET_KEY field in the Payment Notification Form. In this case it will only include the Secret Key as part of a hash of the payment notification details, and this hash is then sent to the merchant system. This is similar to the scenario described above in which the Result URL is secure, but the merchant wishes to perform a hash anyway.

3.3.2 Verify Integrity of Payment Notification Details

The OMI will, when sending payment notification details to the merchant system, send both the payment notification details and a hash of the payment notification details.

The merchant can authenticate the source in one of several ways, depending on whether the Result URL is secure or not:

Result URL is Secure, and Result URL is not overridden

If the Result URL is secure (starts with "https://"), and if the Result URL is NOT overridden from the Payment Request Form, then the merchant does not need to perform a hash of the payment notification details in order to verify their integrity, as the underlying SSL protocol will ensure the integrity of the payment notification details during their transmission from the OMI to the merchant system. As the OMI will send a hash of the payment notification details to the merchant system regardless of whether the Result URL is secure or not, the merchant is therefore free to still perform a hash if so desired.

Result URL is not Secure, or Result URL is overridden

If the Result URL is not secure (does not start with "https://", or is an email address), or if the Result URL is overridden from the Payment Request Form, then GoldMoney strongly recommends that the merchant system performs a hash of the payment notification details upon receipt in order to verify their integrity.

Payment Details Hash

The hash of the payment notification details serves as a mechanism that the merchant system can use to verify both the source and the integrity of the payment notification details it receives at the Result URL in the Payment Notification Form.

In order to generate the hash, the OMI concatenates the following fields in the Payment Notification Form using a question mark ("?") as delimiter:

Merchant Reference Number
Test/Live Mode Flag
Merchant Holding Number
Payer Holding Number
Currency Code
Currency Amount
GoldGram Amount
Transaction ID
Transaction Date and Time
Secret Key

The hash algorithm the OMI will use to generate the hash will be determined by the value of the Payment Details Hash Method OMI property as set in the merchant Holding (MD5 or SHA-1).

In the case of MD5, the calculated hash will consist of 32 hexadecimal digits in UPPERCASE. In the case of SHA-1, the calculated hash will consist of 40 hexadecimal digits in UPPERCASE. GoldMoney recommends that merchants implement the SHA-1 hash method, as it is more secure than the more commonly used MD5 hash method.

The following provides an example of the calculation of a payment notification details hash using both hash methods. Assume the following payment notification details were sent by the OMI to the merchant system in the Payment Notification Form (excluding the merchant parameters):

Table 6: Payment Notification Details Hash Fields Example
No	Field Name	HTML Field Name	Sample Value and Notes
1	Merchant Reference Number	OMI_MERCHANT_REF_NO	12-ABCDEF-34-xyz
2	Test/Live Mode Flag	OMI_MODE	LIVE
3	Merchant Holding Number	OMI_MERCHANT_HLD_NO	50-01-00-H
4	Payer Holding Number	OMI_PAYER_HLD_NO	50-04-00-N
5	Currency Code	OMI_CURRENCY_CODE	840
6	Currency Amount	OMI_CURRENCY_AMT	100.45
7	GoldGram Amount	OMI_GOLDGRAM_AMT	10.430
8	Transaction ID	OMI_TXN_ID	R56TMKF
9	Transaction Date and Time	OMI_TXN_DATETIME	2001-Feb-03 15:02:18
10	Secret Key	OMI_SECRET_KEY	Q34rf764GT5r (the value of this field may be blank, depending on the value of the Send Secret Key Flag OMI property, and whether the Result URL is secure or not)
11	Payment Details Hash (as calculated by the OMI)	OMI_HASH	84AF9B4D4A06ECD097033A170F12D2EF

Using the above values (excluding the hash as calculated by the OMI), a string is created by concatenating the above values in the specified order using a question mark ("?") as delimiter:

12-ABCDEF-34-xyz?LIVE?50-01-00-H?50-04-00-N?840?100.45?10.430?R56TMKF?2001-Feb-03 15:02:18?Q34rf764GT5r

Note that the above string may not be shown as a continuous string of characters in this document (because it may be wrapped), but the hash will be performed on a continuous string of characters. In addition, the value of the Secret Key in the above concatenation must be used as it is known to the merchant system, and NOT as it was sent by the OMI (if it was sent at all).

The expected hash in the OMI_HASH field of the Payment Notification Form, if the Payment Details Hash Method OMI property is set to MD5, is:

84AF9B4D4A06ECD097033A170F12D2EF

The expected hash in the OMI_HASH field of the Payment Notification Form, if the Payment Details Hash Method OMI property is set to SHA-1, is:

2288FEA4F5375D90F47943D7E33290ABF6792632

If the hash sent by the OMI is identical to the hash calculated by the merchant system, the merchant can safely infer that:

the payment notification details were indeed sent by the GoldMoney OMI;
the values of the fields in the Payment Notification Form were received exactly as they were sent by the OMI.

Very Important:

Because some of the fields on the Payment Notification Form are passed via the customer's browser prior to them being sent back to the merchant system by the OMI in step 14 of Figure 1, there can be no absolute guarantee that the values of these fields will be the same as set on the Payment Request Form by the merchant (because the field values on an HTML form can be modified manually, using a text editor, before the form is submitted to a web server). It is therefore important that the merchant does not assume that the integrity of these field values are necessarily intact.

3.3.3 Verify Amount Received

Because any information submitted by a customer's browser can be modified by the customer (such as the amount and currency code), it is important that the merchant verifies that the GoldGram amount paid to the merchant Holding (OMI_GOLDGRAM_AMT field in the Payment Notification Form) is indeed the GoldGram amount that the merchant was expecting to receive.

3.3.4 Verify Payee Holding Number

Because any information submitted by a customer's browser can be modified by the customer (such as the payee Holding number), it is important that the merchant verifies that the merchant Holding number (payee) as specified by the OMI (OMI_MERCHANT_HLD_NO field in the Payment Notification Form) is indeed the Holding number of the merchant.

3.3.5 Verify Real or Test/Simulated Payment

Because the OMI enables merchants to test the integration of the OMI with the merchant system without effecting real payments, the Payment Notification Form can relate to either a real payment or a simulated payment, based on the value of the Test/Live Flag OMI property set by the merchant.

It is therefore important for a merchant system to verify that, upon receipt of a Payment Notification Form, whether a real payment was effected in the OMI, or if it was only a test or simulated payment. The OMI_MODE field in the Payment Notification Form can be used for this purpose, as it will be set to either "TEST" or "LIVE" depending on the value of the Test/Live Flag OMI property.

If the value of the OMI_MODE field is "TEST", then the payment notification details on the Payment Notification Form will NOT BE AUTHENTIC, as they were fabricated by the GoldMoney system, and therefore WILL NOT relate to an actual payment.

If the value of the OMI_MODE field is "LIVE", then the payment notification details on the Payment Notification Form are indeed authentic, as they will relate to an actual payment effected in the OMI.

3.3.6 Conclusion

From the previous sections it should be obvious that having a secure Result URL has more advantages than a non-secure Result URL. GoldMoney recommends that merchants implement secure Result URLs if at all possible. GoldMoney also recommends the selection of SHA-1 rather than MD5 as the Payment Details Hash Method, as it is more secure.

4. Online Merchant Interface Testing

The Test/Live Flag OMI property enables merchants to test the integration of their system with the GoldMoney OMI without effecting real payments. If the value of this property is set to "TEST", then the OMI will generate simulated payments only. Alternatively, if the value of this field is set to "LIVE", then the OMI will attempt to effect real payments to the merchant's Holding.

Merchant's should therefore set the value of the Test/Live Flag to "TEST" until such time as the merchant is confident that the merchant system is working properly with the GoldMoney OMI.

The customer payment pages that are served by the GoldMoney system will, when the Test/Live Flag is set to "TEST" for the merchant Holding specified in the Payment Request Form (OMI_MERCHANT_HLD_NO), display additional debug fields. When debugging, the merchant should use the merchant Holding number specified on the Payment Request Form also as the PAYER Holding - this will be the only Holding number the OMI will accept as PAYER when the Test/Live Flag is set to "TEST".

The test type indicator (OMI_SIM_MODE in the Payment Request Form) can be used to control the behaviour of the OMI with regards to simulated payments as follows:

Table 7: Controlling Simulated Payments
Value of Test Type Indicator	Behaviour of OMI
0 or not specified	All simulated payments will succeed.
1	All simulated payments will fail.
2	Approximately 80% of simulated payments will succeed, and therefore approximately 20% of simulated payments will fail.

While the value of the Test/Live Flag is set to "TEST", all payment notification details sent by the OMI to the merchant system in the Payment Notification Form will refer to simulated payments only.

The merchant Holding does not need to have a positive GoldGram balance to enable testing.

Appendix A. Hash Algorithms

A message digest or hash is a compact digital signature for an arbitrarily long stream of binary data. An ideal hash algorithm would never generate the same signature for two different sets of input, but achieving such theoretical perfection would require a hash as long as the input file. Practical hash algorithms compromise in favour of a digital signature of modest size created with an algorithm designed to make preparation of input text with a given signature computationally infeasible. Hash algorithms have much in common with techniques used in encryption, but to a different end - verification that data has not been altered since the signature was published (data integrity).

Based on a merchant's preference, the GoldMoney OMI can apply either of the following hash algorithms on the payment notification details in the Payment Notification Form:

Message Digest 5;
Secure Hash Algorithm.

A.1 Message Digest 5 (MD5)

The most commonly used present-day hash algorithm is the 128-bit MD5 algorithm, developed by Ron Rivest of the MIT Laboratory for Computer Science and RSA Data Security, Inc. The algorithm, with a reference implementation, was published as Internet RFC 1321 in April 1992, and was placed into the public domain at that time.

A.2 Secure Hash Algorithm (SHA-1)

SHA-1 was developed by the National Security Agency (NSA) for the National Institute of Standards and Technology (NIST) as part of the Secure Hash Standard (SHS). The original published algorithm, known as SHA, was modified in 1994 by the NSA to protect against an unpublished flaw in SHA.

SHA-1 is similar in design to MD4 (the predecessor of MD5), but it differs in that it adds an additional expansion operation, an extra round and the whole transformation was designed to accommodate the DSS block size for efficiency. SHA-1 also produces a 160-bit hash vs. the 128-bit hash of MD5. SHA-1 is also slightly slower than MD5, but the larger hash makes it more secure against brute-force collision and inversion attacks.


Open a free account to start buying gold and silver >>


	© Copyright 2001-2008 Net Transactions Ltd. Disclaimer \| Privacy Policy \| Customer Support \| FAQ \| CAP \| Sitemap