XML API Integration Guide
Version 4.3 November 2, 2017
Page 2
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
1. Introduction .............................................................................. 6
2. Compliance ............................................................................... 6
3. Notes Before Continuing ........................................................... 7
3.1 HASH Parameters ..................................................................................... 7
3.2 Card Types .............................................................................................. 7
3.3 Multi-currency Terminal IDs ....................................................................... 8
3.4 ACH ........................................................................................................ 8
3.5 Custom Fields .......................................................................................... 9
Custom Fields with Subscriptions and Stored Subscriptions .................... 9 3.5.13.6 Dynamic Descriptors ................................................................................. 9
3.7 Hosted Pages ..........................................................................................10
Hosted Page Styling .........................................................................10 3.7.13.7.1.1 Basic Mode Styling ........................................................................11
3.7.1.2 Advanced Mode Styling..................................................................12
3.8 Test Credentials .......................................................................................13
Sandbox Test Details ........................................................................13 3.8.1 Test Cards .......................................................................................13 3.8.2
3.9 Integration and Validation .........................................................................14
GlobalOnePay Testing Guide ..............................................................14 3.9.1 Merchant Validation Document ..........................................................14 3.9.2
3.10 URL .....................................................................................................14
Hosted Payment page .......................................................................14 3.10.1 XML ...............................................................................................15 3.10.2 Bulk Upload.....................................................................................15 3.10.3
4. Payment Page and Pre-Auth Page Integration ........................ 15
4.1 Hosted Payment Page ..............................................................................15
4.2 MaxMind MinFraud ...................................................................................21
4.3 Hosted Pre-Auth Page ..............................................................................22
4.4 Background Validation ..............................................................................22
4.5 Hosted Pages in an iFrame ........................................................................24
4.6 SecureCard Storage via Hosted Payment Page ............................................24
5. XML Payments Integration ...................................................... 26
5.1 Request Types .........................................................................................26
XML Payments .................................................................................26 5.1.1 XML ACH Sale..................................................................................36 5.1.2 Pre-Authorization Request .................................................................39 5.1.3
Page 3
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Pre-Auth Completion Request ............................................................48 5.1.4 Standard Refunds ............................................................................50 5.1.5 Unreferenced Refunds ......................................................................52 5.1.6 CARDDETAILS tag in XML Requests ....................................................54 5.1.7
5.2 XML Requests with eDCC ..........................................................................55
eDCC Exchange Rate Request ............................................................55 5.2.1 eDCC Information in the XML Requests ...............................................57 5.2.2
5.3 Transaction Status Updates .......................................................................59
5.4 3D Secure For XML Transactions (GlobalOnePay MPI) ...................................61
6. Secure Card Storage ............................................................... 64
6.1 Merchant Portfolio Level Secure Card processing .........................................64
6.2 Secure Card Registration and Updating From the Hosted Page.......................64
6.3 Secure ACH Registration and Updating From the Hosted Page .......................67
6.4 XML Secure Card Integration.....................................................................69
Secure Card Details Registration and Updating ....................................69 6.4.1 Card Details Removal .......................................................................72 6.4.2 Card Details Search ..........................................................................74 6.4.3 Card Details Advanced Search ...........................................................76 6.4.4
6.5 XML Secure ACH Integration .....................................................................79
Secure ACH Details Registration and Updating .....................................79 6.5.1 Secure ACH Details Removal .............................................................82 6.5.2 Secure ACH Details Search ................................................................84 6.5.3 XML Payments Using Registered Card .................................................85 6.5.4 XML Payments Using Secure ACH Details ............................................85 6.5.5
7. Subscriptions .......................................................................... 86
7.1 Credit or ACH Subscription Registration From the Hosted Page ......................87
7.2 XML Subscriptions Integration ...................................................................92
Stored Subscription Creation and Update Request ................................92 7.2.1 Stored Subscription Deletion Request .................................................95 7.2.2 Subscription Creation Request ...........................................................97 7.2.3 Subscription Updating Request ........................................................ 101 7.2.4 Subscription Deletion Request ......................................................... 103 7.2.5 Subscription Cancellation Request .................................................... 105 7.2.6 ACH Subscription Creation Request .................................................. 106 7.2.7 ACH Subscription Updating Request ................................................. 110 7.2.8 ACH Subscription Deletion Request .................................................. 111 7.2.9
Page 4
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
ACH Subscription Cancellation Request ............................................. 113 7.2.10 Subscription Card Payment Request ................................................. 114 7.2.11 Subscription ACH Payment Request .................................................. 116 7.2.12
7.3 Subscription Notifications ....................................................................... 119
8. ACH Re-Initiation .................................................................. 120
9. Bulk Payments ...................................................................... 122
9.1 Request File Submission ......................................................................... 122
9.2 Request CSV File Format ........................................................................ 123
9.3 Request File Submission Response ........................................................... 124
9.4 Response File Request ............................................................................ 125
9.5 Response File Format ............................................................................. 126
Appendix A: CVV & AVS Responses ............................................ 127
CVV Results: ................................................................................................ 127
AVS Results: ................................................................................................ 127
Appendix B: Signature Field Format........................................... 129
Appendix C: Supported Currencies............................................. 130
Appendix D: Bank Response Codes ............................................ 134
Appendix E: Dynamic Descriptors Guide .................................... 136
Feature Description ................................................................................... 136
• Descriptors ........................................................................................... 136
• Dynamic Descriptors .............................................................................. 136
Support and Activation .............................................................................. 137
• Merchant Request .................................................................................. 137
• Implementation/Integration .................................................................... 138
• Logic Flow ............................................................................................. 138
Examples.................................................................................................... 139
Appendix F: Smart Transaction Routing Guide ........................... 140
Appendix G: Gateway Secure ACH Error Codes .......................... 150
Appendix H: XML Gateway Subscription Error Codes ................. 151
Appendix I: Transaction Types/Statuses ................................... 152
Appendix J: Provence/State Codes ............................................ 153
Appendix K: Glossary ................................................................. 155
Appendix L: Version Control ...................................................... 156
Page 5
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
For support, contact
+1 (844) 864 9590
Page 6
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
1. Introduction
The GlobalOnePay system is a secure server-based transaction processing service
that will enable your business to authorise and process credit/debit card transactions
online in real-time. The information needed to process the transactions is sent over a
secure, encrypted internet connection.
Once the customer has completed the payment or pre-auth form, the
GlobalOnePay server connects with your acquiring bank for payment authorization and if
the sale is authorised, returns a receipt to the customer. GlobalOnePay settles the
transactions automatically and the acquiring bank deposits the funds into your bank
account. GlobalOnePay automatically archives sales that are finalised so that you can
refer to them at a later date, if necessary.
This guide provides instructions on how to integrate a website or application into
the system and take automatic credit card and ACH payments.
2. Compliance
Starting on October 14 2017 - All new Canadian merchants will need to include
the CVV2 when processing Visa transactions on GlobalOne due to a new Visa compliance
regulation. Otherwise the transaction will be declined. Merchants processing before this
date are excempted from this rule.
Effective 14 October 2018 – All existing Canadian merchants processing VISA
transactions, will need to include the CVV2.
Page 7
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
3. Notes Before Continuing
3.1 HASH Parameters
Every request to and response from GlobalOnePay includes an MD5 HASH
parameter. This is a security feature to ensure that none of the sensitive data in the
request has been modified by a “man-in-the-middle” attack. This is achieved by including
all the sensitive fields in a string (these vary per request type) along with the shared
secret (configured per terminal). This string is then used as the basis of an MD5 HASH.
In this document, when an MD5 input string is listed such as:
TERMINALID+ORDERID+AMOUNT+DATETIME+SECRET
you should not include the “+” symbols in the calculation. For the example in the first
section below if the shared secret was “x4n35c32RT” then the MD5 HASH would be
calculated as:
md5(“6491002328110.0015-3-2006:10:43:01:673x4n35c32RT”)
and would equal to: dd77fde79d1039d6b39e20d748211530. Note that the MD5 function
should always use a character encoding of UTF-8 where appropriate, as should all data
sent to us.
3.2 Card Types
The card types that your account supports are determined by your acquiring bank.
The options are:
• VISA, • VISA DEBIT, • ELECTRON, • MASTERCARD, • DEBIT MASTERCARD, • MAESTRO, • AMEX, • DINERS, • JCB, • DISCOVER and • CUP_SECUREPAY.
Page 8
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
All live accounts will be set up with the correct card types enabled as per the
documentation that GlobalOnePay receive from your acquiring bank. If this changes,
please ask you acquiring bank to sent updated details to GlobalOnePay so that we can
amend the account.
For testing we recommend using the test card numbers in our “Testing Guide”
document.
3.3 Multi-currency Terminal IDs
Some acquiring banks can support multi-currency Terminal IDs. This allows you to
process multiple base currencies via a single Terminal ID (this is NOT related to Dynamic
Currency Conversion or any exchange rates).
If the Terminal ID that you are processing through is a multi-currency Terminal ID
then the currency will have to be included in many of the request and response Hash
calculations. Details of this are given below for each individual Hash description.
GlobalOnePay will inform you if your Terminal ID supports multi-currency.
3.4 ACH
Automated Clearing House (ACH) is an electronic network for financial transactions
in the United States. ACH credit transfers include direct deposit, payroll and vendor
payments. ACH direct debit transfers include consumer payments on insurance
premiums, mortgage loans, and other kinds of bills. ACH payments can be processed in
USD only.
ACH processing uses the Standard Entry Class (SEC) codes to determine what
information is required to be sent in the submission. The National Automated Clearing
House Association (NACHA) requires the use of SEC Codes for each transaction settled
through the Automated Clearing House (ACH). Each code identifies what type of
transaction occurred. A definition of each of the supported SEC codes used by the
GlobalOnePay can be found below.
• Internet Initiated Entry (WEB): An internet initiated entry is a method of
payment for goods or services made via the internet. • Telephone Initiated Entry (TEL): A telephone initiated entry is a payment for
goods or services made with a single entry debit with oral authorization obtained from the consumer via the telephone.
• Prearranged Payment and Deposit (PPD): A pre-authorized consumer payment
Page 9
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• Cash Concentration and Disbursement (CCD): A pre-authorized corporate payment.
3.5 Custom Fields
Custom Fields allow you to send data to our systems with transactions in name-
value pairs so that it is stored and can be included in reports, receipts and for other
uses. There are two different types of custom fields: Explicit and Implicit.
• Explicit Custom Fields: All the custom fields that are mentioned in this document
are explicit custom fields, all custom fields in the XML gateway are also. They must
be pre-configured in the SelfCare System (Setting -> Custom Fields) for the
particular Terminal ID that you are sending the transaction through.
• Implicit Custom Fields: Any other fields that are sent to the Hosted Payment
Page are considered to be implicit custom fields. These will be returned in the
response to the Receipt Page, but will not be stored, sent to the Background
Validation URL or available in any reporting features. Implicit custom fields are not
supported by the XML gateway.
A Custom Field is set up to be one of three types:
• Boolean: Accepted values are “0”, “1”, “true” or “false” • Numeric: Any numeric only value • String: Any value containing only alphanumeric characters, spaces or the
following characters: '-&*()_+:;@#|.,/
Custom Fields with Subscriptions and Stored Subscriptions 3.5.1
For a Custom Field to be used with Subscriptions it has to be set up under the
terminal AND then added under the relevant Stored Subscription.
3.6 Dynamic Descriptors
For some acquirers/processors it's possible to use Dynamic Desriptors to pass
information on to the cardholders statement. This process uses the Custom Fields and is
documented in Appendix E.
Page 10
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
3.7 Hosted Pages
GlobalOnePay provide Hosted Pages for the entry of some sensitive data so that
the merchants servers do not have to be exposed to this data. This is advisable to reduce
the security overhead of the integrated solution as GlobalOnePay is responsible for
maintaining the security and integrity of the data sent to these pages. The payment is
then processed by GlobalOnePay and the account holder is redirected to the merchant's
receipt page
These pages can also be highly styled so that they look very appealing to the
customers. This helps improve conversion rates and improves the customers overall
payment experience.
Hosted Page Styling 3.7.1
The GlobalOnePay hosted pages can be heavily styled and are device aware,
responsive and reactive, depending on the amount of effort the developer wants to put in
to styling them.
As you can see from the image above it is simple to configure separate templates
to be used for various devices. This is intended as a shortcut; a simple way of “cheating”
the customer to think it's a responsive webpage, however a single template can be made
totally responsive if desired.
Different templates can also be used for Mail Order/Telephone Order (MOTO and
ACH TEL), and eCommerce transactions (Internet and ACH WEB).
There are three permanent templates and they default to some sample styles.
They do not all have to be used.
Images can be included but the image files must be hosted on the merchants
website. The URL of the image will be required in the Payment Page styling.
Page 11
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Note: only users who have “Pay Pages” permissions will have access to this
interface. It can be found once logged in by clicking “Settings” and then “Pay Pages” in
the menu.
3.7.1.1 Basic Mode Styling
Page 12
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Basic template styling requires no knowledge of HTML or CSS. It can allow a
merchant to style the page to an acceptable level. Previews of all hosted pages can be
viewed on the right hand side.
All new templates created are basic. It's best to style as close as possible to what
you are looking for in this mode before clicking “Advanced Mode” for more options.
3.7.1.2 Advanced Mode Styling
Advanced mode allows you to directly edit the CSS of the page and also the HTML
of the Header and Footer. It is recommended not to use Auto Update in this mode.
Because of the custom CSS that cannot be reverted to the same constraints as the
Basic Mode, once you have entered Advanced mode you cannot go back to Basic Mode
styling.
Page 13
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
3.8 Test Credentials
Sandbox Test Details 3.8.1
The following values should be used when testing against the GlobalOne test URLs.
Please see the Testing and Certification guide for further details. The terminal details are:
Currency Terminal ID Shared Secret
USD 33001 SandboxSecret001 CAD 33002 SandboxSecret002 EUR 33003 SandboxSecret003 GBP 33004 SandboxSecret004 MCP* 36001 SandboxSecret001
*MCP is the Multi Currency Terminal Settings
Test Cards 3.8.2
Test cards that may be used on our host are:
• Visa 4444 3333 2222 1111
• MasterCard 5404 0000 0000 0001
• Laser 6304 9900 0000 0000 044
• Maestro 3000 0000 0000 0000 04 UK
• Domestic Maestro 5641 8200 0000 0005
• Electron 4917 3000 0000 0008
• Visa Debit 4462 0000 0000 0003
• Debit MasterCard 5573 4700 8901 0012
• American Express 3742 0000 0000 004
• JCB 3569 9900 0000 0009
• Diners 3600 0000 0000 08
• Solo 6767 6222 2222 2222 222
Page 14
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
3.9 Integration and Validation
In addition you must read the GlobalOnePay Testing Guide for more information on
the process.
GlobalOnePay Testing Guide 3.9.1
The GlobalOnePay Testing Guide describes the best practice methods to test your
integration with the GlobalONE payment gateway using our test server and sandbox
accounts. It will also help you choose betweens both GlobalOnePay integrations methods.
Merchant Validation Document 3.9.2
Once you have completed your modifications, perform the relevant transaction
types as listed in our Merchant Validation Document. *Please note that when testing
you must supply at least TWO successful transactions per transaction type that
you intend to use. Please refer to the functionality checklist in the Merchant Validation
Document. Two transactions are necessary to ensure consistency when our Integration
team analyses your transactions. Record all pertinent information relating to the testing
and return the completed forms to our integration team via email. The integration team
will contact you to confirm that you have successfully validated against the GlobalOnePay
Gateway.
3.10 URL
Depending on your integration method to GlobalOnePay the URL (Universal
Resource Locator) you will need to use is different. The live URL will be provided once
merchant testing is complete.
Hosted Payment page 3.10.1
The following is the GlobalOnePay test payment page URL for the Hosted Payment
Page.
• Sales: https://testpayments.globalone.me/merchant/paymentpage
• Pre Auth: https://testpayments.globalone.me/merchant/preauthpage
• Secure Card: https://testpayments.globalone.me/merchant/securecardpage
• Subscription:https://testpayments.globalone.me/merchant/subscriptionpage/
register
Page 15
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
XML 3.10.2
All transaction type using XML in GlobalOne will be sent to the following URL.
• https://testpayments.globalone.me/merchant/xmlpayment
The XML XSD description for the XML is available at the following URL.
• https://testpayments.globalone.me/merchant/gateway.xsd
For 3D Secure XML transactions should be redirected to the following URL.
• https://testpayments.globalone.me/merchant/mpi
Bulk Upload 3.10.3
The request for the bulk upload will be sent to the following URL.
• https://testpayments.globalone.me/merchant/bulkpayments/submit
The request for the bulk upload response will be sent to the following URL.
• https://testpayments.globalone.me/merchant/bulkpayments/result
4. Payment Page and Pre-Auth Page Integration
4.1 Hosted Payment Page
The Hosted Payment Page is built to allow merchants to easily integrate with the
GlobalOnePay system for processing one-off payments.
Using this system, the cardholders are redirected to the GlobalOnePay payment
page once they have made the decision to buy. All payment details are collected by
GlobalOnePay to be sent to the bank server once the submit button is pressed. The
payment is then processed by GlobalOnePay and the cardholder is redirected to the
merchant's receipt page. GlobalOnePay will also handle 3D Secure and eDCC offerings if
they are appropriate and configured for that Terminal ID.
The above is accomplished by means of a simple HTML form post with a number of
defined form fields (below). The following is the GlobalOnePay test payment page URL:
https://testpayments.globalone.me/merchant/paymentpage
The live URL will be provided once merchant testing is complete.
Page 16
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following table describes the form fields to be posted:
Field Name Required Description TERMINALID Y A TerminalID provided by GlobalOnePay. ORDERID Y A unique identifier for the order created by
the merchant. (Max 12 Characters). CURRENCY Y A 3 character currency code of the
transaction. ISO 4217 Currency Code. AMOUNT Y The amount of the transaction as a 2 digit
decimal or an Integer value for JPY amounts.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See Note below. CARDHOLDERNAME N This will pre-populate the Cardholder Name
field on the payment page. This will be editable on the payment page. It should be as displayed on the front of the card.
AUTOREADY N Y or N. Automatically set the transaction to Ready in the batch. If not present the terminal default will be used.
DESCRIPTION N A description of the transaction. EMAIL N An email address to send a confirmation
email to. Normally this is cardholder email address.
RECEIPTPAGEURL N This is the URL of the page on your site that will display the result of the transaction. If sent this will override the terminal setting in the SelfCare System.
VALIDATIONURL N This will overwrite the default Background Validation URL and will display an error if this feature is not enabled and sent. Highly recommended. See section 4.4.
TERMINALTYPE N 1 or 2 (default). Defines whether the transaction is to be processed as Mail Order/Telephone Order (1) or eCommerce (2 or not sent). Mail Order transactions can have a separate Payment Page Layout.
TRANSACTIONTYPE N ACH: • 4 = ACH Telephone Order • 7 = ACH WEB transaction
Credit: • 4 = Normal Mail Order/Telephone
Order • 5 = 3DS fully authenticated trans • 6 = 3DS attempted trans • 7 = Normal eCommerce trans • 9 = Mail Order (First Data Latvia only)
ADDRESS1 N First line of the customer’s address.This is an AVS field (See Glossary) and is
Page 17
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description mandatory if, and only if, the Terminal settings define that. If “Enable AVS” is set, the verification will be performed when there's data, and if “AVS Compulsory” is set, at least the POSTCODE is mandatory. ADDRESS1 and ADDRESS2 are mandatory in two cases: if during the sale the user defines the field AVS, at the virtual terminal, as “Exact”; and when using a payment integration interface (XML Gateway or HPP) the “API AVS Type” is defined as “Exact". Specifically for HPP integrations, there’s one more setting, “If AVS Sent”, which handles the fields display, when they are sent to the form, before the same is created. If the setting is defined as “Display”, the fields are displayed, read only. If defined as “Editable”, the fields are displayed and editable. If defined as “Hide”, all the AVS fields are hidden.
ADDRESS2 N Second line of the customer’s address.The same handling as ADDRESS1.
POSTCODE N Postal code of the customer’s address. The same handling as ADDRESS1 and ADDRESS2. Also required for MaxMind MinFraud fraud scoring. See section 4.2.
CITY N Required for MaxMind MinFraud fraud scoring. See section 4.2.
REGION N Required for MaxMind MinFraud fraud scoring. See MaxMind definition of this field as it is forwarded to them without modification. See section 4.2.
COUNTRY N ISO 3166-1-alpha-2 code. Required for MaxMind MinFraud fraud scoring. See section 4.2.
PHONE N Customer phone number, to be stored against transaction. International format and numeric.
PAYMENTTYPE N Set to “CUP_SECUREPAY” in order to forward directly to China Union Pay.
CUSTOMER_REF_NUMBER
N Text type field with max length of 48 characteres. This number is defined by the cardmember. It is entered by the merchant at the point of sale. Also, see level 2 notes below. (used only if processing level 2)
TAX_AMOUNT N Value type field, with max length of 13 algarisms. A value of zero is required in
Page 18
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description order to indicate tax exempt transactions. Also, see level 2 notes below. (used only if processing level 2)
SHIPPING_FULL_NAME N Text type field with max length of 50 characteres. Also, see level 2 notes below. (used only if processing level 2)
SHIPPING_ADDRESS1 N Text type field with max length of 50 characteres. Also, see level 2 notes below. (used only if processing level 2)
SHIPPING_ADDRESS2 N Text type field with max length of 50 characteres. Always optional regardless compulsory setting. (used only if processing level 2)
SHIPPING_CITY N Text type field, between 1 and 128 characteres. Also, see level 2 notes below. (used only if processing level 2)
SHIPPING_REGION N Text type field, between 1 and 128 characteres. Also, see level 2 notes below. (used only if processing level 2)
SHIPPING_POSTCODE N Text type field, between 1 and 50 characteres. Also, see level 2 notes below. (used only if processing level 2)
SHIPPING_COUNTRY N Text type field, with 2 characteres. ISO ALPHA-2 Country Code. Also, see level 2 notes below. (used only if processing level 2)
AnyOtherCustomField N Any other fields sent in the request will be treated as a custom field (see section 3.4). It will be returned to the Receipt and Validation URLs also. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+RECEIPTPAGEURL+
VALIDATIONURL+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+RECEIPT
PAGEURL+VALIDATIONURL+SECRET
Page 19
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• If the RECEIPTPAGEURL or VALIDATIONURL parameters are not being sent,
they should not be included in the hash.
• Any non-standard field will be considered as a Custom Field, the name does
not have to starts with ‘CUSTOMFIELD’. Custom Fields are those that are set
up in Terminal Setup. They will be included in posts to the Background
Validation URL and may be prompted for on the payment page if not sent.
Note that Custom Fields are also used to implement Dynamic Descriptors.
• Any other fields that are sent to the HPP are considered to be 'extra fields'.
These will be returned in the response to the Receipt Page, but will not be
stored or sent to the Background Validation URL.
Level 2 Notes:
• This field is associate with the feature “Level II Data”, and to be used is
necessary to set the “Allow Level II Data” option, on a Processing Terminal
“Features” section. And this feature is only available for TSYS Saratoga
Terminals.
• All the fields associated with the feature “Level II Data”, except for
SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory”
is checked in the Processing Terminal “Features” section.
The following HTML shows the minimum required to initiate a transaction. <html> <body> <form action=https://testpayments.globalone.me/merchant/paymentpage method="post"> <input type="hidden" name="TERMINALID" value="6491002" /> <input type="hidden" name="ORDERID" value="3281" /> <input type="hidden" name="CURRENCY" value="EUR" /> <input type="hidden" name="AMOUNT" value="10.00" /> <input type="hidden" name="DATETIME" value="15-3-2006:10:43:01:673" /> <input type="hidden" name="HASH" value="dd77fde79d1039d6b39e20d748211530" /> <input type="submit" value="Pay Now" /> </form> </body> <html>
The URL where GlobalOnePay will send transaction processing results is set on the
Terminal Setup screen (Receipt Page URL field). The following fields are returned in the
response, ** Please note that not all fields will be returned with every transaction type**
Page 20
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Description TERMINALID The Terminal ID that the trans was
processed under. ORDERID The original order ID of the transaction. APPROVALCODE Six digit AuthCode. RESPONSECODE A, E, D or R (Approved, Accepted for later
processing but result currently unknown (China Union Pay), Declined or Referred respectively).
RESPONSETEXT The text of the authorization. DATETIME The time of the transaction created by
the bank. Format: YYYY-MM-DDTHH:MM:SS.
ACCOUNT_TYPE CHECKING or SAVINGS ROUTING_NUMBER The ACH routing number AVSRESPONSE The result of the AVS check. See
Appendix A for more information. CVVRESPONSE The result of the CVV check. See
Appendix A for more information. UNIQUEREF Generated reference that should be
stored for tracking and remote XML refunding.
EMAIL If sent we will return this value. PHONE If sent we will return this value. COUNTRY If sent we will return this value. CARDNUMBER The card number (obfuscated) that was
used for the transaction. HASH An MD5 HASH. See Note below. FRAUDREVIEWSTATUS PASS, REVIEW or REJECT. See level 2
Notes 1,2 and 3 below. FRAUDREVIEWRISKRATING
HIGH, MEDIUM, LOW, NEUTRAL or TRUST. See level 2 Note 1 below.
FRAUDREVIEWSCORE Number between -100 (highest risk) and +100 (lowest risk). See level 2 Note 1 below.
FRAUDREVIEWREASONCODE
Empty String, or a list of comma separated reasons of why this transaction is a risk. See level 2 Note 1 below.
AnyOtherCustomField Any other fields sent in the request will also be included in the response sent to the Receipt Page URL. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.
Notes:
Page 21
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+RESPONSECODE
+RESPONSETEXT+SECRET
Level 2 Notes:
• This field is associate with the feature “Threat Metrix”, and to be used must
be enabled for your Gateway. Also, the Terminal used for processing the
request needs to be enabled for ThreatMetrix feature so your response
contains these fields.
• If a transaction is returned with “FRAUDREVIEWSTATUS” as “REVIEW”, this
transaction can be changed - manually (using the new report feature) or the
using the transaction update XML gateway service - to “APPROVE” or
“REJECT”.
• Transactions returned with “FRAUDREVIEWSTATUS” as “REVIEW” are not
going to be settled until the transaction status is changed (as defined in the
previous note). See Transaction Status Updates page for more details on how
to use the transaction update XML gateway service to change the transaction
returned as “REVIEW” to “REJECT” or “APPROVE”.
Many code examples on how to generate an MD5 HASH can be found on the
Internet. For assistance, please contact GlobalOnePay.
4.2 MaxMind MinFraud
Some fields are required for performing fraud scoring on the transaction using the
MaxMind MinFraud service. There is no charge for this service, and it can be enabled in
the Terminal Setup section of our SelfCare System.
This service will provide a score for the transaction between 0.01 and 100
(riskScore), effectively the percentage chance that it could be fraudulent. Please contact
GlobalOnePay integration support prior to deploying this feature.
Page 22
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
4.3 Hosted Pre-Auth Page
Hosted Pre-Auth page enables pre-authorization requests for merchant needs such
requests are supported by pre-auth terminals only. Approved pre-auth transactions must
be completed using SelfCare System before they will be settled. Final transaction amount
can be adjusted on completion.
The hosted Pre-Auth Page looks the same as the Hosted Payment Page, and has
the same set of fields as Payment Page. However, in the event of a pre-authorization, the
following URL should be used:
https://testpayments.globalone.me/merchant/preauthpage
One thing to note though is that pre-auths don't have the concept of Auto Ready. A
pre-auth will always go into a PENDING state when completed via an XML completion.
4.4 Background Validation
Background validation is a method of double checking the results of transactions
using a server-side post. It is useful for Hosted Payment Page transactions as the result
of the transaction (i.e. the response redirect) can sometimes fail, leaving the site without
a result for the transaction even though the transaction may have been authorised.
It is possible to enable background transaction validation at a terminal level. If this
feature is enabled then all transactions sent through the Hosted Payment Page will be
validated.
The Validation URL should be set for the terminal or sent in the payment request to
the Payment Page, and GlobalOnePay will use this URL to send an HTTP POST request
with transaction processing result and will expect to receive “OK” in the HTTP response
body (2 characters only, no HTML). Any other response or connection issue will be
considered as not-validated and a subsequent attempt to reach the validation URL will be
made later, this process will repeat until our maximum allowed time for validation has
passed. If the maximum allowed time has passed and the transaction was not
successfully validated, the transaction will be marked as expired and the notification
email address will be notified.
If validation is failing or has failed for a particular transaction there will be details
of the cause of the failure in the Open Batch in the SelfCare System. This will detail the
URL being requested and the result, which could be a timeout, SSL or other error or it
could also be the body of the HTML that we received that did not match “OK”. You can
Page 23
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
update the URL for the next attempt, reattempt validation of the transaction by clicking
“Validate” or simply flag the transaction as validated without reattempting online by
clicking “Validate Offline”.
Background Validation can be enabled through the SelfCare System in the Terminal
Setup section
ACH Only
Send ACH notification using the Background Validation process, result of sending
notification does not impact on farther ACH transaction processing
Notification sent in two cases:
• ACH transaction made from HPP (general flow)
• During Settlement process when transaction moving from open to closed
transactions
To distinguish notification types on merchant side use response code, where 'E'
means that transaction initially approved, 'A' transaction approved finally.
The following parameters are sent in the validation request: ** Please note that
not all fields will be returned with every transaction type**
Field Name Description TERMINALID Terminal Id. UNIQUEREF Generated reference that should be stored for
tracking and remote XML refunding. ORDERID Order ID supplied by merchant in request. RESPONSECODE A, D or R (Approved,Declined or Referral). RESPONSETEXT Text describing transaction state. This will be
populated with an error message if there was an issue during processing.
APPROVALCODE Transaction approval code if transaction was authorised otherwise empty.
DATETIME Format: YYYY-MM-DDTHH:MM:SS. AVSRESPONSE AVS response, available only when AVS is enabled for
the terminal. See Appendix A. CVVRESPONSE CVV response, available only when CVV is enabled for
the terminal. See Appendix A. HASH An MD5 HASH. See Note below. Custom Parameters Configured Terminal Custom Parameters.
Page 24
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE
+RESPONSETEXT+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME
+RESPONSECODE+RESPONSETEXT+SECRET
4.5 Hosted Pages in an iFrame
It is also possible to process transactions using an iFrame rather than a full
redirect. All the same fields are required as the standard full redirect integration, but the
implementation for the iFrame is slightly different.
There are two methods of doing this:
1. Build and submit the form as with the standard integration, but withing the
iFrame.
2. Build the POST query string within the main page and then create an iFrame
with that string as it's SRC value.
In either case you should also include this extra parameter:
Field Name Value Description INIFRAME Y
Ensures that all redirects our system performs do not break out of the iFrame.
4.6 SecureCard Storage via Hosted Payment Page
The Hosted Payment Page can be configured to store the processed card as a
SecureCard upon successful authorization of the requested payment. This must be
enabled by GlobalOnePay; if required please email us to request this feature be enabled.
If this feature is enabled and you wish to store the card after the transaction you
need to include the following in the payment request:
Field Name Value Description SECURECARDMERCHANTREF Y Unique Reference assigned by the
merchants site/software to identify the stored card details. Length is limited to 48 chars.
Page 25
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
PERMITTEDTERMINALS N List of permitted terminals. Comma separated list without spaces.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+
RECEIPTPAGEURL+VALIDATIONURL+PERMITTEDTERMINALS
+SECRET
The following additional parameters will be sent to the Receipt Page URL:
Field Name Description ISSTORED “true” or “false” SCERROR Description of storage error if ISSTORED is
“false” MERCHANTREF Original SecureCard Merchant Reference. CARDREFERENCE Generated Card Reference. CARDTYPE See section 3.2 above. CARDEXPIRY Expiry date of the card.
Notes:
• The MD5 response HASH for Hosted Payment Page transactions where the
card is stored is generated using the following as an input string:
TERMINALID+UNIQEREF+AMOUNT+DATETIME+RESPONSECODE+
RESPONSETEXT+CARDREFERENCE+CARDTYPE+CARDNUMBER+
CARDEXPIRY+SECRET
Page 26
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
5. XML Payments Integration
It is also possible to send XML directly to the GlobalOnePay payment server. This is
useful in a scenario where your application needs full control of the payment process or
where you wish to collect card details on your site.
The XML XSD description for all of the packet types below is available there:
https://testpayments.globalone.me/merchant/gateway.xsd
Note that all data sent to us should be correctly uncoded using UTF-8 as the character
encoding.
5.1 Request Types
XML Payments 5.1.1
The following is a simple example of a payment via an XML POST: <?xml version="1.0" encoding="UTF-8"?> <PAYMENT> <ORDERID>115010922465</ORDERID> <TERMINALID>6491002</TERMINALID> <AMOUNT>10</AMOUNT> <DATETIME>12-06-2006:11:47:04:656</DATETIME> <CARDNUMBER>4111111111111111</CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>0807</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> <CURRENCY>EUR</CURRENCY> <TERMINALTYPE>1</TERMINALTYPE> <TRANSACTIONTYPE>7</TRANSACTIONTYPE> <CVV>214</CVV> <CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD> </PAYMENT>
For testing, this XML is posted to:
https://testpayments.globalone.me/merchant/xmlpayment
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8"?> <PAYMENTRESPONSE> <UNIQUEREF>JJCVGCTOV3</UNIQUEREF> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>475318</APPROVALCODE> <DATETIME>2005-11-14T12:53:18</DATETIME> <CVVRESPONSE>M</CVVRESPONSE> <HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH> </PAYMENTRESPONSE>
Page 27
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Payment request fields description:
Field Name Required Description ORDERID Y A unique identifier for the order created by
the merchant. (Max 12 Characters). TERMINALID Y A Terminal ID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. TRACKDATA N Track 2 data should be present for a
swiped cardholder present (CHP) transaction. If this is present then TERMINALTYPE should be set to 3 and TRANSACTIONTYPE should be set to 0.
CARDNUMBER N The payment card number, required if TRACKDATA is not being sent.
CARDTYPE Y See section 3.2 above. CARDEXPIRY N 4 digit expiry field (MMYY), required if
TRACKDATA is not being sent and not using a SecureCard.
CARDHOLDERNAME N The name of the card holder, required if TRACKDATA is not being sent and not using a SecureCard. It should be as displayed on the front of the card.
HASH Y An MD5 HASH. See Note 1 below. CURRENCY Y A 3 character currency code of the
transaction. ISO 4217 Currency Code. FOREIGNCURRENCYINFORMATION
N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions. See XML Payments with eDCC.
TERMINALTYPE Y The type of the terminal: 1 - MOTO (Mail Order/Telephone Order) 2 – eCommerce 3 – Cardholder Present
TRANSACTIONTYPE Y Normally: 0 – Cardholder Present (CHP) transaction 4 - MOTO (Mail Order/Telephone Order) 7 – eCommerce Recurring Payment Flagging: 2 – Specify that this transaction is recurring. This must be accompanied by the RECURRINGTXNREF field or have special permission granted by the Gateway. Not all processors support this
Page 28
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description transaction type and consultation with the integration team should be carried out prior to configuring recurring payment flagging. For First Data Latvia terminal MOTO transactions: 4 - Telephone Order 9 - Mail Order If sending XID & CAVV from non-GlobalOnePay MPI on an eCommerce transaction use: 0 - not applicable 1 - Single transaction 2 - Recurring transaction 3 - Installment payment 4 - Unknown classification 5 - Fully authenticated transaction 3D Secure transaction 6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not participate in 3D-Secure. 7 - Transaction when payment data was transmitted using SSL encryption, or Channel Encrypted 8 - Transaction in the clear, or Non Secure
AUTOREADY N Y or N - If this is set to Y GlobalOnePay will automatically set the transaction to READY in the batch. If set to N then the transaction will go to a PENDING status. If not present the terminal default will be used.
EMAIL N Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by the SelfCare Terminal Setup setting “Disable Cardholder Receipt”.
CVV N The security code entered by the card holder.
ADDRESS1 N First line of the customer’s address.This is an AVS field (See Glossary) and is mandatory if, and only if, the Terminal settings define that. If “Enable AVS” is set, the verification will be performed when there's data, and if “AVS Compulsory” is set, at least the POSTCODE is mandatory.
Page 29
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description ADDRESS1 and ADDRESS2 are mandatory in two cases: if during the sale the user defines the field AVS, at the virtual terminal, as “Exact”; and when using a payment integration interface (XML Gateway or HPP) the “API AVS Type” is defined as “Exact".
ADDRESS2 N The second address field for AVS. See note below.
POSTCODE N The postcode (required) for AVS. Also required for MaxMind MinFraud fraud scoring.
DESCRIPTION N A description of the transaction. XID N The XID for a 3D Secure transaction. CAVV N The CAVV for a 3D Secure transaction. MPIREF N 3D-Secure GlobalOnePay Transaction
Reference supplied in GlobalOnePay MPI transactions.
MOBILENUMBER N Used for SMS receipts. International format, numeric only.
DEVICEID N The unique identifier string for a connecting device. Mandatory for non-server based devices such as handheld devices/cash registers etc.
PHONE N Card Holder Phone Number stored against transaction. International format, numeric only.
CITY N Required for MaxMind MinFraud fraud scoring.
REGION N Required for MaxMind MinFraud fraud scoring. See MaxMind definition of this field as it is forwarded to them without modification.
COUNTRY N ISO 3166-1-alpha-2 code. Required for MaxMind MinFraud fraud scoring.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
SIGNATURE N Optional field if processing Cardholder Present (CHP) transaction using the TRACKDATA field. For format see Appendix B.
RECURRINGTXNREF N Should be set to the value of a UNIQUEREF returned in a PAYMENT response for a matching card. TRANSACTIONTYPE should be set to 2.
CAVV N The CAVV for a 3D Secure transaction
Page 30
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description when not using our MPI. (3D secure not currently supported)
MPIREF N 3D-Secure GlobalOnePay Transaction Reference supplied in GlobalOnePay MPI authentication requests (3D Secure not currently supported).
DEVICE ID N The unique identifier string for a connecting device. Mandatory for non-server based devices such as handheld devices/cash registers etc.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See Note 4.
CUSTOMER_REF_NUMBER
N Subfield of LEVEL_2_DATA. Value is text, type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale. Also, see level 2 notes below.
TAX_AMOUNT N Subfield of LEVEL_2_DATA. Value is integer type, with max length of 13 algorisms. A value of zero is required in order to indicate tax exempt transactions. Also, see level 2 notes below.
SHIPPING_ADDRESS N Subfield of LEVEL_2_DATA. Subcomponent with all the data related to the shipping address of a purchase. Also, see level 2 notes below.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Also, see level 2 notes below.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Also, see level 2 notes below.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting. Also, see level 2 notes below.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. Also, see level 2 notes below.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. Also, see level 2 notes below.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
Page 31
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description Also, see Notes 3 and 4 below.
COUNTRY N Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. Also, see level 2 notes below.
FRAUDREVIEWSESSIONID
N This field should contain the value of THEIR_SESSION_ID parameter that a merchant integration uses to configure its session with ThreatMetrix. See Threat Metrix Notes below for more information.
CUSTOMFIELD N Should also use the “NAME” xml attribute to assign the name of the custom field. See section 3.4 for more info.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+SECRET
• Many code examples on how to generate an MD5 HASH can be found in the
Internet. For assistance, please contact GlobalOnePay support.
• For AVS checking, assuming an consumers address of 1234 Main Street,
Atlanta GA 30315, “1234 Main Street” will be placed in the Address1 field,
“Atlanta” will be placed in the Address2 field and “30315” will be placed in
the PostCode field.
Level 2 Notes:
• All the fields associated with the feature “Level II Data”, except for
SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory”
is checked in the Processing Terminal “Features” section.
• This field is associate with the feature “Level II Data”, and to be used is
necessary to set the “Allow Level II Data” option, on a Processing Terminal
“Features” section. And this feature is only available for TSYS Saratoga
Terminals.
Page 32
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The request component for LEVEL_2_DATA would look like this inside the request
body: <LEVEL_2_DATA> <CUSTOMER_REF_NUMBER></CUSTOMER_REF_NUMBER> <TAX_AMOUNT></TAX_AMOUNT> <SHIPPING_ADDRESS> <FULL_NAME></FULL_NAME> <ADDRESS1></ADDRESS1> <ADDRESS2></ADDRESS2> <CITY></CITY> <REGION></REGION> <POSTCODE></POSTCODE> <COUNTRY></COUNTRY> </SHIPPING_ADDRESS> </LEVEL_2_DATA>
ThreatMetrix Notes:
• If a merchant wishes to use ThreatMetrix on its website, it must insert the
ThreatMetrix scripts to its website. These scripts create a profile on
ThreatMetrix servers and are used to validate the users device. <!-- ThreatMetrix Profiling Tags --> <script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORD_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"> </script> <noscript> <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORG_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"> </iframe> </noscript>
• The parameters THEIR_ORG_ID and THEIR_SESSION_ID must be supplied
by the merchant.
Threat Metrix Pamareter Name
Description
THEIR_ORG_ID ThreatMetrix orgId which is set in their terminal settings on the gateway and/or from their ThreatMetrix portal. - Up to 32 Chars.
THEIR_SESSION_ID Session Id used to identify session. This must be generated for every new transaction/sale. Do not use a persistent session id. - It can be up to 128 bytes long and must only consist of the following characters - upper and lowercase English letters, digits, underscore or hyphen ([a-z], [A-Z], 0-9, _, -).
PAGEID The pageid is an identifier to be used if you place the tags on multiple pages.
Page 33
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields are returned in the response:
Field Name Description UNIQUEREF Generated reference that should be stored for
tracking and remote XML refunding. RESPONSECODE A or D or R (Approved or Declined or
Referral). RESPONSETEXT The text of the authorization. APPROVALCODE Six digit AuthCode. BANKRESPONSECODE Only sent on TSYS terminals. The TSYS
response code returned in the authorization response.
AUTHORIZEDAMOUNT Only sent for specific acquirers. Partial amount authorised for some transactions.
DATETIME The time of the transaction created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a differnet time.
AVSRESPONSE The result of the AVS check. See Appendix A for more information.
CVVRESPONSE The result of the CVV check. See Appendix A for more information.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
MASKEDCARDNUMBER If the “Show Masked Card Number in XML Response” property defined for the used Terminal (TERMINALID) is enabled, this field is going to be send back in the response, like: 444433******1111 (Shows the first 6 numbers and the last 4). Please contact GlobalOne to enable this feature.
HASH An MD5 HASH. See Note 2 below. FRAUDREVIEWRESPONSE Component of the response that is going to
be added in case the Threat Metrix feature is in use for the Terminal processing the Payment. See ThreatMetrix Notes below for more information
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT. See ThreatMetrix Notes below for more information.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NEUTRAL or TRUST. See ThreatMetrix Notes below for more information.
Page 34
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk). See ThreatMetrix Notes below for more information.
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk. See ThreatMetrix Notes below for more information.
Notes:
• The MD5 HASH response is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+
RESPONSETEXT+BANKRESPONSECODE+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME
+RESPONSECODE+RESPONSETEXT+SECRET
• The DATETIME is the time returned by the bank for the transaction.
ThreatMetrix Notes:
• This field is associate with the feature “Threat Metrix”, and to be used must
be enabled for your Gateway. Also, the Terminal used for processing the
request needs to be enabled for ThreatMetrix feature so your response
contains these fields
The response component FRAUDREVIEWRESPONSE would look like this inside the
response body: <FRAUDREVIEWRESPONSE> <FRAUDREVIEWSTATUS>PASS</FRAUDREVIEWSTATUS> <FRAUDREVIEWRISKRATING>LOW</FRAUDREVIEWRISKRATING> <FRAUDREVIEWSCORE>-10</FRAUDREVIEWSCORE> <FRAUDREVIEWREASONCODE>Profiling Blocked,Profiling Incomplete</FRAUDREVIEWREASONCODE> </FRAUDREVIEWRESPONSE>
• If a transaction is returned with “FRAUDREVIEWSTATUS” as “REVIEW”, this
transaction can be changed - manually (using the new report feature) or the
using the transaction update XML gateway service - to “APPROVE” or
“REJECT”.
Page 35
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• Transactions returned with “FRAUDREVIEWSTATUS” as “REVIEW” are not
going to be settled until the transaction status is changed (as defined on
Note 3). See Transaction Status Updates page for more details on how to use
the transaction update XML gateway service to change the transaction
returned as “REVIEW” to “REJECT” or “APPROVE”.
Error handling
If there is an error processing the transaction, the error string is returned in an
XML message with the simple tags below: <ERROR><ERRORSTRING></ERRORSTRING></ERROR>
Page 36
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
XML ACH Sale 5.1.2
The following is a simple example of a payment via an XML POST: <?xml version="1.0" encoding="UTF-8"?> <PAYMENTACH> <ORDERID>3472151837</ORDERID> <TERMINALID>2366006</TERMINALID> <AMOUNT>2.09</AMOUNT> <CURRENCY>USD</CURRENCY> <DATETIME>22-02-2017:18:02:31:849</DATETIME> <TERMINALTYPE>2</TERMINALTYPE> <SEC_CODE>CCD</SEC_CODE> <ACCOUNT_TYPE>CHECKING</ACCOUNT_TYPE> <ACCOUNT_NUMBER>2387654376</ACCOUNT_NUMBER> <ROUTING_NUMBER>101000187</ROUTING_NUMBER> <ACCOUNT_NAME>Test Consumer</ACCOUNT_NAME> <CHECK_NUMBER>1234</CHECK_NUMBER> <ADDRESS1>7th Avenu, 77</ADDRESS1> <ADDRESS2>5th Avenu, 13</ADDRESS2> <CITY>New York</CITY> <REGION>A1</REGION> <POSTCODE>117898</POSTCODE> <COUNTRY>US</COUNTRY> <PHONE>9563343234</PHONE> <IPADDRESS>192.168.0.1</IPADDRESS> <EMAIL>[email protected]</EMAIL> <DESCRIPTION>test</DESCRIPTION> <DL_STATE>NY</DL_STATE> <DL_NUMBER>4353446</DL_NUMBER> <HASH>ceb3fded5144eec6a8e821014f2e66f5</HASH> </PAYMENTACH>
Field Name Required Description
ORDERID Y A unique identifier for the order created by the merchant. (Max 12 Characters).
TERMINALID Y A Terminal ID provided by GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal
CURRENCY Y Must be “USD”. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. TERMINALTYPE Y The type of the terminal:
1 - MOTO (Mail Order/Telephone Order) 2 – eCommerce
ACH_SECURE N Y or N SEC_CODE Y See section 3.3 above. ACCOUNT_TYPE Y CHECKING or SAVINGS. Optional if
ACH_SECURE set to 'Y' ACCOUNT_NUMBER Y The ACH account number or ACH Secure
reference if ACH_SECURE set to 'Y'
Page 37
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description
ROUTING_NUMBER Y The ACH routing number. ACCOUNT_NAME Y The customer’s first and last name. CHECK_NUMBER N Check number ADDRESS1 N First line of customer’s address. See note
below. ADDRESS2 N Second line of customer’s address. See note
below. CITY N Customer’s home city. REGION N Customer’s region. POSTCODE N Customer’s post code. COUNTRY N Customer’s country. PHONE N Customer’s phone number. IPADDRESS N Customer’s IP address. EMAIL N Customer’s e-mail address. DESCRIPTION N Optional transaction description field. DL_STATE N Customers driving licence state. DL_NUMBER N Customers driving licence number. HASH Y An MD5 HASH. See Note 1 below.
Notes:
• The request MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+SECRET
For testing, this XML is posted to:
https://testpayments.globalone.me/merchant/xmlpayment
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8" ?> <PAYMENTACHRESPONSE> <UNIQUEREF>G6VPOBK1E7</UNIQUEREF> <RESPONSECODE>E</RESPONSECODE> <RESPONSETEXT>ACCEPTED</RESPONSETEXT> <APPROVALCODE>Success</APPROVALCODE> <DATETIME>2017-03-22T17:19:38</DATETIME> <HASH>a6cd3355928183ccb82dd8185ffcfd39</HASH> </PAYMENTACHRESPONSE>
Page 38
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields are returned in the response:
Field Name Description UNIQUEREF Generated reference that should be stored for tracking
and remote XML refunding. RESPONSECODE IA: Initial Approval or D: Declined. If IA is received,
then final approval will be provided by background notification.
RESPONSETEXT The text of the authorization. APPROVALCODE E:Initial Approval or D:Declined DATETIME The time of the transaction created by the bank.
Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
HASH An MD5 HASH. See Note below.
Notes:
• The response MD5 HASH is generated using the following as an input
string:
TERMINALID+ORDERID+UNIQUEREF+AMOUNT+DATETIME+
RESPONSECODE+RESPONSETEXT+SECRET
For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+UNIQUEREF+CURRENCY+AMOUNT+
DATETIME+ RESPONSECODE+RESPONSETEXT+SECRET
• Many code examples on how to generate an MD5 HASH can be found in the
Internet. For assistance, please contact GlobalOnePay support.
• For Address1 and Address2 fields, assuming a consumers address of 1234 Main
Street Apartment #201, Atlanta GA 30315, “1234 Main Street” will be placed in
the Address1 field, “Apartment #201” will be placed in the Address2 field,
“Atlanta” will be placed in the City field and “30315” will be placed in the
PostCode field. Valid country codes will be placed within the Region field.
Page 39
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Error handling
If there is an error processing the transaction, the error string is returned in an
XML message with the simple: <ERROR> <ERRORCODE>E01</ERRORCODE> <ERRORSTRING>Invalid ACH Order ID</ERRORSTRING> </ERROR>
A listing of potential error results is listed in Appendix G Gateway Secure ACH Error
Codes.
Pre-Authorization Request 5.1.3
Pre-authorization transactions are supported only by a subset of our acquirers;
please contact us for more information regarding your acquirer. 3D Secure pre-auth
transactions are not supported due to scheme restrictions.
Example of a XML Pre-Auth request: <?xml version="1.0" encoding="UTF-8"?> <PREAUTH> <ORDERID>100028374319</ORDERID> <TERMINALID>6491999</TERMINALID> <AMOUNT>15.62</AMOUNT> <DATETIME>18-12-2008:09:24:16:105</DATETIME> <CARDNUMBER>4111111111111111</CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>1109</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME> <HASH>9c58e8d7ff9eb98db4ece2af75dec6ae</HASH> <CURRENCY>EUR</CURRENCY> <TERMINALTYPE>1</TERMINALTYPE> <TRANSACTIONTYPE>7</TRANSACTIONTYPE> <CVV>214</CVV> </PREAUTH>
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8"?> <PREAUTHRESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>475318</APPROVALCODE> <DATETIME>2008-12-18T09:24:17</DATETIME> <CVVRESPONSE>M</CVVRESPONSE> <HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH> <PROCESSINGTERMINAL>6491002</PROCESSINGTERMINAL> </PREAUTHRESPONSE>
Page 40
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Payment request fields description:
Field Name Required Description ORDERID Y A unique identifier for the order created by
the merchant. (Max 12 Characters). TERMINALID Y A Terminal ID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. CARDNUMBER N The payment card number. CARDTYPE Y See section 3.2 above. CARDEXPIRY N 4 digit expiry field (MMYY), required if not
using a SecureCard. CARDHOLDERNAME N The name of the card holder, required if
not using a SecureCard. HASH Y An MD5 HASH. See Note 1 below. CURRENCY Y A 3 character currency code of the
transaction. ISO 4217 Currency Code. FOREIGNCURRENCYINFORMATION
N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions. See XML Payments with eDCC.
TERMINALTYPE Y The type of the terminal: 1 - MOTO (Mail Order/Telephone Order) 2 - eCommerce
TRANSACTIONTYPE Y Normally: 4 - MOTO (Mail Order/Telephone Order) 7 – eCommerce Recurring Payment Flagging: 2 – Specify that this transaction is recurring. This must be accompanied by the RECURRINGTXNREF field or have special permission granted by the Gateway. Not all processors support this transaction type and consultation with the integration team should be carried out prior to configuring recurring payment flagging. For First Data Latvia terminal MOTO transactions: 4 - Telephone Order 9 - Mail Order If sending XID & CAVV from non-
Page 41
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description GlobalOnePay MPI on an eCommerce transaction use: 0 - not applicable 1 - Single transaction 2 - Recurring transaction 3 - Installment payment 4 - Unknown classification 5 - Fully authenticated transaction 3D Secure transaction 6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not participate in 3D-Secure. 7 - Transaction when payment data was transmitted using SSL encryption, or Channel Encrypted 8 - Transaction in the clear, or Non Secure
EMAIL N Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by the SelfCare Terminal Setup setting “Disable Cardholder Receipt”.
CVV N The security code entered by the card holder.
ISSUENO N The issue no. of the card (Solo). ADDRESS1 N First line of the customer’s address.This is
an AVS field (See Glossary) and is mandatory if, and only if, the Terminal settings define that. If “Enable AVS” is set, the verification will be performed when there's data, and if “AVS Compulsory” is set, at least the POSTCODE is mandatory. ADDRESS1 and ADDRESS2 are mandatory in two cases: if during the sale the user defines the field AVS, at the virtual terminal, as “Exact”; and when using a payment integration interface (XML Gateway or HPP) the “API AVS Type” is defined as “Exact".
ADDRESS2 N The second address field for AVS. See note below.
POSTCODE N The postcode (required) for AVS. Also required for MaxMind MinFraud fraud scoring.
DESCRIPTION N A description of the transaction. CITY N Required for MaxMind MinFraud fraud
scoring. REGION N Required for MaxMind MinFraud fraud
Page 42
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description scoring. See MaxMind definition of this field as it is forwarded to them without modification.
COUNTRY N ISO 3166-1-alpha-2 code. Required for MaxMind MinFraud fraud scoring.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. Also, see level 2 notes below.
CUSTOMER_REF_NUMBER
N Subfield of LEVEL_2_DATA. Value is text, type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale. Also, see level 2 notes below.
TAX_AMOUNT N Subfield of LEVEL_2_DATA. Value is integer type, with max length of 13 algorisms. A value of zero is required in order to indicate tax exempt transactions. Also, see level 2 notes below.
SHIPPING_ADDRESS N Subfield of LEVEL_2_DATA. Subcomponent with all the data related to the shipping address of a purchase. Also, see level 2 notes below.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Also, see level 2 notes below.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Also, see level 2 notes below.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting. Also, see level 2 notes below.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. Also, see level 2 notes below.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. Also, see level 2 notes below.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters. Also, see Notes 3 and 4 below.
Page 43
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description COUNTRY N Subfield of SHIPPING_ADDRESS. Value is
text type, with 2 characters. ISO ALPHA-2 Country Code. Also, see level 2 notes below.
FRAUDREVIEWSESSIONID
N This field should contain the value of THEIR_SESSION_ID parameter that a merchant integration uses to configure its session with ThreatMetrix. See Threat Metrix Notes below for more information.
CUSTOMFIELD N Should also use the “NAME” xml attribute to assign the name of the custom field. See Note 3 in PAYMENT section.
RECURRINGTXNREF N Should be set to the value of a UNIQUEREF returned in a PAYMENT response for a non-recurring approved transaction on a matching card. TRANSACTIONTYPE should be set to 2.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+SECRET
• Many code examples on how to generate an MD5 HASH can be found in the
Internet. For assistance, please contact GlobalOnePay.
• For AVS checking, assuming an consumers address of 1234 Main Street,
Atlanta GA 30315, “1234 Main Street” will be placed in the Address1 field,
“Atlanta” will be placed in the Address2 field and “30315” will be placed in
the PostCode field.
Level 2 Notes:
• All the fields associated with the feature “Level II Data”, except for
SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory”
is checked in the Processing Terminal “Features” section.
• This field is associate with the feature “Level II Data”, and to be used is
necessary to set the “Allow Level II Data” option, on a Processing Terminal
Page 44
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
“Features” section. And this feature is only available for TSYS Saratoga
Terminals.
The request component for LEVEL_2_DATA would look like this inside the request
body: <LEVEL_2_DATA> <CUSTOMER_REF_NUMBER></CUSTOMER_REF_NUMBER> <TAX_AMOUNT></TAX_AMOUNT> <SHIPPING_ADDRESS> <FULL_NAME></FULL_NAME> <ADDRESS1></ADDRESS1> <ADDRESS2></ADDRESS2> <CITY></CITY> <REGION></REGION> <POSTCODE></POSTCODE> <COUNTRY></COUNTRY> </SHIPPING_ADDRESS> </LEVEL_2_DATA>
ThreatMetrix Notes:
• If a merchant wishes to use ThreatMetrix on its website, it must insert the
ThreatMetrix scripts to its website. These scripts create a profile on
ThreatMetrix servers and are used to validate the users device. <!-- ThreatMetrix Profiling Tags --> <script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORD_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"> </script> <noscript> <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORG_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"> </iframe> </noscript>
• The parameters THEIR_ORG_ID and THEIR_SESSION_ID must be supplied
by the merchant.
Threat Metrix Pamareter Name
Description
THEIR_ORG_ID ThreatMetrix orgId which is set in their terminal settings on the gateway and/or from their ThreatMetrix portal. - Up to 32 Chars.
THEIR_SESSION_ID Session Id used to identify session. This must be generated for every new transaction/sale. Do not use a persistent session id. - It can be up to 128 bytes long and must only consist of the following characters - upper and
Page 45
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
lowercase English letters, digits, underscore or hyphen ([a-z], [A-Z], 0-9, _, -).
PAGEID The pageid is an identifier to be used if you place the tags on multiple pages.
The following fields are returned in the response:
Field Name Description UNIQUEREF Generated reference that should be stored
for tracking and remote XML refunding. RESPONSECODE A or D or R (Approved or Declined or
Referral). RESPONSETEXT The text of the authorization. BANKRESPONSECODE Only sent on TSYS terminals. The TSYS
response code returned in the authorization response.
APPROVALCODE Six digit AuthCode. DATETIME The time of the transaction created by the
bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
AVSRESPONSE The result of the AVS check. See Appendix A for more information.
CVVRESPONSE The result of the CVV check. See Appendix A for more information.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
MASKEDCARDNUMBER If the “Show Masked Card Number in XML Response” property defined for the used Terminal (TERMINALID) is enabled, this field is going to be send back in the response, like: 444433******1111 (Shows the first 6 numbers and the last 4).
HASH An MD5 HASH. See Note2 below. FRAUDREVIEWRESPONSE Component of the response that is going to
be added in case the Threat Metrix feature is in use for the Terminal processing the Payment. See ThreatMetrix Notes below for more information
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT. See ThreatMetrix Notes below for more information.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NEUTRAL or
Page 46
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
TRUST. See ThreatMetrix Notes below for more information.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk). See ThreatMetrix Notes below for more information.
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk. See ThreatMetrix Notes below for more information.
Notes:
• The MD5 HASH response is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+
RESPONSETEXT+BANKRESPONSECODE+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+
RESPONSECODE+RESPONSETEXT+SECRET
• The DATETIME is the time returned by the bank for the transaction.
ThreatMetrix Notes:
• This field is associate with the feature “Threat Metrix”, and to be used must
be enabled for your Gateway. Also, the Terminal used for processing the
request needs to be enabled for ThreatMetrix feature so your response
contains these fields
The response component FRAUDREVIEWRESPONSE would look like this inside the
response body: <FRAUDREVIEWRESPONSE> <FRAUDREVIEWSTATUS>PASS</FRAUDREVIEWSTATUS> <FRAUDREVIEWRISKRATING>LOW</FRAUDREVIEWRISKRATING> <FRAUDREVIEWSCORE>-10</FRAUDREVIEWSCORE> <FRAUDREVIEWREASONCODE>Profiling Blocked,Profiling Incomplete</FRAUDREVIEWREASONCODE> </FRAUDREVIEWRESPONSE>
• If a transaction is returned with “FRAUDREVIEWSTATUS” as “REVIEW”, this
transaction can be changed - manually (using the new report feature) or the
using the transaction update XML gateway service - to “APPROVE” or
“REJECT”.
Page 47
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• Transactions returned with “FRAUDREVIEWSTATUS” as “REVIEW” are not
going to be settled until the transaction status is changed (as defined on
Note 3). See Transaction Status Updates page for more details on how to use
the transaction update XML gateway service to change the transaction
returned as “REVIEW” to “REJECT” or “APPROVE”.
Error handling
If there is an error processing the transaction, the error string is returned in an
XML message with the simple tags: <ERROR><ERRORSTRING></ERRORSTRING></ERROR>
Page 48
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Pre-Auth Completion Request 5.1.4
Example of a Pre-Auth completion request: <?xml version="1.0" encoding="UTF-8"?> <PREAUTHCOMPLETION> <UNIQUEREF>JJCVGCTOV3</UNIQUEREF> <TERMINALID>6491002</TERMINALID> <AMOUNT>12.31</AMOUNT> <DATETIME>19-12-2008:14:47:51:307</DATETIME> <CVV>785</CVV> <HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH> </PREAUTHCOMPLETION>
For testing, this XML is posted to:
https://testpayments.globalone.me/merchant/xmlpayment
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8"?> <PREAUTHCOMPLETIONRESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>515658</APPROVALCODE> <DATETIME>2008-12-18T14:47:51</DATETIME> <HASH>93527dbb00534a4b33546161aefe5222</HASH> </PREAUTHCOMPLETIONRESPONSE>
Pre-Auth Completion request fields description:
Field Name Required Description UNIQUEREF Y A unique identifier for the order created by
the merchant. (Max 12 Characters).The UNIQUEREF for the original authorisation.
TERMINALID Y A TerminalID provided by GlobalOnePay. AMOUNT Y The amount of the transaction as a 2 digit
decimal or an integer value for JPY amounts.
FOREIGNCURRENCYINFORMATION
N Tag contains Dynamic Currency Conversion information. It is required when completing out of the 15% margin eDCC transaction. See XML Payments with eDCC.
DESCRIPTION N An optional description, overrides original pre-auth description if available.
DATETIME Y Format DD-MM-YYYY:HH:MM:SS:SSS. CVV N The security code entered by the card
holder. It should be available when CVV is enabled for a terminal and completing out of the 15% margin transaction.
HASH Y An MD5 HASH (See Note 1 below).
Page 49
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields are returned in the response:
Field Name Description RESPONSECODE A or D or R(Approved or Declined or Referral). RESPONSETEXT The text of the authorization. APPROVALCODE Six digit AuthCode. DATETIME The time of the transaction created by the
bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
AVSRESPONSE The result of the AVS check. See Appendix A for more information.
CVVRESPONSE The result of the CVV check. See Appendix A for more information.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
HASH An MD5 HASH. See Note2 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+
RESPONSECODE+RESPONSETEXT+SECRET
• The MD5 HASH response is generated using the following as an input
string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+
RESPONSECODE+RESPONSETEXT+SECRET
Error handling
If there is an error processing the transaction, the error string is returned in an
XML message with the simple tags below: <ERROR><ERRORSTRING></ERRORSTRING></ERROR>
Page 50
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Standard Refunds 5.1.5
Standard refunds can be performed on any authorised ACH or Credit transaction in
the GlobalOnePay system, either in the Open Batch or Closed Batch. By default you can
refund any amount up to 100% of the original transaction value. If multiple partial
refunds are performed then the sum total of them cannot exceed 100% either. This is to
prevent fraud. This 100% value is configurable at a Terminal level and if you wish to alter
it please contact GlobalOnePay support for determining if the transaction should be
adjusted.
The following is a simple example of a refund via an XML POST: <?xml version="1.0" encoding="UTF-8"?> <REFUND> <UNIQUEREF>Q8F40S2V</UNIQUEREF> <TERMINALID>6491002</TERMINALID> <AMOUNT>10.00</AMOUNT> <DATETIME>20-06-2006:12:28:02:171</DATETIME> <HASH>cfa094f53a508d2031c7895f9f766cbb</HASH> <OPERATOR>Test Operator</OPERATOR> <REASON>Faulty Goods</REASON> </REFUND>
For testing, this XML is posted to:
https://testpayments.globalone.me/merchant/xmlpayment
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8"?> <REFUNDRESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>SUCCESS</RESPONSETEXT> <UNIQUEREF>JJCVGCTOV3</UNIQUEREF> <TERMINALID>6491002</TERMINALID> <AMOUNT>10.00</AMOUNT> <DATETIME>20-06-2006:12:28:03:875</DATETIME> <HASH>6a06aa6f14fe539f4dedd305465811ab</HASH> </REFUNDRESPONSE>
The GlobalOnePay payment system then handles subsequent transaction
settlement and storage.
The following is a description of each field:
Field Name Required Description UNIQUEREF Y The UNIQUEREF for the original
authorisation. TERMINALID Y A TerminalID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be
Page 51
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
issued with a test terminal ID. AMOUNT Y The amount of the transaction as a 2
digits decimal or an Integer value for JPY amounts.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note 1 below. OPERATOR Y An identifier for who executed this
transaction. REASON Y The reason for the refund.
The following fields are returned in the response:
Field Name Description RESPONSECODE A or D (Approved or Declined). RESPONSETEXT The text of the authorization. UNIQUEREF The UNIQUEREF for this refund. TERMINALID A Terminal ID provided by GlobalOnePay. NB
– Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT The amount of the transaction as a 2 digit decimal or an integer value for JPY amounts.
DATETIME Format DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See note 2 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+SECRET
• The MD5 HASH response is generated using the following as an input
string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE
+RESPONSETEXT+SECRET (n.b. the response UNIQUEREF is to be used
here)
Page 52
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Unreferenced Refunds 5.1.6
Unreferenced refunds are refunds that do not require a sale transaction to be
referenced to. They are only available on certain accounts by request from GlobalOnePay
support and must also be approved by your acquiring (merchant) bank.
The following is a simple example of an unreferenced refund via an XML POST: <?xml version="1.0" encoding="UTF-8"?> <UNREFERENCEDREFUND> <ORDERID>115073134</ORDERID> <TERMINALID>6491002</TERMINALID> <CARDDETAILS> <CARDTYPE>VISA</CARDTYPE> <CARDNUMBER>4111111111111111</CARDNUMBER> <CARDEXPIRY>0807</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME> </CARDDETAILS> <AMOUNT>10.00</AMOUNT> <EMAIL>[email protected]</EMAIL> <DATETIME>20-06-2006:12:28:02:171</DATETIME> <HASH>cfa094f53a508d2031c7895f9f766cbb</HASH> <OPERATOR>Test Operator</OPERATOR> </UNREFERENCEDREFUND>
The following is a simple example of an unreferenced refund on a SecureCard via
an XML POST: <?xml version="1.0" encoding="UTF-8"?> <UNREFERENCEDREFUND> <ORDERID>115073134</ORDERID> <TERMINALID>6491002</TERMINALID> <CARDREFERENCE>2967534771694736</CARDREFERENCE> <AMOUNT>10.00</AMOUNT> <EMAIL>[email protected]</EMAIL> <DATETIME>20-06-2006:12:28:02:171</DATETIME> <HASH>cfa094f53a508d2031c7895f9f766cbb</HASH> <OPERATOR>Test Operator</OPERATOR> </UNREFERENCEDREFUND>
For testing, this XML is posted to:
https://testpayments.globalone.me/merchant/xmlpayment
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8"?> <UNREFERENCEDREFUNDRESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>SUCCESS</RESPONSETEXT> <UNIQUEREF>G53D0M1S4</UNIQUEREF> <TERMINALID>6491002</TERMINALID> <AMOUNT>10.00</AMOUNT> <DATETIME>20-06-2006:12:28:03:875</DATETIME> <HASH>6a06aa6f14fe539f4dedd305465811ab</HASH> </UNREFERENCEDREFUNDRESPONSE>
Page 53
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following is a description of each field:
Field Name Required Description ORDERID Y A unique identifier for the order created
by the merchant. (Max 12 Characters). TERMINALID Y A TerminalID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be issued with a test terminal ID.
CARDREFERENCE N If using a SecureCard then this tag must contain a valid SecureCard Card Reference.
CARDDETAILS N If not using a SecureCard then this tag must be populated.
CURRENCY N A 3 character currency code of the transaction. ISO 4217 Currency Code. Required only for multi-currency Terminal IDs (see section 3.3)
AMOUNT Y The amount of the transaction as a 2 digits decimal or an Integer value for JPY amounts.
AUTOREADY N Y or N. Automatically set the transaction to Ready in the batch. If not present the terminal default will be used.
EMAIL N An email address to send a confirmation email to. Normally this is cardholder email address.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note 1 below. OPERATOR Y An identifier for who executed this
transaction. DESCRIPTION N The description for the refund.
The following fields are returned in the response:
Field Name Description RESPONSECODE A or D (Approved or Declined). RESPONSETEXT The text of the authorization. UNIQUEREF The UNIQUEREF for this refund. TERMINALID A Terminal ID provided by GlobalOnePay. NB –
Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT The amount of the transaction as a 2 digit decimal or an integer value for JPY amounts.
DATETIME Format DD-MM-YYYY:HH:MM:SS:SSS. PROCESSINGTERMINAL If the transaction was performed on a “routing
terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
HASH An MD5 HASH. See note 2 below.
Page 54
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+CARDTYPE+CARDNUMBER+CARDEXPIRY
+CARDHOLDERNAME+AMOUNT+DATETIME+SECRET
• For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+CARDTYPE+CARDNUMBER+CARDEXPIRY
+CARDHOLDERNAME+CURRENCY+AMOUNT+DATETIME+SECRET
• If using a SecureCard (CARDREFERNCE tag) then the MD5 HASH is
generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+SECRET
For multi-currency Terminal IDs (see section 3.3 above) this should be:
TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME
+SECRET
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE
+RESPONSETEXT+SECRET
CARDDETAILS tag in XML Requests 5.1.7
Some XML packets require the options CARDDETAILS tag and it nested tags.
There is an example of Foreign Currency information in the XML payment request: <CARDDETAILS> <CARDTYPE>VISA</CARDTYPE> <CARDNUMBER>4444333322221111</CARDNUMBER> <CARDEXPIRY>1120</CARDEXPIRY> <CARDHOLDERNAME>0.667157</CARDHOLDERNAME> </CARDDETAILS>
Description of FOREIGNCURRENCYINFORMATION fields:
Field Name Required Description CARDTYPE Y See section 3.2 above. CARDNUMBER Y The payment card number (PAN). CARDEXPIRY Y 4 digit expiry field (MMYY). CARDHOLDERNAME Y The name of the card holder.
Page 55
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
5.2 XML Requests with eDCC
Direct XML transactions (Payment, Pre-Auth and Pre-Auth Completion) can be DCC
(Dynamic Currency Conversion) enabled. This is useful when card and terminal
currencies are different. GlobalOnePay support Currency Conversion Rate request,
merchant application can request Conversion Rate for the card, then cardholder have to
decide if he/she would like to use eDCC service, and after this appropriate request to the
TPS will be sent. eDCC enabled XML transaction request should include additional tag -
‘FOREIGNCURRENCYINFORMATION’ with all required nested tags.
DCC transactions are allowed for the eDCC-enabled terminals only. DCC support for
the terminal can be enabled or disabled by the GlobalOnePay support team only. DCC is
not available on multi-currency Terminals (see section 3.3).
eDCC Exchange Rate Request 5.2.1
The following is an example of a Conversion Rate request for the Terminal ID and
BIN: <?xml version="1.0" encoding="UTF-8"?> <GETCARDCURRENCYRATE> <TERMINALID>1001</TERMINALID> <CARDBIN>411111</CARDBIN> <DATETIME>27-06-2007:16:50:02:123</DATETIME> <HASH>15f6c0f0b51faff9cbb77220ab8ddfce</HASH> </GETCARDCURRENCYRATE>
Fields description:
Field Name Required Description TERMINALID Y A TerminalID provided by
GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
CARDBIN Y BIN. The first 6 digits from the Card Number.
BASEAMOUNT N Transaction amount in the base currency. If sent GlobalOnePay will return the correctly formatted and calculated FOREIGNAMOUNT.
DATETIME Y Request Date and Time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y An MD5 HASH. See Note below.
Page 56
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+CARDBIN+DATETIME+SECRET
A response for this request would be: <CARDCURRENCYRATERESPONSE> <TERMINALCURRENCY>EUR</TERMINALCURRENCY> <CARDCURRENCY>GBP</CARDCURRENCY> <CONVERSIONRATE>0.667157</CONVERSIONRATE> <DATETIME>27-06-2007:16:50:02:999</DATETIME> <EXCHANGERATESOURCENAME>Imaginary Bank</EXCHANGERATESOURCENAME> <MARGINPERCENTAGE>1.50</MARGINPERCENTAGE> <COMMISSIONPERCENTAGE>1.00</COMMISSIONPERCENTAGE> <FOREIGNAMOUNT>15.98</FOREIGNAMOUNT> <HASH>a12a10322f5af4a8a419f7dc1c6dd39f</HASH> </CARDCURRENCYRATERESPONSE>
The following fields will be returned in the response:
Field Name Description TERMINALCURRENCY Terminal’s currency code. ISO 4217 Currency
Code. CARDCURRENCY Card’s currency code. ISO 4217 Currency
Code. CONVERSIONRATE Conversion rate. See Note 2 below. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. EXCHANGERATESOURCENAME Source of rates. Display on decision page. MARGINPERCENTAGE Margin percentage applied. COMMISSIONPERCENTAGE Commission percentage applied. FOREIGNAMOUNT Converted amount. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALCURRENCY+CARDCURRENCY+CONVERSIONRATE
+DATETIME+SECRET
• In this string CONVERSIONRATE must be a decimal value with 6 decimal
places separated by dot character (‘.’), example: ‘0.123000’. The secret
should be set by merchant in the selfcare section.
Page 57
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Error handling
If there is an error processing the request, the error string is returned in an XML
message with the simple tags below: <ERROR><ERRORSTRING></ERRORSTRING></ERROR>
There is list of error codes and their brief descriptions:
Error Code Description 101 Terminal not found. 102 BIN not found. 103 Currencies are the same. 104 eDCC is not allowed for the terminal. 105 Invalid card currency/Unknown currency. 106 Conversion rate not found. 107 Invalid request format. 108 Invalid hash in the request. 109 Other error. 110 Internal error. 111 Unsupported card currency.
Notes:
• Some errors can have more informative message. For example error with
code 107 may have detailed information on wrong or expected tag(s) in
the XML.
eDCC Information in the XML Requests 5.2.2
When the eDCC feature is enabled, XML requests must include
FOREIGNCURRENCYINFORMATION tag and it nested tags.
There is an example of Foreign Currency information in the XML payment request: <FOREIGNCURRENCYINFORMATION> <CARDCURRENCY>GBP</CARDCURRENCY> <CARDAMOUNT>6.67</CARDAMOUNT> <CONVERSIONRATE>0.667157</CONVERSIONRATE> </FOREIGNCURRENCYINFORMATION>
Description of FOREIGNCURRENCYINFORMATION fields:
Field Name Required Description FOREIGNCURRENCYINFORMATION
N Outer tag for Currency Conversion Rate informative fields.
CARDCURRENCY Y Card’s currency code. CARDAMOUNT Y Amount which supposed to be charged
Page 58
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
in the home currency. CONVERSIONRATE Y Value received in the Conversion Rate
request should be there. Processing bank (EuroConex) will decline transaction if wrong rate will be there.
Example of a Payment transaction with eDCC: <?xml version="1.0" encoding="UTF-8"?> <PAYMENT> <ORDERID>1150109224656</ORDERID> <TERMINALID>6491002</TERMINALID> <AMOUNT>10</AMOUNT> <DATETIME>12-06-2006:11:47:04:656</DATETIME> <CARDNUMBER>4111111111111111</CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>0807</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> <CURRENCY>EUR</CURRENCY> <FOREIGNCURRENCYINFORMATION> <CARDCURRENCY>GBP</CARDCURRENCY> <CARDAMOUNT>6.67</CARDAMOUNT> <CONVERSIONRATE>0.667157</CONVERSIONRATE> </FOREIGNCURRENCYINFORMATION> <TERMINALTYPE>1</TERMINALTYPE> <TRANSACTIONTYPE>7</TRANSACTIONTYPE> <CVV>214</CVV> </PAYMENT>
Example of an eDCC Pre-Auth transaction: <?xml version="1.0" encoding="UTF-8"?> <PREAUTH> <ORDERID>100028374319</ORDERID> <TERMINALID>6491002</TERMINALID> <AMOUNT>15.62</AMOUNT> <DATETIME>18-12-2008:09:24:16:105</DATETIME> <CARDNUMBER>4111111111111111</CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>1109</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME> <HASH>9c58e8d7ff9eb98db4ece2af75dec6ae</HASH> <CURRENCY>EUR</CURRENCY> <FOREIGNCURRENCYINFORMATION> <CARDCURRENCY>GBP</CARDCURRENCY> <CARDAMOUNT>10.42</CARDAMOUNT> <CONVERSIONRATE>0.667157</CONVERSIONRATE> </FOREIGNCURRENCYINFORMATION> <TERMINALTYPE>1</TERMINALTYPE> <TRANSACTIONTYPE>7</TRANSACTIONTYPE> <CVV>214</CVV> </PREAUTH>
Page 59
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Example of out of 15% margin eDCC Pre-Auth Completion transaction: <?xml version="1.0" encoding="UTF-8"?> <PREAUTHCOMPLETION> <ORDERID>100028374123</ORDERID> <TERMINALID>1001</TERMINALID> <AMOUNT>22.38</AMOUNT> <FOREIGNCURRENCYINFORMATION> <CARDCURRENCY>GBP</CARDCURRENCY> <CARDAMOUNT>14.93</CARDAMOUNT> <CONVERSIONRATE>0.667157</CONVERSIONRATE> </FOREIGNCURRENCYINFORMATION> <DATETIME>19-12-2008:14:47:51:307</DATETIME> <CVV>785</CVV> <HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH> </PREAUTHCOMPLETION>
Notes:
• Foreign currency information in the completion request is useful when
completing an “out of 15% tolerance” transaction, because the original
pre-auth transaction will be reversed and a new PAYMENT transaction will
be authorized instead, and the foreign currency details provided will be
used for the new transaction.
• The original pre-auth exchange rate is used when an eDCC transaction
within the 15% tolerance is completed
5.3 Transaction Status Updates
Transaction updates allow you to update the status of a transaction in the Open
Batch. You need to know the existing status of the transactions in order to update it.
Attention: Transactions statuses can be updated as long as the change respect
the following constraints.
Changing FROMSTATUS to TOSTATUS READY PENDING DECLINED READY NO YES NO PENDING YES NO NO REFERRAL YES YES NO REVIEW YES YES YES
Page 60
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following is a simple example of an update via an XML POST: <?xml version="1.0" encoding="UTF-8"?> <TRANSACTIONUPDATE> <UNIQUEREF>Q8F40S2V</UNIQUEREF> <TERMINALID>6491002</TERMINALID> <OPERATOR>Test Operator</OPERATOR> <FROMSTATUS>PENDING</FROMSTATUS> <TOSTATUS>READY</TOSTATUS> <DATETIME>20-06-2006:12:28:02:171</DATETIME> <HASH>cfa094f53a508d2031c7895f9f766cbb</HASH> </TRANSACTIONUPDATE>
For testing, this XML is posted to:
https://testpayments.globalone.me/merchant/xmlpayment
A response for this transaction would be: <?xml version="1.0" encoding="UTF-8"?> <TRANSACTIONUPDATERESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>SUCCESS</RESPONSETEXT> <UNIQUEREF>JJCVGCTOV3</UNIQUEREF> <TERMINALID>6491002</TERMINALID> <DATETIME>20-06-2006:12:28:03:875</DATETIME> <HASH>6a06aa6f14fe539f4dedd305465811ab</HASH> </TRANSACTIONUPDATERESPONSE>
The following is a description of each field:
Field Name Required Description UNIQUEREF Y The UNIQUEREF for the transaction
being updated. TERMINALID Y A TerminalID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be issued with a test terminal ID.
OPERATOR Y An identifier for who executed this update.
FROMSTATUS Y The current status of the transaction. Can be READY, PENDING or REFERRAL
TOSTATUS Y New status for the transaction. Can go from: REFERRAL to PENDING or READY, PENDING to READY, READY to PENDING.
AUTHCODE N The approval code of of the referral. Only required if changing a REFERRAL to PENDING or READY.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note 1 below.
Page 61
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields are returned in the response:
Field Name Description RESPONSECODE Updated transaction Response Code. RESPONSETEXT Updated transaction Response Text. UNIQUEREF The UNIQUEREF for this transaction. TERMINALID A Terminal ID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be issued with a test terminal ID.
DATETIME Format DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See note 2 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+OPERATOR+FROMSTATUS+TOSTATUS
+APPROVALCODE+DATETIME+SECRET
• The MD5 HASH is generated using the following as an input string:
TERMINALID+RESPONSECODE+RESPONSETEXT+UNIQUEREF+
DATETIME+SECRET
5.4 3D Secure For XML Transactions (GlobalOnePay MPI)
To simplify 3D Secure integration using XML payments, GlobalOnePay provides a
simple MPI redirect. To allow 3D Secure transactions for a terminal it should be
configured and registered with the card schemes, please contact the GlobalOnePay
support team for details.
The merchants application should redirect the cardholder’s browser to the URL:
https://testpayments.globalone.me/merchant/mpi
The above URL should be used in test mode only, please contact the GlobalOnePay
support team to receive the live URL.
Cardholder will have to pass the 3D Secure check, check result will be sent back to
the merchant application as a GET request. Processing result response will include
MPIREF parameter, which should be included in the XML payment request.
Page 62
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following parameters should be passed in the request:
Field Name Required Description TERMINALID Y A Terminal ID provided by GlobalOnePay. NB –
Please contact GlobalOnePay to be issued with a test terminal ID.
CARDNUMBER Y The payment card number. CARDEXPIRY Y 4 digit expiry field (MMYY). CARDTYPE Y See section 3.2 above. AMOUNT Y The amount of the transaction as a 2 digit
decimal or an Integer value for JPY amounts. CURRENCY Y A 3 character currency code of the
transaction. ORDERID Y A unique identifier for the order created by the
merchant. (Max 12 Characters). CVV N The security code entered by the card holder. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+CARDNUMBER+CARDEXPIRY+CARDTYPE
+AMOUNT+DATETIME+SECRET
The following parameter are returned to a merchant application:
Field Name Description RESULT MPI processing result:
A – Approved D – Declined
MPIREF MPI reference, this value should be sent in the XML payment request if received from the GlobalOnePay MPI.
ORDERID Original order identifier. STATUS A - An attempt at authentication was performed (ECI: 06)
N - Authentication attempt not performed (ECI: 06) U - Unable to authenticate (ECI: 07 or 06) Y - Authentication attempted and succeeded (ECI: 05)
ECI 05 - Full 3D Secure authentication 06 - Issuer and/or cardholder are not enrolled for 3D Secure 07 - 3D Secure authentication attempt failed (numerous possible reasons) (Visa only)
DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Page 63
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
RESULT+MPIREF+ORDERID+DATETIME+SECRET
After the merchant application will receives the 3D Secure check result, it should
send an XML payment request. If the 3D Secure check was successful (‘A’ Result) the
payment request should contain the fields MPIREF, Order ID and Terminal ID and they
should be the same as in the 3D Secure request. If the 3D Secure check was not
successful (‘D’ Result) the application can send a non-3D Secure transaction (MPIREF
will not be available in such case) or don’t send payment transaction at all. We
recommend that the transaction should be marked as declined in your system if our MPI
rejects the transaction.
Page 64
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
6. Secure Card Storage
Secure Card Storage is the storage/tokenisation of sensitive card information in the
GlobalOnePay system for use at a later date. It is a requirement for all (ACH and Credit)
Subscription processing. It is useful for merchants that are required to perform regular
payments without the card holder entering their information. Only PCI-DSS certified
merchants are allowed to store card details themselves.
6.1 Merchant Portfolio Level Secure Card processing
GlobalOnePay provides the ability for a Secure Card token stored under one
terminal ID to be used for payments on other terminals IDs. This is limited to Terminal
IDs that are under merchants that are configured to be within the same “Merchant
Portfolio” (a merchant portfolio is a group of merchants in our system).
In this scenario, the Secure Card is registered under one terminal ID as normal
(this is called the “Terminal Holder” terminal, or the parent terminal of the token) and a
list of permitted terminal IDs is sent in the registration request. If successfully registered
then all the other terminal IDs will be able to process payments on that token or search
for the token. Only requests to the terminal holder (parent) terminal ID will be able to
update or delete the token though.
If successfully registered, then all the allowed Terminals will be able to process
payments on that token or search for the token, but only requests the parent Terminal
will be able to update or delete the token, though.
6.2 Secure Card Registration and Updating From the Hosted
Page
Secure Card details can be registered or updated using the GlobalOnePay hosted
page by the cardholder, card details will be stored using GlobalOnePay Secure Card
Storage.
To initiate a Secure Card registration or update a POST must be made to the
following URL:
https://testpayments.globalone.me/merchant/securecardpage
Page 65
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following table describes the form fields to be posted:
Field Name Required Description ACTION Y register
update TERMINALID Y A TerminalID provided by
GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
MERCHANTREF Y Unique Reference assigned by the merchants site/software to identify the stored card details. Length is limited to 48 chars.
PERMITTEDTERMINALS
N List of permitted terminals. Comma separated list without spaces.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS
HASH Y An MD5 HASH. See Note below.
Notes:
• If permitted terminals are not used, the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+DATETIME+ACTION+SECRET
• If permitted terminals are used, The MD5 HASH of the request is
generated using the following as an input string:
TERMINALID+MERCHANTREF+PERMITTEDTERMINALS+DATETIME
+ACTION+SECRET
Below is an example HTML form to open card details registration page. <html> <body> <form action="https://testpayments.globalone.me/merchant/securecardpage" method="post"> <input type="hidden" name="ACTION" value="register" /> <input type="hidden" name="TERMINALID" value="6491002" /> <input type="hidden" name="MERCHANTREF" value="1234321" /> <input type="hidden" name="DATETIME" value="15-03-2006:10:43:01:673" /> <input type="hidden" name="HASH" value="d5d3441fb0e8318ce6d03976c2e93749" /> <input type="submit" value="Register" /> </form> </body> <html>
Page 66
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
To initiate card details updating, the value of the ACTION parameter should be
changed to “update”. A Secure Card of MERCHANTREF 1234321 must be already existing
under your account. Please note that the TERMINALID here is not valid and must be
changed.
Assuming valid details were sent, the Hosted Registration or Update page will be
displayed, clicking on “Register” or “Update” will save the card details, result GET
parameters will be forwarded to the Secure Card URL that is configured on the Terminal
Setup page.
Following parameters will be sent to the Secure Card Receipt URL:
Field Name Description RESPONSECODE Response Code “A” - Approval, check
the Response Codes table below for a full list of all supported codes.
RESPONSETEXT Response Text. MERCHANTREF Original Merchant Reference. CARDREFERENCE Generated Card Reference. MASKEDCARDNUMBER The card number (obfuscated) that
registered/updated. CARDTYPE See section 3.2 above. CARDEXPIRY Expiry date of the card. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+RESPONSECODE+RESPONSETEXT+MERCHANTREF+
CARDREFERENCE+DATETIME+SECRET
Response Codes:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E04 INVALID REFERENCE DETAILS E05 INVALID CARD TYPE E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E10 INVALID CARDNUMBER E11 INVALID CARDEXPIRY
Page 67
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
E12 INVALID CARDHOLDERNAME E13 INVALID HASH E14 CVV VALIDATION FAILED E23 INVALID PERMITTED TERMINALID
If invalid parameter values are sent, an Error Page will appear and the web
browser will not be redirected to the Secure Card Receipt Page. This should not happen
in a production environment after integration is completed.
6.3 Secure ACH Registration and Updating From the Hosted
Page
SecureACH details can be registered or updated using the GlobalOnePay hosted
page by the account holder, account details will be stored using GlobalOnePay
SecureACH Storage.
To initiate a SecureACH registration or update a POST must be made to the
following URL:
https://testpayments.globalone.me/merchant/securecardpage
The following table describes the form fields to be posted:
Field Name Required Description ACTION Y registerAch
updateAch MERCHANTREF Y Unique Reference assigned by the
merchants site/software to identify the stored account details. Length is limited to 48 chars.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS
TERMINALID Y A Terminal ID provided by GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
RECEIPTPAGEURL N Overrides “Secure Card URL” terminal setting if sent.
PERMITTEDTERMINALS
N Terminals which are permitted to process the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals
HASH Y An MD5 HASH. See Note 1 below.
Page 68
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+ACTION+RECEIPTPAGE
URL+SECRET
Below is an example HTML form to open account details registration page. <html> <body> <form action="https://testpayments.globalone.me/merchant/securecardpage" method="post"> <input type="hidden" name="ACTION" value="registerAch" /> <input type="hidden" name="TERMINALID" value="6491002" /> <input type="hidden" name="MERCHANTREF" value="1234321" /> <input type="hidden" name="DATETIME" value="15-03-2006:10:43:01:673" /> <input type="hidden" name="HASH" value="d5d3441fb0e8318ce6d03976c2e93749" /> <input type="submit" value="Register" /> </form> </body> <html>
To initiate account details updating, the value of the ACTION parameter should be
changed to “updateAch”. A SecureACH of MERCHANTREF 1234321 must be already
existing under your account. Please note that the TERMINALID here is not valid and must
be changed.
Assuming valid details were sent, the Hosted Registration or Update page will be
displayed, clicking on “Register” or “Update” will save the account details, result GET
parameters will be forwarded to the SecureACH URL that is configured on the Terminal
Setup page.
Following parameters will be sent to the SecureACH Receipt URL:
Field Name Description RESPONSECODE Response Code “A” - Approval, check the
Response Codes table below for a full list of all supported codes.
RESPONSETEXT Response Text. MERCHANTREF Original Merchant Reference. ACHREFERENCE Generated globally unique numeric account
reference. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below. MASKED_ACH_ACCOUNT Masked ACH account number, shows ~60% of
characters.
Page 69
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+RESPONSECODE+RESPONSETEXT+MERCHANTREF+
ACHREFERENCE+DATETIME+SECRET
6.4 XML Secure Card Integration
Secure Card Details Registration and Updating 6.4.1
The following is an example of a Secure Card Details Registration request for a
terminal: <?xml version="1.0" encoding="UTF-8"?> <SECURECARDREGISTRATION> <MERCHANTREF>77001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-12-2008:23:59:59:001</DATETIME> <CARDNUMBER>4444333322221111</CARDNUMBER> <CARDEXPIRY>1208</CARDEXPIRY> <CARDTYPE>VISA</CARDTYPE> <CARDHOLDERNAME>Joe Bloggs<CARDHOLDERNAME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> <PERMITTEDTERMINALS> <TERMINALID>77002</TERMINALID> <TERMINALID>77003</TERMINALID> </PERMITTEDTERMINALS> </SECURECARDREGISTRATION>
The following is an example of a Secure Card Details Updating request: <?xml version="1.0" encoding="UTF-8"?> <SECURECARDUPDATE> <MERCHANTREF>77001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-12-2008:23:59:59:001</DATETIME> <CARDEXPIRY>1208</CARDEXPIRY> <CARDTYPE>VISA</CARDTYPE> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> <PERMITTEDTERMINALS> <TERMINALID>77002</TERMINALID> <TERMINALID>77003</TERMINALID> </PERMITTEDTERMINALS> </SECURECARDUPDATE>
Page 70
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Field Name Required to Register
Required to Update
Description
MERCHANTREF Y Y Unique Merchant Reference. Length is limited to 48 chars.
TERMINALID Y Y A TerminalID provided by GlobalOnePay.
DATETIME Y Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
CARDNUMBER Y N The payment card number. CARDEXPIRY Y N 4 digit expiry field (MMYY). CARDTYPE Y Y Card type supported by terminal.
See section 3.2 Card Types. CARDHOLDERNAME Y N Cardholder name. HASH Y Y An MD5 HASH. See note 1 below. CVV N N The security code entered by the
card holder. If sent then GlobalOnePay will perform an authorization for 1 major unit of the terminal currency. If the bank responds with a CVV match response then GlobalOnePay will void the transaction so that it is not charged to the cardholder and add the SecureCard. If the CVV result is not a match then GlobalOnePay will return an error to the SecureCard registration request. Note that this does not require an approval, only the CVV result is checked in the response.
ISSUENO N N The issue no. of the card (Solo). PERMITTEDTERMINALS
N N Li List of permitted TERMINALID nodes. See example.
Page 71
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• If permitted terminals are not used, the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+DATETIME+CARDNUMBER+
CARDEXPIRY+CARDTYPE+CARDHOLDERNAME+SECRET
• If permitted terminals are used, The MD5 HASH of the request is
generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+CARDNUMBER+
CARDEXPIRY+CARDTYPE+CARDHOLDERNAME+
PERMITTEDTERMINALS+SECRET
• For updates where some of these fields are not sent they should just be
omitted from the hash calculation.
• The PERMITTEDTERMINALS string should be a comma separated list of the
permitted terminals in the same order as they are listed in the node list.
If the card was successfully registered, response for registration request would be: <SECURECARDREGISTRATIONRESPONSE> <MERCHANTREF>77001</MERCHANTREF> <CARDREFERENCE>2999990000000001</CARDREFERENCE> <DATETIME>31-12-2008:23:59:59:002</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURECARDREGISTRATIONRESPONSE>
Example of a successful card updating response: <SECURECARDUPDATERESPONSE> <MERCHANTREF>77001</MERCHANTREF> <CARDREFERENCE>2999990000000001</CARDREFERENCE> <DATETIME>31-12-2008:23:59:59:002</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURECARDUPDATERESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Refernce sent in
registration request. CARDREFERENCE System-Generated Card Reference (Secure
Card). DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Page 72
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+CARDREFERENCE+DATETIME+
SECRET
Error handling
If card was not registered or updated, error code and error message will be
returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
There is list of error codes and corresponding messages:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E04 INVALID REFERENCE DETAILS E05 INVALID CARD TYPE E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E10 INVALID CARDNUMBER E11 INVALID CARDEXPIRY E12 INVALID CARDHOLDERNAME E13 INVALID HASH E14 CVV VALIDATION FAILED E23 INVALID PERMITTED TERMINALID
Card Details Removal 6.4.2
Note that SecureCard MerchantRef's cannot be re-used after deletion. This is
because they are tied to existing transactions in our system and are retained internally
for data integrity and future refund functionality.
Card details removal request format: <?xml version="1.0" encoding="UTF-8"?> <SECURECARDREMOVAL> <MERCHANTREF>77001</MERCHANTREF> <CARDREFERENCE>2967534771694736</CARDREFERENCE> <TERMINALID>6491002</TERMINALID> <DATETIME>31-12-2008:23:59:59:001</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURECARDREMOVAL>
Page 73
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Field Name Required Description MERCHANTREF Y Unique Merchant Reference. Length is
limited to 48 chars. CARDREFERENCE
Y System-Generated Card Reference (Secure Card).
TERMINALID Y A TerminalID provided by GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+CARDREFERENCE+
SECRET
Card detail successful deletion response format: <SECURECARDREMOVALRESPONSE> <DATETIME>31-12-2008:23:59:59:002</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURECARDREMOVALRESPONSE>
The following fields will be returned in the response:
Field Name Description DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If request was not successful, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
There is list of error codes and corresponding messages:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E04 INVALID REFERENCE DETAILS E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E13 INVALID HASH
Page 74
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Card Details Search 6.4.3
Secure Card search by Merchant Reference can be performed as needed: <?xml version="1.0" encoding="UTF-8"?> <SECURECARDSEARCH> <MERCHANTREF>77001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-12-2008:23:59:59:001</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURECARDSEARCH>
Fields description:
Field Name Required Description MERCHANTREF Y Unique Merchant Reference. Length
is limited to 48 chars. TERMINALID Y A TerminalID provided by
GlobalOnePay. PERMITTEDTERMINALSREQUIRED N Should a list of permitted terminals
be included in the response? Y or N. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Secure Card detail successful deletion response format: <SECURECARDSEARCHRESPONSE> <MERCHANTREF>77001</MERCHANTREF> <CARDREFERENCE>2967532702149716</CARDREFERENCE> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>1208</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs<CARDHOLDERNAME> <DATETIME>31-12-2008:23:59:59:001</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURECARDSEARCHRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Unique Merchant Reference. CARDREFERENCE Card Reference. CARDTYPE Card type supported by terminal. See section
3.2 Card Types CARDEXPIRY 4 digit expiry field (MMYY). CARDHOLDERNAME Cardholder name. PERMITTEDTERMINALS List of permitted TERMINALID nodes.
Page 75
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. MASKEDCARDNUMBER If the “Show Masked Card Number in XML
Response” property defined for the used Terminal (TERMINALID) is enabled, this field is going to be send back in the response, like: 444433******1111 (Shows the first 6 numbers and the last 4).
HASH An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+CARDREFERENCE+CARDTYPE+
CARDEXPIRY+CARDHOLDERNAME+DATETIME+SECRET
Error handling
If request was not successful, error code and error message will be returned: <ERROR> <ERRORCODE>E04</ERRORCODE> <ERRORSTRING>INVALID REFERENCE DETAILS</ERRORSTRING> </ERROR>
There is list of error codes and corresponding messages:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E04 INVALID REFERENCE DETAILS E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E13 INVALID HASH
Page 76
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Card Details Advanced Search 6.4.4
Extension for the Secure Card Search functionality. With this feature, you are going
to be able to add criteria for a search, like: name, date, e-mail, phone and even custom
fields (up to 3), as needed: <?xml version="1.0" encoding="UTF-8"?> <SECURE_CARD_ADVANCED_SEARCH> <MERCHANTREF>77001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <NAME>John Smith</NAME> <EMAIL>[email protected]</EMAIL> <PHONE>11856452420</PHONE> <CREATIONDATE>31-12-2008</CREATIONDATE> <PERMITTEDTERMINALSREQUIRED>Y<PERMITTEDTERMINALSREQUIRED> <DATETIME>11-6-2017:11:23:55:134 </DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECURE_CARD_ADVANCED_SEARCH>
Fields description:
Field Name Required Description MERCHANTREF N Unique Merchant Reference. Length
is limited to 48 chars. TERMINALID Y A TerminalID provided by
GlobalOnePay. NAME N Card holder’s name of the Secure
Card EMAIL N Card holder’s email of the Secure
Card PHONE N Card holder’s phone of the Secure
Card CREATIONDATE N Creation date of the Secure Card.
Format: DD-MM-YYYY. PERMITTEDTERMINALSREQUIRED N Should a list of permitted terminals
be included in the response? Y or N. CUSTOMFIELD N Use the “NAME” xml attribute to
assign the name of the custom field. See section 3.4 for more info.
DATETIME Y Format: DD-MMYYYY: HH:MM:SS:SSS.
HASH Y An MD5 HASH. See note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+NAME+EMAIL+PHONE+
CREATIONDATE+DATETIME+SECRET
• No field accepts partial match
Page 77
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Secure Card detail successful response format: <?xml version="1.0" encoding="UTF-8"?> <SECURE_CARD_ADVANCED_SEARCH_RESPONSE> <SECURECARD> <MERCHANTREF>77001 </MERCHANTREF> <CARDREFERENCE>72357598079</CARDREFERENCE> <CARDTYPE>Discovery</CARDTYPE> <CARDEXPIRY>1019</CARDEXPIRY> <CARDHOLDERNAME>Joan Simons</CARDHOLDERNAME> <PERMITTEDTERMINALS> <TERMINALID>101102</TERMINALID> <TERMINALID>101103</TERMINALID> </PERMITTEDTERMINALS> </SECURECARD> <SECURECARD> <MERCHANTREF>77001 </MERCHANTREF> <CARDREFERENCE>12465693334</CARDREFERENCE> <CARDTYPE>Secure Card</CARDTYPE> <CARDEXPIRY>1217</CARDEXPIRY> <CARDHOLDERNAME>Phelippo Henry Sibouer</CARDHOLDERNAME> <PERMITTEDTERMINALS> <TERMINALID>101102</TERMINALID> <TERMINALID>101103</TERMINALID> </PERMITTEDTERMINALS> </SECURECARD> <!-- Until 10 Secure Card registries are returned → <DATETIME>29-06-2017:09:52:12:650</DATETIME> <HASH>a978a30afd8303cd24035d8bad6692d7]</HASH> </SECURE_CARD_ADVANCED_SEARCH_RESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Unique Merchant Reference. CARDREFERENCE Card Reference. CARDTYPE Card type supported by terminal. CARDEXPIRY 4 digit expiry field (MMYY). CARDHOLDERNAME Cardholder name. PERMITTEDTERMINALS List of permitted TERMINALID nodes. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. MASKEDCARDNUMBER If the “Show Masked Card Number in XML Re-
sponse” property defined for the used Termi-nal (TERMINALID) is enabled, this field is go-ing to be send back in the response, like: 444433******1111 (Shows the first 6 num-bers and the last 4).
HASH An MD5 HASH. See note 1 below.
Page 78
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+CARDREFERENCE+CARDHOLDERNAME
+DATETIME+SECRET
Errors handling
If request was not successful, error code and error message will be returned: <ERROR> <ERRORCODE>E04</ERRORCODE> <ERRORSTRING>INVALID REFERENCE DETAILS</ERRORSTRING> </ERROR>
There is list of error codes and corresponding messages:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E04 INVALID REFERENCE DETAILS E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E13 INVALID HASH
Page 79
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
6.5 XML Secure ACH Integration
Secure ACH Details Registration and Updating 6.5.1
The following is an example of a SecureACH Registration request for a terminal. <?xml version="1.0" encoding="UTF-8"?> <ACHSECUREREGISTRATION> <MERCHANTREF>CSV_73443623</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <DATETIME>22-02-2017:18:24:03:638</DATETIME> <ACCOUNT_TYPE>CHECKING</ACCOUNT_TYPE> <ACCOUNT_NUMBER>2387654376</ACCOUNT_NUMBER> <ROUTING_NUMBER>123103729</ROUTING_NUMBER> <ACCOUNT_NAME>Billy Joel</ACCOUNT_NAME> <ADDRESS1>7th Avenu, 77</ADDRESS1> <ADDRESS2>5th Avenu, 14</ADDRESS2> <CITY>New York</CITY> <REGION>A1</REGION> <POSTCODE>117898</POSTCODE> <COUNTRY>US</COUNTRY> <PHONE>9563343234</PHONE> <IPADDRESS>192.168.0.1</IPADDRESS> <EMAIL>[email protected]</EMAIL> <DL_STATE>NY</DL_STATE> <DL_NUMBER>4353446</DL_NUMBER> <PERMITTEDTERMINALS> <TERMINALID>2366002</TERMINALID> </PERMITTEDTERMINALS> <HASH>ebdc9615f1c3e7ca3a01e28ad6ce04f4</HASH> </ACHSECUREREGISTRATION>
The following is an example of a SecureACH update request: <?xml version="1.0" encoding="UTF-8"?> <ACHSECUREUPDATE> <MERCHANTREF>CSV_73254705</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <DATETIME>22-02-2017:18:50:51:008</DATETIME> <ACCOUNT_TYPE>SAVINGS</ACCOUNT_TYPE> <ACCOUNT_NUMBER>2387654376</ACCOUNT_NUMBER> <ROUTING_NUMBER>121122676</ROUTING_NUMBER> <ACCOUNT_NAME>Billy Joel</ACCOUNT_NAME> <ADDRESS1>7th Avenu, 77</ADDRESS1> <CITY>New York</CITY> <REGION>NY</REGION> <POSTCODE>-1</POSTCODE> <COUNTRY>US</COUNTRY> <PHONE>9563343234</PHONE> <IPADDRESS>192.168.0.2</IPADDRESS> <EMAIL>[email protected]</EMAIL> <DL_STATE>NY</DL_STATE> <DL_NUMBER>4353446</DL_NUMBER> <PERMITTEDTERMINALS> <TERMINALID>2366002</TERMINALID> </PERMITTEDTERMINALS> <HASH>982f6c2b467401fccc765ebf4d16bd66</HASH> </ACHSECUREUPDATE>
Page 80
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Note:
The PERMITTEDTERMINALS string should be a comma separated list of the
permitted terminals.
Fields description:
Field Name Required Description Register Update
TERMINALID Y Y A TerminalID provided by GlobalOnePay.
MERCHANTREF Y Y Unique Merchant Reference. Length is limited to 48 chars.
ACCOUNT_NAME Y Y The customers first and last names. ACCOUNT_TYPE Y Y CHECKING or SAVINGS. ACCOUNT_NUMBER Y Y Customers ACH account number. ROUTING_NUMBER Y Y Customers ACH routing number. DESCRIPTION N N Optional Description. ADDRESS1 N N First line of customers address. For
updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that field)
ADDRESS2 N N Second line of customers address. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that field)
CITY N N Customers home city. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that field)
REGION N N Customers home state. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that field)
POSTCODE N N Customers ZIP code. For updateAch actions only submit this parameter if you want to set a new value. ('-1' value clear that field)
PHONE N N Customers phone number. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that field)
COUNTRY N N Customers country. ('REMOVE'
Page 81
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
value clear that field) IPADDRESS N N Customer IP Address. ('REMOVE'
value clear that field) EMAIL N N Customers email address.
('REMOVE' value clear that field) DL_STATE N N Customers driving licence state. ('-
1' value clear that field) DL_NUMBER N N Customers driving licence number.
('REMOVE' value clear that field) DATETIME Y Y Format: DD-MM-
YYYY:HH:MM:SS:SSS. PERMITTED TERMINALS
N N Terminals which are permitted to process the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals
HASH Y Y An MD5 HASH. See note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+ACCOUNT_NUMBER+
ACCOUNT_NAME+ACCOUNT_TYPE+ROUTING_NUMBER+
PERMITTEDTERMINALS+SECRET
If the account details were successfully registered, response for registration
request would be: <ACHSECUREREGISTRATIONRESPONSE> <MERCHANTREF>CSV_73443623</MERCHANTREF> <ACHREFERENCE>2967530237009546</ACHREFERENCE> <DATETIME>22-02-2017:17:24:05:894</DATETIME> <HASH>eb3c878e6c304c086dd7ca186406584a</HASH> </ACHSECUREREGISTRATIONRESPONSE>
Example of a successful account details updating response: <MERCHANTREF>CSV_73254705</MERCHANTREF> <ACHREFERENCE>2967539138333186</ACHREFERENCE> <DATETIME>22-02-2017:17:50:51:176</DATETIME> <HASH>4b8f045a2a5682a9af34ba4532e78dea</HASH>
Page 82
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Refernce sent in registration
request. ACHREFERENCE Generated globally unique numeric account
reference. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+ACHREFERENCE+DATETIME
+SECRET
Error handling
If ACH Secure Account was not registered or updated, error code and error
message will be returned: <ERROR> <ERRORCODE>E21</ERRORCODE> <ERRORSTRING>Invalid First Name</ERRORSTRING> </ERROR>
Secure ACH Details Removal 6.5.2
Note that SecureACH MerchantRef's cannot be re-used after deletion. This is
because they are tied to existing transactions in our system and are retained internally
for data integrity and future refund functionality.
Card details removal request format: <?xml version="1.0" encoding="UTF-8"?> <ACHSECUREREMOVAL> <MERCHANTREF>CSV_73254705</MERCHANTREF> <ACHREFERENCE>2967539138333186</ACHREFERENCE> <TERMINALID>2366006</TERMINALID> <DATETIME>22-02-2017:19:10:31:114</DATETIME> <HASH>e632813057b4b7d80fa3556f78e16983</HASH> </ACHSECUREREMOVAL>
Page 83
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Field Name Required Description TERMINALID Y A TerminalID provided by
GlobalOnePay. MERCHANTREF Y Unique Merchant Reference. Length is
limited to 48 chars. ACHREFERENCE Y Generated globally unique numeric
account reference. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+ACHREFERENCE
+SECRET
Account detail successful deletion response format:
<SECUREACHDELETIONRESPONSE> <MERCHANTREF>werg456343wf34fe</MERCHANTREF> <DATETIME>31-12-2008:23:59:59:002</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </SECUREACHDELETIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Refernce sent in registration
request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If request was not successful, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Page 84
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Secure ACH Details Search 6.5.3
SecureACH search by Merchant Reference can be performed as needed: <?xml version="1.0" encoding="UTF-8"?> <ACHSECURESEARCH> <MERCHANTREF>CSV_73254705</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <PERMITTEDTERMINALSREQUIRED>Y</PERMITTEDTERMINALSREQUIRED> <DATETIME>22-02-2017:18:59:50:189</DATETIME> <HASH>efa7edfab30da38bdfbea8c67cb324cd</HASH> </ACHSECURESEARCH>
Fields description:
Field Name Required Description MERCHANTREF Y Unique Merchant Reference. Length is
limited to 48 chars. ACHREFERENCE Y Generated globally unique numeric
account reference. TERMINALID Y A TerminalID provided by
GlobalOnePay. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
SecureACH detail successful deletion response format: <?xml version="1.0" encoding="UTF-8"?> <ACHSECURESEARCHRESPONSE> <MERCHANTREF>CSV_73254705</MERCHANTREF> <ACHREFERENCE>2967539138333186</ACHREFERENCE> <ACCOUNT_NAME>Test Consumer</ACCOUNT_NAME> <PERMITTEDTERMINALS> <TERMINALID>2366002</TERMINALID> </PERMITTEDTERMINALS> <DATETIME>22-02-2017:17:59:50:319</DATETIME> <HASH>5ffb7b446ef9c9bcd94b1c3500157c82</HASH> </ACHSECURESEARCHRESPONSE>
Page 85
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields will be returned in the response:
Field Name Description MERCHANTREF The Merchant Reference from the request. ACHREFERENCE The SecureACH Reference from the request ACCOUNT_NAME Customers name PERMITTEDTERMINALS Terminals which are permitted to process
the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals
TERMINALID A TerminalID provided by GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+ACHREFERENCE+ACCOUNT_NAME+
DATETIME+SECRET
Error handling
If request was not successful, error code and error message will be returned: <ERROR> <ERRORCODE>E04</ERRORCODE> <ERRORSTRING>INVALID REFERENCE DETAILS</ERRORSTRING> </ERROR>
XML Payments Using Registered Card 6.5.4
To send a payment transaction using a registered card, a standard PAYMENT
request should be sent. The Card Type should be set to 'SECURECARD', the
CARDNUMBER should contain the Secure Card Reference, both CARDEXPIRY and
CARDHOLDERNAME tags should be omitted from the request.
XML Payments Using Secure ACH Details 6.5.5
To send a payment transaction using stored ACH details, a standard ACHSALE
request should be sent. The ACH_SECURE field should be set to 'Y' and the
ACH_ACCOUNT field should be populated with the ACHREFERENCE for the account.
These fields should then be omitted from the request:
• ACH_ACCOUNT_TYPE
• ACH_FIRST_NAME
Page 86
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• ACH_LAST_NAME
• ACH_ADDRESS1
• ACH_ADDRESS2
• ACH_CITY
• ACH_STATE
• ACH_ZIP
• ACH_PHONE_NUMBER
7. Subscriptions
GlobalOnePay Subscriptions is a versatile and complete recurring payments
solution. It can be used in two main ways:
1. Automatic payments - This is a fully automated solution that will manage
the lifetime of a recurring payment once it is registered and notify the
merchant of any issues that happen during it's lifetime.
2. Manual payments – With this solution, recurring payments are set up in
our system just as they are for automatic payments. The main difference is
that our system does not actually process payments automatically. Instead,
when a payment is pending, the merchant should initiate the payment, either
via and “XML Payment Request” for Credit transactions, “XML Subscription
ACH Payment” for ACH transactions or through the SelfCare System. Another
difference with this method is that you can modify the amount of the
payment.
Subscriptions can only be set up on card details already stored in our system using
the Secure Card feature above. Subscriptions are set up in two levels:
1. Stored Subscriptions – Stored subscriptions are not subscriptions in their
own right, but instead are templates for multiple subscriptions that are
registered under them. They define the period (weekly / monthly / quarterly
/ annually), the number of those periods (if it's a fixed number), setup price,
recurring price, etc. They are intended to represent a product, for example.
2. Subscriptions – Every subscription set up has to be under a Stored
Subscription. However some of the settings of the stored subscription can be
overruled by the Subscription itself, as you will see below. Subscriptions are
intended to represent a specific order of a product represented by the stored
Page 87
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
subscription that it's under.
7.1 Credit or ACH Subscription Registration From the Hosted
Page
New Subscription can be registered from the GlobalOnePay hosted page. When
new subscription is created it name, description, set-up price, recurring price, length,
period type and type are copied from the corresponding stored subscription.
To get Subscription Registration Page opened in a client browser a POST must be
made to the following URL:
https://testpayments.globalone.me/merchant/subscriptionpage/register
Subscription registration POST parameters description:
Field Name Required Description TERMINALID Y A TerminalID provided by GlobalOnePay.
NB – Please contact GlobalOnePay to be issued with a test terminal ID.
MERCHANTREF Y Unique Merchant Reference. Length is limited to 48 chars.
STOREDSUBSCRIPTIONREF
N This field is required if new Subscription being created should be based on already existing Stored Subscription.
SECURECARDMERCHANTREF
Y for Credit
Merchant Reference of a Secure Card which will be used to do set-up and recurring payments. (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
SECREACHA-COUNTMERCHANTREF
Y for ACH
Merchant Reference of a SecureACH record which will be used to do set-up and recurring payments. (Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be present)
CARDREFERENCE N for Credit
System-Generated Secure Card Reference (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
ACHREFERENCE N for ACH
ACH Account secure reference generated by GlobalOnePay and provided to merchant during creation Secure ACH Account. (Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be present)
SUBSCRIPTIONRECURRINGAMOUNT
N Cost of each payment. Should only be sent if Stored Subscription type is “Automatic (without amounts)” and new
Page 88
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description Stored Subscription is not being created.
SUBSCRIPTIONINITIALAMOUNT
N Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Should only be sent if Stored Subscription type is “Automatic (without amounts)” and new Stored Subscription is not being created.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. STARTDATE Y Subscription Start Date. ENDDATE N Subscription End Date, if it is not set
subscription will continue until manually canceled or lenght reached (if it is set).
HASH Y An MD5 HASH. See Note 1 below. Following parameters should be posted if new Stored Subscription should be created (STOREDSUBSCRIPTIONREF shouldn't be posted in such case). NEWSTOREDSUBSCRIPTIONREF
N Merchant Ref to be assigned for new Stored Subscription being created.
NAME Y Display name for subscription. DESCRIPTION Y Description explaining subscription. PERIODTYPE Y Integer code of Period Type, can be:
2 – WEEKLY 3 – FORTNIGHTLY 4 – MONTHLY 5 – QUARTERLY 6 - YEARLY
LENGTH Y 0 for non ending / multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date – Current Date).
RECURRINGAMOUNT Y Cost of each payment (will be ignored if manual).
INITIALAMOUNT Y Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Setup fails if setup payment declines.
TYPE Y Integer code of subscription type: 1 – AUTOMATIC 2 – MANUAL 3 – AUTOMATIC (WITHOUT AMOUNTS)
ONUPDATE Y Integer code of onupdate: 1 – CONTINUE 2 – UPDATE (Let all depending subscriptions finish their subscription prior to update / Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions)
ONDELETE Y Integer code of ondelete: 1 – CONTINUE
Page 89
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Field Name Required Description 2 - CANCEL (Continue subscriptions until cancelled manually or reach end date or length / Cancel all subscriptions)
AnyOtherCustomField N Any other fields sent in the request will be treated as a custom field (see section 3.4). Should start with “CF_” followed by the required name of the custom field. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.
Notes for Credit:
• If “SECURECARDMERCHANTREF” is used, the MD5 HASH is generated
using the following as an input string:
TERMINALID+MERCHANTREF+SECURECARDMERCHANTREF+
DATETIME+STARTDATE+SECRET
• If “CARDREFERENCE” is used, the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+CARDREFERENCE+DATETIME+
STARTDATE+SECRET
Notes for ACH:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+SECUREACHACCOUNTMERCHANTRE
F+DATETIME+STARTDATE+SECRET
• If “ACHREFERENCE ” is used, the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+ACHREFERENCE+DATETIME+
STARTDATE+SECRET
Page 90
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Below is an example HTML form to open subscription registration page using
“SECURECARDMERCHANTREF”. <html> <body> <form action=“https://testpayments.globalone.me/merchant/subscriptionpage/register” meth-od=“post”> <input type=“hidden” name=“TERMINALID” value=“6491002”> <input type=“hidden” name=“MERCHANTREF” value=“26352”> <input type="hidden" name="STOREDSUBSCRIPTIONREF" value="6523423"> <input type="hidden" name="SECURECARDMERCHANTREF" value="237498"> <input type="hidden" name="SECUREACHACCOUNTMERCHANTREF" value="237498"> <input type=“hidden” name=“DATETIME” value=“03-08-2009:17:32:18:329”> <input type="hidden" name="STARTDATE" value="04-08-2009"> <input type="hidden" name="ENDDATE" value="03-08-2010"> <input type=“hidden” name=“HASH” value=“b9a034421808a80dc8f1a5657da80f95”> <input type=“submit” value=“Register”> </form> </body> <html>
Assuming valid details were sent, the Subscription Registration Hosted page will be
displayed, clicking on “Accept & Subscribe” button will create the subscription only if the
setup amount authorises successfully, and the resulting GET parameters will be
forwarded to the Subscription Receipt URL that is configured on the Terminal Setup page.
If Subscription Secure Card currency is other than Stored Subscription currency then
eDCC Decision Page will be displayed, and the customer will have to decide if eDCC
should be used for the initial and all subsequent payments for the subscription.
Following parameters will be sent to the Subscription Receipt URL:
Field Name Description RESPONSECODE Response Code:
A - Approval C - Cancelled Check the <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Subscription creation and updating error codes table for a full list of supported codes.
RESPONSETEXT Response Text. MERCHANTREF Original Merchant Reference. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Page 91
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+RESPONSECODE+
RESPONSETEXT+SECRET
If invalid parameter values will be sent, an Error Page will appear and the web
browser will not be redirected to the Subscription Receipt Page. This should not happen
in a production environment after integration is completed.
Subscription creation error codes:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E13 INVALID HASH E20 INVALID LENGTH E21 INVALID PERIOD TYPE E22 INVALID NAME E23 INVALID DESCRIPTION E24 INVALID RECURRINGAMOUNT E25 INVALID INITIALAMOUNT E26 INVALID TYPE E27 INVALID ONUPDATE E28 INVALID ONDELETE E29 INVALID TERMINAL CURRENCY E30 INVALID STORED SUBSCRIPTION REF E31 INVALID STORED SUBSCRIPTION MERCHANT REF E32 INVALID SECURE CARD MERCHANT REF E33 INVALID STARTDATE E34 INVALID ENDDATE E35 INVALID EDCCDECISION E36 SETUP PAYMENT PROCESSING ERROR E37 INVALID SUBSCRIPTIONRECURRINGAMOUNT E38 INVALID SUBSCRIPTIONINITIALAMOUNT E39 SECURE CARD NOT VALIDATED E41 PASS ONLY ONE OF CARDREFERENCE OR
SECURECARDMERCHANTREF OR SECUREACHACCOUNTMERCHANTREF
E48 INVALID SECURE CARD REFERENCE
Page 92
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
7.2 XML Subscriptions Integration
Stored Subscription and Subscriptions can be managed through XML Gateway.
Stored Subscription Creation and Update Request 7.2.1
The following is an example of a Stored Subscription Registration request for a
terminal: <?xml version="1.0" encoding="UTF-8"?> <ADDSTOREDSUBSCRIPTION> <MERCHANTREF>MR001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>30-07-2009:15:26:38:027</DATETIME> <NAME>Animal Life</NAME> <DESCRIPTION>Magazine membership</DESCRIPTION> <PERIODTYPE>MONTHLY</PERIODTYPE> <LENGTH>12</LENGTH> <CURRENCY>EUR</CURRENCY> <RECURRINGAMOUNT>15.87</RECURRINGAMOUNT> <INITIALAMOUNT>10.99</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> <HASH>750f7c545a3d63ecaf3b48c149b95555</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”></CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID” /> </ADDSTOREDSUBSCRIPTION>
Example of a Stored Subscription Updating request: <?xml version="1.0" encoding="UTF-8"?> <UPDATESTOREDSUBSCRIPTION> <MERCHANTREF>13231</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:16:07:21:000</DATETIME> <NAME>Animal Life</NAME> <DESCRIPTION>Magazine membership</DESCRIPTION> <LENGTH>12</LENGTH> <CURRENCY>EUR</CURRENCY> <RECURRINGAMOUNT>15.99</RECURRINGAMOUNT> <INITIALAMOUNT>10.99</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> <HASH>5023bbb6726d1b5d2dcb7c77fb11b94f</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”></CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID” /> </UPDATESTOREDSUBSCRIPTION>
Page 93
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Field Name Required to Add
Required to Update
Description
MERCHANTREF Y Y Unique merchant identifier per terminal. Length is limited to 48 chars.
TERMINALID Y Y A TerminalID provided by GlobalOnePay. DATETIME Y Y Format: DD-MM-YYYY:HH:MM:SS:SSS. NAME Y Y Display name for subscription. DESCRIPTION Y Y Description explaining subscription. PERIODTYPE Y N Period Type, can be: WEEKLY,
FORTNIGHTLY, MONTHLY, QUARTERLY, YEARLY. Only allowed for ADDSTOREDSUBSCRIPTION request.
LENGTH Y Y 0 for non ending / multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date – Current Date).
CURRENCY Y Y Currency of subscription, this must either the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT
Y Y Cost of each payment (will be ignored if manual).
INITIALAMOUNT Y Y Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0.
TYPE Y Y MANUAL / AUTOMATIC / AUTOMATIC (WITHOUT AMOUNTS).
ONUPDATE Y Y UPDATE/CONTINUE (Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions/Let them finish their subscription prior to update).
ONDELETE Y Y CANCEL/CONTINUE (Cancel all subscriptions / Continue subscriptions until cancelled manually or reach end date or length).
HASH Y Y An MD5 HASH. See note below. CUSTOMFIELD N N Use the “NAME” xml attribute to assign
the name of the custom field. See section 3.4 for more info. No value is required and any value sent will be ignored.
Page 94
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+TYPE+NAME
+CURRENCY+RECURRINGAMOUNT+INITIALAMOUNT+LENGTH
+SECRET
If new stored subscription was successfully registered, response would be: <ADDSTOREDSUBSCRIPTIONRESPONSE> <MERCHANTREF>13231</MERCHANTREF> <DATETIME>30-07-2009:15:26:39:745</DATETIME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </ADDSTOREDSUBSCRIPTIONRESPONSE>
Example of a successful stored subscription updating response: <UPDATESTOREDSUBSCRIPTIONRESPONSE> <MERCHANTREF>13231</MERCHANTREF> <DATETIME>31-07-2009:16:07:21:329</DATETIME> <HASH>0af49616cad0fd1e19bc709de7d7c934</HASH> </UPDATESTOREDSUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in
registration request DATETIME Format: DD-MM-
YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If stored subscription was not registered or updated, error code and error message
will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Page 95
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Stored Subscription creation and updating error codes:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E13 INVALID HASH E20 INVALID LENGTH E21 INVALID PERIOD TYPE E22 INVALID NAME E23 INVALID DESCRIPTION E24 INVALID RECURRINGAMOUNT E25 INVALID INITIALAMOUNT E26 INVALID TYPE E27 INVALID ONUPDATE E28 INVALID ONDELETE E29 INVALID TERMINAL CURRENCY
Stored Subscription Deletion Request 7.2.2
Note that Stored Subscription MerchantRef's cannot be re-used after deletion. This
is because they are tied to existing transactions in our system and are retained internally
for data integrity and issue tracing. This method applies for Stored Card and Stored ACH
subscriptions.
To delete stored subscription following XML Gateway request should be send: <?xml version="1.0" encoding="UTF-8"?> <DELETESTOREDSUBSCRIPTION> <MERCHANTREF>13231</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:20:49:34:798</DATETIME> <HASH>efc5a04b5a98be9bd59ec5383abb9161</HASH> </DELETESTOREDSUBSCRIPTION>
Fields description:
Field Name Required Description MERCHANTREF Y Unique merchant identifier per terminal.
Length is limited to 48 chars. TERMINALID Y A TerminalID provided by GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Page 96
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Example of a successful stored subscription deletion response: <DELETESTOREDSUBSCRIPTIONRESPONSE> <MERCHANTREF>13231</MERCHANTREF> <DATETIME>31-07-2009:20:49:35:381</DATETIME> <HASH>8a8f462278c730e9de5561d8f186d7dc</HASH> </DELETESTOREDSUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Refernce sent in registration
request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If stored subscription was not registered or updated, error code and error message
will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
There is list of error codes and corresponding messages:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E13 INVALID HASH
Page 97
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Subscription Creation Request 7.2.3
Each subscription should be created based on some stored subscription. When new
subscription is created it name, description, set-up price, recurring price, length, period
type and type are copied from the corresponding stored subscription, most subscription
fields can be changed by Subscription Updating request.
To create new subscription based on an existing Stored Subscription following XML
Gateway request should be sent: <?xml version="1.0" encoding="UTF-8"?> <ADDSUBSCRIPTION> <MERCHANTREF>MR01-02</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <STOREDSUBSCRIPTIONREF>MR01</STOREDSUBSCRIPTIONREF> <SECURECARDMERCHANTREF>7126</SECURECARDMERCHANTREF> <DATETIME>30-07-2009:15:34:23:671</DATETIME> <STARTDATE>01-08-2009</STARTDATE> <ENDDATE>31-07-2010</ENDDATE> <EDCCDECISION>Y</EDCCDECISION> <CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD> </ADDSUBSCRIPTION>
If Stored Subscription doesn't yet exist it can be created putting all it details into
the nested NEWSTOREDSUBSCRIPTIONINFO tag, STOREDSUBSCRIPTIONREF in such
case should be omitted. There is example of such request: <?xml version="1.0" encoding="UTF-8"?> <ADDSUBSCRIPTION> <MERCHANTREF>MR02-02</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <SECURECARDMERCHANTREF>7126</SECURECARDMERCHANTREF> <DATETIME>30-07-2009:15:34:23:671</DATETIME> <STARTDATE>01-08-2009</STARTDATE> <ENDDATE>31-07-2010</ENDDATE> <EDCCDECISION>Y</EDCCDECISION> <NEWSTOREDSUBSCRIPTIONINFO> <MERCHANTREF>MR001</MERCHANTREF> <NAME>Animal Life</NAME> <DESCRIPTION>Magazine membership</DESCRIPTION> <PERIODTYPE>MONTHLY</PERIODTYPE> <LENGTH>12</LENGTH> <CURRENCY>EUR</CURRENCY> <RECURRINGAMOUNT>15.87</RECURRINGAMOUNT> <INITIALAMOUNT>10.99</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> </NEWSTOREDSUBSCRIPTIONINFO> <HASH>8515ccc5605651c12ab0645f79eb0271</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD> </ADDSUBSCRIPTION>
Page 98
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Field Name Required Description MERCHANTREF Y Unique merchant identifier per terminal.
Length is limited to 48 chars. TERMINALID Y A TerminalID provided by GlobalOnePay. STOREDSUBSCRIPTIONREF
N Stored Subscription Merchant Reference, it is allowed only if NEWSTOREDSUBSCRIPTIONINFO do not present.
SECURECARDMERCHANTREF
N Merchant Reference of a Secure Card which will be used to do set-up and recurring payments. (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
CARDREFERENCE N System-Generated Secure Card Reference (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. RECURRINGAMOUNT N Cost of each payment. Should only be sent if
Stored Subscription type is “Automatic (without amounts)” and new Stored Subscription is not being created.
INITIALAMOUNT N Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Should only be sent if Stored Subscription type is “Automatic (without amounts)” and new Stored Subscription is not being created.
STARTDATE Y Subscription Start Date. Format: DD-MM-YYYY. ENDDATE N Subscription End Date, if it is not set
subscription will continue until manually canceled or lenght reached (if it is set). Format: DD-MM-YYYY.
EDCCDECISION N This field is supported by a eDCC-enabled terminals only and will be ignored if terminal doesn't supports eDCC. Can be “Y” or “N”.
NEWSTOREDSUBSCRIPTIONINFO
N It is allowed only if STOREDSUBSCRIPTIONREF is not set. This tag and all it children should be set if Stored Subscription on which new Subscription being added should be based doesn't exists yet and should be created. Please check NEWSTOREDSUBSCRIPTIONINFO fields description table for details.
HASH Y An MD5 HASH. See note 1 below. CUSTOMFIELD N Should also use the “NAME” xml attribute to
assign the name of the custom field. See section 3.4 for more info.
Page 99
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• If "SECURECARDMERCHANTREF" is used, the MD5 HASH is generated
using the following as an input string:
TERMINALID+MERCHANTREF+STOREDSUBSCRIPTIONREF+
SECURECARDMERCHANTREF+DATETIME+STARTDATE+SECRET
• If "CARDREFERENCE" is used, the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+STOREDSUBSCRIPTIONREF+
CARDREFERENCE+DATETIME+STARTDATE+SECRET
• STOREDSUBSCRIPTIONREF should be omitted if it is not set.
NEWSTOREDSUBSCRIPTIONINFO fields description:
Field Name Required Description MERCHANTREF Y Unique merchant identifier per terminal.
Length is limited to 48 chars. NAME Y Display name for subscription. DESCRIPTION Y Description explaining subscription. PERIODTYPE Y Period Type, can be: WEEKLY,
FORTNIGHTLY, MONTHLY, QUARTERLY, YEARLY.
LENGTH Y 0 for non ending / multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date – Current Date).
CURRENCY Y Currency of subscription, this must either the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT N Cost of each payment (should not be sent if TYPE is “MANUAL”).
INITIALAMOUNT Y Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0.
TYPE Y MANUAL / AUTOMATIC. ONUPDATE Y UPDATE/CONTINUE (Update name,
description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions/Let them finish their subscription prior to update).
ONDELETE Y CANCEL/CONTINUE (Cancel all subscriptions / Continue subscriptions until cancelled manually or reach end date or length).
Page 100
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Example of a successful subscription creation response: <ADDSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR02-02</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </ADDSUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in
registration request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If new subscription was not registered, error code and error message will be
returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Subscription creation and updating error codes:
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E13 INVALID HASH E20 INVALID LENGTH E21 INVALID PERIOD TYPE E22 INVALID NAME E23 INVALID DESCRIPTION E24 INVALID RECURRINGAMOUNT E25 INVALID INITIALAMOUNT E26 INVALID TYPE
Page 101
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
E27 INVALID ONUPDATE E28 INVALID ONDELETE E29 INVALID TERMINAL CURRENCY E30 INVALID STORED SUBSCRIPTION REF E31 INVALID STORED SUBSCRIPTION MERCHANT REF E32 INVALID SECURE CARD MERCHANT REF E33 INVALID STARTDATE E34 INVALID ENDDATE E35 INVALID EDCCDECISION E36 SETUP PAYMENT PROCESSING ERROR E37 INVALID SUBSCRIPTIONRECURRINGAMOUNT E38 INVALID SUBSCRIPTIONINITIALAMOUNT E39 SECURE CARD NOT VALIDATED E41 PASS ONLY ONE OF CARDREFERENCE OR
SECURECARDMERCHANTREF OR SECUREACHACCOUNTMERCHANTREF
E48 INVALID SECURE CARD REFERENCE E49 SECURECARDMERCHANTREF AND
CARDREFERENCE ARE ABSENT (ONLY ONE OF THEM IS REQUIRED)
E50 SECURECARDMERCHANTREF AND CARDREFERENCE ARE BOTH PRESENT (ONLY ONE OF THEM IS REQUIRED)
Subscription Updating Request 7.2.4
The following is an example of a Subscription Updating request: <?xml version="1.0" encoding="UTF-8"?> <UPDATESUBSCRIPTION> <MERCHANTREF>MR001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <SECURECARDMERCHANTREF>8328</SECURECARDMERCHANTREF> <DATETIME>30-07-2009:09:59:38:921</DATETIME> <NAME>Animal Life</NAME> <DESCRIPTION>Magazine membership</DESCRIPTION> <LENGTH>12</LENGTH> <RECURRINGAMOUNT>15.87</RECURRINGAMOUNT> <STARTDATE>23-08-2009</STARTDATE> <ENDDATE>22-08-2010</ENDDATE> <EDCCDECISION>Y</EDCCDECISION> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”>132453462</CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID”>FG00001</CUSTOMFIELD> </UPDATESUBSCRIPTION>
Fields description:
Field Name Required Description MERCHANTREF Y Merchant Ref of subscription which
should be updated. TERMINALID Y A TerminalID provided by
Page 102
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
GlobalOnePay. SECURECARDMERCHANTREF
N Merchant Reference of a Secure Card which will be used to do set-up and recurring payments. (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
CARDREFERENCE N System-Generated Secure Card Reference (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
NAME N Subscription Name. DESCRIPTION N Subscription Description. LENGTH N Subscription Length. RECURRINGAMOUNT N New Recurring Amount. STARTDATE N Subscription Start Date. ENDDATE N Subscription End Date, if it is not set
subscription will continue until manually canceled or lenght reached (if it is set).
EDCCDECISION N This field is supported by a eDCC-enabled terminals only and will be ignored if terminal doesn't supports eDCC. Can be “Y” or “N”.
HASH Y An MD5 HASH. See note 1 below. CUSTOMFIELD N Should also use the “NAME” xml
attribute to assign the name of the custom field. See section 3.4 for more info.
Notes:
• If "SECURECARDMERCHANTREF" is used, the MD5 HASH is generated
using the following as an input string:
TERMINALID+MERCHANTREF+SECURECARDMERCHANTREF+
DATETIME+STARTDATE+SECRET
• If "CARDREFERENCE" is used, the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+CARDREFERENCE+DATETIME+
STARTDATE+SECRET
Page 103
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Example of a successful subscription updating response: <UPDATESUBSCRIPTIONRESPONSE> <MERCHANTREF>MR02-02</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </UPDATESUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in
registration request DATETIME Format: DD-MM-
YYYY:HH:MM:SS:SSS HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If subscription was not updated, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Possible error codes are covered in the Subscription creation and updating error
codes.
Subscription Deletion Request 7.2.5
Note that Subscription MerchantRef's cannot be re-used after deletion. This is
because they are tied to existing transactions in our system and are retained internally
for data integrity and issue tracing.
The following is an example of a Subscription Deletion request: <?xml version="1.0" encoding="UTF-8"?> <DELETESUBSCRIPTION> <MERCHANTREF>MR002</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:11:03:42:328</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> </DELETESUBSCRIPTION>
Page 104
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Example of a successful subscription deletion response: <DELETESUBSCRIPTIONRESPONSE> <MERCHANTREF>MR02-02</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </DELETESUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in
registration request. DATETIME Format: DD-MM-
YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If subscription was not deleted, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Possible error codes are covered in the Subscription creation and updating error
codes.
Field Name Required Description MERCHANTREF Y Merchant Ref of subscription
which should be deleted. TERMINALID Y A TerminalID provided by
GlobalOnePay. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Page 105
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Subscription Cancellation Request 7.2.6
Cancelling a subscription is exactly the same as deleting a subscription.
The following is an example of a Subscription Cancellation request: <?xml version="1.0" encoding="UTF8"?> <CANCELSUBSCRIPTION> <MERCHANTREF>MR002</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:11:03:42:328</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> </CANCELSUBSCRIPTIONACH>
Fields description:
Field Name Required Description MERCHANTREF Y Merchant Ref of subscription which
should be deleted. TERMINALID Y A TerminalID provided by
GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Example of a successful subscription cancellation response: <CANCELSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </CANCELSUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in registration request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Page 106
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Error handling
If subscription was not cancelled, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
ACH Subscription Creation Request 7.2.7
Each subscription should be created based on some stored subscription. When new
subscription is created it name, description, set-up price, recurring price, length, period
type and type are copied from the corresponding stored subscription, most subscription
fields can be changed by Subscription Updating request.
To create new subscription based on an existing Stored Subscription following XML
Gateway request should be sent: <?xml version="1.0" encoding="UTF-8"?> <ADD_ACH_SUBSCRIPTION> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <ACHREFERENCE>2967530284987420</ACHREFERENCE> <SEC_CODE>TEL</SEC_CODE> <DATETIME>06-03-2017:18:09:04:583</DATETIME> <RECURRINGAMOUNT>2.0</RECURRINGAMOUNT> <INITIALAMOUNT>13.0</INITIALAMOUNT> <STARTDATE>06-03-2017</STARTDATE> <ENDDATE>17-05-2020</ENDDATE> <HASH>05b0f69a72dd7b25883c7b8ed3918ae9</HASH> </ADD_ACH_SUBSCRIPTION>
If Stored Subscription doesn't yet exist it can be created putting all it details into
the nested NEWSTOREDSUBSCRIPTIONINFO tag, STOREDSUBSCRIPTIONREF in such
case should be omitted. There is example of such request: <?xml version="1.0" encoding="UTF-8"?> <ADD_ACH_SUBSCRIPTION> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <ACHREFERENCE>2967530284987420</ACHREFERENCE> <SEC_CODE>TEL</SEC_CODE> <DATETIME>06-03-2017:18:09:04:583</DATETIME> <RECURRINGAMOUNT>2.0</RECURRINGAMOUNT> <INITIALAMOUNT>13.0</INITIALAMOUNT> <STARTDATE>06-03-2017</STARTDATE> <ENDDATE>17-05-2020</ENDDATE> <NEWSTOREDSUBSCRIPTIONINFO> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <NAME>name</NAME> <DESCRIPTION>description test</DESCRIPTION> <PERIODTYPE>WEEKLY</PERIODTYPE> <LENGTH>12</LENGTH> <CURRENCY>USD</CURRENCY>
Page 107
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
<RECURRINGAMOUNT>3.0</RECURRINGAMOUNT> <INITIALAMOUNT>12.0</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> </NEWSTOREDSUBSCRIPTIONINFO> <HASH>05b0f69a72dd7b25883c7b8ed3918ae9</HASH> </ADD_ACH_SUBSCRIPTION>
Fields description:
Field Name Required Description MERCHANTREF Y Unique merchant identifier per terminal.
Length is limited to 48 chars. TERMINALID Y A TerminalID provided by GlobalOnePay. STOREDSUBSCRIPTIONREF N Stored Subscription Merchant Reference,
it is allowed only if NEWSTOREDSUBSCRIPTIONINFO do not present.
SECUREACHACCOUNTMERCHANTREF
N Merchant Reference of a Secure ACH Account which will be used to do set-up and recurring payments.(Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be present)
ACHREFERENCE N System-Generated ACH Reference (Secure ACH).(Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be present)
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. STARTDATE Y Subscription Start Date. Format: DD-MM-
YYYY. ENDDATE N Subscription End Date, if it is not set
subscription will continue until manually canceled or lenght reached (if it is set). Format: DD-MM-YYYY.
NEWSTOREDSUBSCRIPTIONINFO
N It is allowed only if STOREDSUBSCRIPTIONREF is not set. This tag and all it children should be set if Stored Subscription on which new Subscription being added should be based doesn't exists yet and should be created. Please check NEWSTOREDSUBSCRIPTIONINFO fields description table for details.
HASH Y An MD5 HASH. See note 1 below.
Page 108
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+ACHREFERENCE+DATETIME+START
DATE+SECRET
• If using a secure ach account the MD5 HASH is generated using the
following as an input string:
TERMINALID+MERCHANTREF+
SECUREACHACCOUNTMERCHANTREF+DATETIME+STARTDATE+
SECRET
• STOREDSUBSCRIPTIONREF should be omitted if it is not set.
NEWSTOREDSUBSCRIPTIONINFO fields description:
Field Name Required Description MERCHANTREF Y Unique merchant identifier per
terminal. Length is limited to 48 chars.
NAME Y Display name for subscription. DESCRIPTION Y Description explaining
subscription. PERIODTYPE Y Period Type, can be: WEEKLY,
FORTNIGHTLY, MONTHLY, QUARTERLY or YEARLY.
LENGTH Y 0 for non ending / multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date – Current Date).
CURRENCY Y Currency of subscription, this must either the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT N Cost of each payment (should not be sent if TYPE is “MANUAL”).
INITIALAMOUNT Y Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0.
TYPE Y MANUAL or AUTOMATIC. ONUPDATE Y UPDATE or CONTINUE (Update
name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all
Page 109
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
subscriptions/Let them finish their subscription prior to update).
ONDELETE Y CANCEL/CONTINUE (Cancel all subscriptions / Continue subscriptions until cancelled manually or reach end date or length).
Example of a successful subscription creation response:
<ADDSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR02-02</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </ADDSUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in registration request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If new subscription was not registered, error code and error message will be
returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
A listing of potential error results is listed in Appendix H XML Gateway Subscription
Error Codes.
Page 110
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
ACH Subscription Updating Request 7.2.8
The following is an example of a Subscription Updating request: <?xml version="1.0" encoding="UTF-8"?> <UPDATE_ACH_SUBSCRIPTION> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <ACHREFERENCE>2967530284987420</ACHREFERENCE> <SEC_CODE>CCD</SEC_CODE> <DATETIME>06-03-2017:18:38:02:154</DATETIME> <NAME>NameUpdated_CSV_11082143</NAME> <LENGTH>10</LENGTH> <SKIPPERIODCOUNT>1</SKIPPERIODCOUNT> <RECURRINGAMOUNT>5.0</RECURRINGAMOUNT> <STARTDATE>06-03-2017</STARTDATE> <ENDDATE>06-11-2017</ENDDATE> <HASH>3cfc892047e5a1154e0f4c2e7cb29980</HASH> </UPDATE_ACH_SUBSCRIPTION>
Fields description:
Field Name Required Description MERCHANTREF Y Merchant Ref of subscription which
should be updated. TERMINALID Y A TerminalID provided by
GlobalOnePay. ACHREFERENCE N System-Generated ACH Reference
(Secure ACH).(Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be present)
SECUREACHACCOUNTMERCHANTREF N Merchant Reference of a Secure ACH which will be used to do recurring payments.(Only one of SECURECARDMERCHANTREF or ACHREFERENCE must be present)
SEC_CODE Y See section 3.3 above. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS. NAME N Subscription Name. DESCRIPTION N Subscription Description. LENGTH N Subscription Length. RECURRINGAMOUNT N New Recurring Amount. STARTDATE N Subscription Start Date. ENDDATE N Subscription End Date, if it is not set
subscription will continue until manually canceled or lenght reached (if it is set).
HASH Y An MD5 HASH. See notebelow.
Page 111
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+ACHREFERENCE+DATETIME+
STARTDATE+SECRET
Example of a successful subscription updating response: <UPDATE_ACH_SUBSCRIPTION_RESPONSE> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <DATETIME>06-03-2017:17:38:02:399</DATETIME> <HASH>e0f3de3996b57b1ac57b6cf92b5de046</HASH> </UPDATE_ACH_SUBSCRIPTION_RESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in registration request DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If subscription was not updated, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
A listing of potential error results is listed in Appendix H XML Gateway Subscription
Error Codes.
ACH Subscription Deletion Request 7.2.9
Note that Subscription MerchantRef's cannot be re-used after deletion. This is
because they are tied to existing transactions in our system and are retained internally
for data integrity and issue tracing. Deleted Subscriptions can still be viewed in the
SelfCare System by using the Advanced Filter.
Page 112
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following is an example of a Subscription Deletion request: <?xml version="1.0" encoding="UTF8"?> <DELETESUBSCRIPTIONACH> <MERCHANTREF>MR002</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:11:03:42:328</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> </DELETESUBSCRIPTIONACH>
Fields description:
Field Name Required Description MERCHANTREF Y Merchant Ref of subscription which
should be deleted. TERMINALID Y A TerminalID provided by
GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Example of a successful subscription deletion response: <DELETESUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </DELETESUBSCRIPTIONRESPONSE>
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in registration request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Page 113
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Error handling
If subscription was not deleted, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
A listing of potential error results is listed in Appendix H XML Gateway Subscription
Error Codes.
ACH Subscription Cancellation Request 7.2.10
Cancelling a subscription is exactly the same as deleting a subscription.
The following is an example of a Subscription Cancellation request: <?xml version="1.0" encoding="UTF8"?> <CANCELSUBSCRIPTIONACH> <MERCHANTREF>MR002</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:11:03:42:328</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> </CANCELSUBSCRIPTIONACH>
Fields description:
Field Name Required Description MERCHANTREF Y Merchant Ref of subscription which
should be deleted. TERMINALID Y A TerminalID provided by
GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Example of a successful subscription cancellation response: <CANCELSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </CANCELSUBSCRIPTIONRESPONSE>
Page 114
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields will be returned in the response:
Field Name Description MERCHANTREF Original Merchant Reference sent in registration request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+MERCHANTREF+DATETIME+SECRET
Error handling
If subscription was not cancelled, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>
Subscription Card Payment Request 7.2.11
Manual subscription recurring payment can be done from the XML Gateway. If
automatic subscription was not paid automatically because of card details expiration or
other issue it also can be paid in the same way as manual after Secure Card issue was
solved. The following is an example of a Subscription Payment request: <?xml version="1.0" encoding="UTF-8"?> <SUBSCRIPTIONPAYMENT> <ORDERID>8362</ORDERID> <TERMINALID>6491002</TERMINALID> <AMOUNT>87.78</AMOUNT> <SUBSCRIPTIONREF>311</SUBSCRIPTIONREF> <FOREIGNCURRENCYINFORMATION> <CARDCURRENCY>JPY</CARDCURRENCY> <CARDAMOUNT>10638</CARDAMOUNT> <CONVERSIONRATE>121.186190</CONVERSIONRATE> </FOREIGNCURRENCYINFORMATION> <EMAIL>[email protected]</EMAIL> <DATETIME>31-07-2009:14:09:59:121</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”>132453462</CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID”>FG00001</CUSTOMFIELD> </SUBSCRIPTIONPAYMENT>
Page 115
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Fields description:
Field Name Required Description ORDERID Y A unique identifier for the order
created by the merchant. (Max 12 Characters).
TERMINALID Y A TerminalID provided by GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.
SUBSCRIPTIONREF Y Merchant reference of a subscription being paid.
DESCRIPTION N Transaction Description. FOREIGNCURRENCYINFORMATION
N It is accepted for eDCC enabled subscriptions only. See section 5.1.6.2.
EMAIL N Cardholder e-mail address. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS HASH Y An MD5 HASH. See note below. CUSTOMFIELD N Should also use the “NAME” xml
attribute to assign the name of the custom field. See section 3.4 for more info.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+SUBSCRIPTIONREF+AMOUNT+
DATETIME+SECRET
Example of a successful subscription payment response: <SUBSCRIPTIONPAYMENTRESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>406243</APPROVALCODE> <DATETIME>31-07-2009:14:10:03:834</DATETIME> <HASH>6dd32c4b61f180dd791310f9c07d76a1</HASH> </SUBSCRIPTIONPAYMENTRESPONSE>
The following fields are returned in the response:
Field Name Description RESPONSECODE A or D or R(Approved or Declined or Referral). RESPONSETEXT The text of the authorization.
Page 116
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
APPROVALCODE Six digit AuthCode. DATETIME The time of the transaction created by the
bank. Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE
+RESPONSETEXT+SECRET
Error handling
If subscription payment was not accepted, error message will be returned: <ERROR> <ERRORSTRING>Invalid HASH field</ERRORSTRING> </ERROR>
A listing of potential error results is listed in Appendix H XML Gateway Subscription
Error Codes.
Subscription ACH Payment Request 7.2.12
Manual subscription recurring payment can be done from the XML Gateway. If
automatic subscription was not paid automatically because of ACH Account details
expiration or other issue it also can be paid in the same way as manual after SecureACH
issue was solved.
The following is an example of a Subscription Payment request: <?xml version="1.0" encoding="UTF-8"?> <ACH_SUBSCRIPTION_PAYMENT> <ORDERID>CSV_95790073</ORDERID> <TERMINALID>2366006</TERMINALID> <AMOUNT>3.94</AMOUNT> <SUBSCRIPTIONREF>mRef102</SUBSCRIPTIONREF> <SEC_CODE>WEB</SEC_CODE> <DATETIME>07-03-2017:18:09:50:137</DATETIME> <HASH>e088efde331594ec2d881479735368c5</HASH> </ACH_SUBSCRIPTION_PAYMENT>
Fields description:
Field Name Required Description SUBSCRIPTIONREF Y Merchant reference of a
subscription being paid. ORDERID Y A unique identifier for the order
created by the merchant. (Max 12 Characters).
Page 117
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
TERMINALID Y A TerminalID provided by GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.
SEC_CODE Y See section 3.3 above. DATETIME Y Format: DD-MM-
YYYY:HH:MM:SS:SSS HASH Y An MD5 HASH. See note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+SUBSCRIPTIONREF+AMOUNT+
DATETIME+SECRET
Example of a successful subscription payment response: <ACH_SUBSCRIPTION_PAYMENT_RESPONSE> <UNIQUEREF>JIZDZ59H1D</UNIQUEREF> <RESPONSECODE>E</RESPONSECODE> <RESPONSETEXT>ACCEPTED</RESPONSETEXT> <APPROVALCODE>Success</APPROVALCODE> <DATETIME>2017-03-07T17:09:54</DATETIME> <HASH>50909e43de3161f884db589c66deaee3</HASH> </ACH_SUBSCRIPTION_PAYMENT_RESPONSE>
The following fields are returned in the response:
Field Name Description APPROVALCODE Six digit AuthCode. UNIQUEREF Generated reference that should be stored for tracking
and remote XML refunding. RESPONSECODE A or D or R(Approved or Declined or Referral). RESPONSETEXT The text of the authorization. DATETIME The time of the transaction created by the bank.
Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+UNIQUEREF+AMOUNT+DATETIME+
RESPONSECODE+RESPONSETEXT+SECRET
Page 118
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• For multi-currency Terminal IDs (see section 3.2 above) this should be:
TERMINALID+ORDERID+UNIQUEREF+CURRENCY+AMOUNT+
DATETIME+RESPONSECODE+RESPONSETEXT+SECRET
• UNIQUEREF is to be used here
Error handling
If subscription payment was not accepted, error message will be returned: <ERROR> <ERRORCODE>E41</ERRORCODE> <ERRORSTRING>Invalid HASH field</ERRORSTRING> </ERROR>
A listing of potential error results is listed in Appendix H XML Gateway Subscription
Error Codes.
Page 119
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
7.3 Subscription Notifications
The Subscription Notification URL can be set in the Terminal Setup page of the
SelfCare System. If this is set a POST notification will be sent to this URL each time
automated activity happens on any active subscriptions. Note that manual changes
applied to subscriptions via the SelfCare System will not generate these notifications.
The data sent to the Subscription Notification URL contains the normal subscription
response fields as well as these extra fields:
The following fields are sent in the notification:
Field Name Description NOTIFICATIONTYPE Possible values for subscriptions are:
• SUBSCRIPTIONCREATION • SUBSCRIPTIONUPDATING • SUBSCRIPTIONDELETION • SUBSCRIPTIONSETUPPAYMENT • SUBSCRIPTIONRECURRINGPAYMENT
Possible values for stored subscriptions are:
• STOREDSUBSCRIPTIONCREATION • STOREDSUBSCRIPTIONUPDATING • STOREDSUBSCRIPTIONDELETION
TERMINALID The Terminal ID that the subscription is set up on.
ORDERID The Order ID that the system assigned to the Subscription payment. Only sent for SUBSCRIPTIONSETUPPAYMENT and SUBSCRIPTIONRECURRINGPAYMENT
AMOUNT The amount of the subscription payment as a 2 digit decimal or an Integer value for JPY amounts. Only sent for SUBSCRIPTIONSETUPPAYMENT and SUBSCRIPTIONRECURRINGPAYMENT
Notes:
• Subscription payments (SUBSCRIPTIONSETUPPAYMENT and
SUBSCRIPTIONRECURRINGPAYMENT) MD5 hash is calculated using the
following as an input string:
TERMINALID+MERCHANTREF+NOTIFICATIONTYPE+DATETIME+
ORDERID+AMOUNT+RESPONSECODE+RESPONSETEXT+SECRET
Page 120
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
8. ACH Re-Initiation
Re-Initiation process involves re-processing of initially approved transactions that
have been identified as NSF.
There are 2 ways to process such transactions:
• Automatic – A job is run at a set time which will process Re-Initiations
automatically.
• Manual – Re-Initiation can be processed manually via Selfcare.
Example of a Re-Initiation request: <?xml version="1.0" encoding="UTF-8"?> <ACHJHREINITIATION> <UNIQUEREF>LS2O5CO1XB</UNIQUEREF> <TERMINALID>2366006</TERMINALID> <DATETIME>24-01-2017:15:43:04:334</DATETIME> <HASH>1ecafefa8fead5c9db18daf8f6e75ba8</HASH> </ACHJHREINITIATION>
Fields description:
Field Name Required Description
UNIQUEREF Y Generated reference that should be stored for tracking and remote XML refunding.
TERMINALID Y A TerminalID provided by GlobalOnePay. NB – Please contact GlobalOnePay to be issued with a test terminal ID.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS HASH Y An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+UNIQUEREF+DATETIME+SECRET
Example of a successful Re-Initiation response: <ACHREINITIATIONRESPONSE> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>SUCCESS</RESPONSETEXT> <UNIQUEREF>LS2O5CO1XB</UNIQUEREF> <DATETIME>24-01-2017:14:43:05:940</DATETIME> <HASH>...</HASH> </ACHREINITIATIONRESPONSE>
Page 121
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
The following fields are returned in the response:
Field Name Description UNIQUEREF Generated reference that should be stored for tracking
and remote XML refunding. RESPONSECODE A or D or R(Approved or Declined or Referral). RESPONSETEXT The text of the authorization. DATETIME The time of the transaction created by the bank.
Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+RESPONSECODE+RESPONSETEXT+UNIQUEREF+
DATETIME+SECRET
Page 122
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
9. Bulk Payments
Bulk payments are useful for merchants that need to process a large amount of
transaction periodically for the customers.
We allow submission of these transactions in a csv file. We will immediately return
a response based on file format and field validation.
An e-mail notification will be sent when the bulk file has been processed. This will
only be sent if the notification email is configured. Please see the SelfCare User Guide for
details.
If the customer does not wish to automate their bulk payments, all of these
features are available inside our SelfCare System. Please see the SelfCare User Guide for
details.
9.1 Request File Submission
A HTTP POST will be sent to the URL below during testing:
https://testpayments.globalone.me/merchant/bulkpayments/submit
The live URL will be supplied when the merchant is ready to go live.
The parameters for the HTTP POST are:
Field Name Required Description terminalid Y Terminal ID Provided by GlobalOnePay
support. transactioncount Y The count of transactions in the bulk
payment file. batchtotal Y The net total of all amount fields in the
bulk payment file. datetime Y The date time of submission. Format: DD-
MM-YYYY:HH:MM:SS:SSS. hash Y MD5(terminalid +
transactioncount+batchtotal+datetime+secret) This is an MD5 HASH of the above described string without +’s. The secret should be set by merchant in the selfcare section.
Page 123
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
9.2 Request CSV File Format
Field Name Required Description Order ID Y A unique reference generated by
Merchant system to identify the transaction. (Max 12 Characters).
Currency Y ISO 4217 Currency Code. Amount Y Amount formatted to two decimal
places. E.g. 1653.00. Card Number Y Card PAN. Can be SecureCard Card
Reference Card Type N See section 3.2 Card Types above.
Leave blank if using SecureCard. Card Expiry N MMYY. Leave blank if using
SecureCard. Cardholder Name N The cardholders name. Leave blank if
using SecureCard. Address 1 N AVS Address Line 1. Address 2 N AVS Address Line 2. Post Code N AVS Post Code. Date Time Y Format: DD-MM-YYYY:HH:MM:SS:SSS. Hash Y An MD5 HASH of TerminalID + OrderID
+ Amount + DateTime + secret Amount should be formatted to 2 decimal places.
Auto Ready N Set to Y for setting auto ready or N to mark as pending.
Description N Optional transaction description. Email N Card holder email for notification.
Page 124
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
9.3 Request File Submission Response
The response is returned in csv format as a string, e.g. “200”,”76528”
The response contains the following fields :
Field Name Description Response Code Code defining the result of the bulk payment
submission. Code is a 3 digit numeric code. Possible responses codes : 200 VALIDATION OK 001 INVALID FILE ITEM COUNT 002 INVALID FILE FORMAT 003 FILE UPLOAD ERROR 004 INVALID TRANSACTION COUNT 005 INVALID BATCH TOTAL 006 INVALID TERMINAL ID 007 INVALID DATETIME 008 INVALID HASH 009 NOTHING TO SETTLE 010 INVALID NUMBER OF BATCH FILES 011 METHOD NOT SUPPORTED 012 UNKNOWN ERROR 013 INVALID BULK ID 014 INVALID BULK ID TERMINAL ID COMBINATION 015 BULK PAYMENTS ARE NOT ALLOWED 016 BULK PROCESSING IN PROGRESS
Page 125
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
9.4 Response File Request
The Response file is a csv file containing the results of all of the transactions
submitted in a bulk payment. This file is available for download in the the merchant
SelfCare System. Please see SelfCare User Guide for details.
The response file request is a HTTP GET request. The test URL to submit to is:
https://testpayments.globalone.me/merchant/bulkpayments/result
The required parameters are :
Field Name Required Description bulkid Y The bulk id supplied to merchant after
submitting bulk payments file. terminalid Y Terminal ID Provided by GlobalOnePay. hash Y An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
terminalid+bulkid+SECRET
• If the file is still being progressed the response to this request will be
error code 016 Which signifies BULK PROCESSING IN PROGRESS
Page 126
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
9.5 Response File Format
The response data is returned in a csv file. It will contain the results of the
transactions in a specified bulkid.
Field Name Required Description Order ID Y Order ID supplied by merchant in request.
(Max 12 Characters). Approval Code N Will be present for a successful
authorisation. Response Code N A, D or R (Approved,Declined or Referral)
In the case of an error there is an 3 digit numeric error code contained in this column. Order Already Processed System Error
Response Text Y Text describing state of transaction. Error message will be displayed here if an issue was encountered while processing transactions.
Date time N Only sent in the case of no error, same format as in request. YYYY-MM-DD:HH:MM:SS.
Hash Y An MD5 HASH. See Note below.
Notes:
• The MD5 HASH is generated using the following as an input string:
TERMINALID+ORDERID+AMOUNT+DATETIME+RESPONSECODE+
RESPONSETEXT+SECRET
Page 127
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix A : CVV & AVS Responses Note that transactions can still be authorised even if the CVV and AVS responses
are No match or failure responses. CVV and AVS responses are for indication to the
merchant only and usually do not influence the overall Authorization result. This can vary
per cardholders bank though (issuing bank).
CVV Results:
• M - CVV Match
• N - CVV No Match
• P - Not Processed
• S - CVV should be on the card but the merchant indicates it is not.
• U - User is unregistered
AVS Results:
• A - Address matches, ZIP does not. The first five numerical characters
contained in the address match with those stored at the VIC or issuer’s
center. However, the zip code does not match.
• E - Ineligible transaction.
• N - Neither address nor ZIP matches. Neither the first five numerical
characters contained in the address match with those stored at the VIC
nor issuer’s center nor the zip code match.
• R - Retry (system unavailable or timed out).
• S - Card type not supported. The card type for this transaction is not
supported by AVS. AVS can verify addresses for Visa cards, MasterCard,
proprietary cards, and private label transactions.
• U - Address information unavailable.
• G - Address information unavailable, International - Visa Only The address
information was not available at the VIC or issuer’s center.
• W - Nine-digit zip match, address does not. The nine-digit Postal zip code
matches that stored at the VIC or card issuer's center. However, the first
five numerical characters contained in the address do not match.
• X - Exact match (nine-digit zip and address). Both the nine-digit Postal zip
code as well as the first five numerical characters contained in the address
Page 128
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
match.
• Y - Address and five-digit zip match. Both the five-digit Postal zip code as
well as the first five numerical characters contained in the address match.
• Z - Five-digit zip matches, address does not. The five-digit Postal zip code
matches that stored at the VIC or card issuer’s centre.
• Contact GlobalOne support for configuration options related to AVS
responses and how the auto decline AVS feature will approve.
Page 129
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix B : Signature Field Format The SIGNATURE field is a string of characters. Each set of 4 characters represents
a point on a 300 pixel wide x 100 pixel tall canvas.
Each set of 4 characters is comprised of 2 chars to represent the X value (pixel
distance right from left side) and 2 chars to represent the Y value (pixel distance from
down from top).
Each 2 char value is a base 28 encoded decimal number (similar to hex which is
base 16). Possible values for each character are any numerical digit and the letters from
“a” to “r” inclusive (“a” = 10, “b” = 11, etc. just like in hex, but up to “r” = 28). For
example “3bac” can be calculated as:
(3 x 281) + (11 x 280) = 84 + 11 = 95 from the left and
(10 x 281) + (12 x 280) = 280 + 12 = 292 from the top,
hence 3bac is a point at 95x292 pixels from the top left.
To include a space between 2 points (no line drawn on signature canvas) include a
0x0 point (encoded as “0000”) in the string.
Points outside the bounds of the 300x100 pixel canvas will not be rendered, and
should not be included.
The SIGNATURE string can be a minimum length of 4 characters (1 point) and a
maximum of 1600 characters (400 points).
The recording canvas should always have a 3:1 width to height ratio.
If the canvas that the signature is recorded on is of a larger size, the magnitude of
the X and Y values should be scaled down proportionately to a 300x100 boundaries
respectively.
Example SIGNATURE string: “4i1m621m00005a125a2e” will draw a 40x40 pixel
“plus” symbol in the middle of the canvas.
Page 130
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix C : Supported Currencies The following is a list of currency types supported by GlobalOnePay. Other may be
added upon request.
Code Currency USA Canada AUD AUSTRALIAN DOLLAR X X CAD CANADIAN DOLLAR X X EUR EURO X X GBP POUND STERLING X X MXN MEXICAN NUEVO PESO X X USD US DOLLAR X X AED ARAB EMIRATES DIRHAM X
AFN AFGHANISTAN AFGHANI X ALL ALBANIAN LEK X AMD ARMENIAN DRAM X
ANG NETHERLANDS ANTILLEAN GUILDER X
AOA ANGOLAN KWANZA X ARS ARGENTINE PESO X AWG ARUBAN GUILDER X BAM MARKA X BBD BARBADOS DOLLAR X BDT BANGLADESHI TAKA X BGN BULGARIAN LEV X BHD BAHRAINI DINAR X BIF BURUNDI FRANC X BMD BERMUDIAN DOLLAR X BND BRUNEI DOLLAR X BOB BOLIVIANO X BSD BAHAMIAN DOLLAR X BTN BHUTAN NGULTRUM X BWP BOTSWANA PULA X BZD BELIZE DOLLAR X CDF FRANCS X CHF SWISS FRANC X CLP CHILEAN PESO X CNY YUAN RENMINBI X COP COLOMBIAN PESO X CRC COSTA RICAN COLON X CUP CUBAN PESO X CVE CAPE VERDE ESCUDO X CZK CZECH KORUNA X DJF DJIBOUTI FRANC X
Page 131
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
DKK DANISH KRONE X DOP DOMINICAN PESO X DZD ALGERIAN DINAR X EGP EGYPTIAN POUND X ERN ERITREAN NAKFA X ETB ETHIOPIAN BIRR X FJD FIJI DOLLAR X FKP FALKLAND ISLANDS POUND X GEL GEORGIAN LARI X GGP POUND STERLING X GHS GHANAIAN CEDI X GIP GIBRALTAR POUND X GMD GAMBIAN DALASI X GNF GUINEA FRANC X GYD GUYANA DOLLAR X HKD HONG KONG DOLLAR X HNL HONDURAN LEMPIRA X HRK CROATIAN KUNA X HTG HAITIAN GOURDE X HUF HUNGARIAN FORINT X IDR INDONESIAN RUPIAH X ILS ISRAELI NEW SHEKEL X INR INDIAN RUPEE X IQD IRAQI DINAR X IRR IRANIAN RIAL X ISK ICELAND KRONA X JMD JAMAICAN DOLLAR X JOD JORDANIAN DINAR X JPY JAPANESE YEN X KES KENYAN SHILLING X KGS SOM X KHR KAMPUCHEAN RIEL X KMF COMOROS FRANC X KPW NORTH KOREAN WON X KRW KOREAN WON X KWD KUWAITI DINAR X KYD CAYMAN ISLANDS DOLLAR X KZT KAZAKHSTAN TENGE X LAK LAO KIP X LBP LEBANESE POUND X LKR SRI LANKA RUPEE X LRD LIBERIAN DOLLAR X LSL LESOTHO LOTI X LTL LITHUANIAN LITAS X
Page 132
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
LVL LATVIAN LATS X LYD LIBYAN DINAR X MAD MOROCCAN DIRHAM X MDL MOLDOVAN LEU X MGF MALAGASY FRANC X MKD DENAR X MMK MYANMAR KYAT X MNT MONGOLIAN TUGRIK X MOP MACAU PATACA X MRO MAURITANIAN OUGUIYA X MUR MAURITIUS RUPEE X MVR MALDIVE RUFIYAA X MWK MALAWI KWACHA X MYR MALAYSIAN RINGGIT X MZN MOZAMBIQUE METICAL X NAD NAMIBIAN DOLLAR X NGN NIGERIAN NAIRA X NIO NICARAGUAN CORDOBA ORO X NOK NORWEGIAN KRONE X NPR NEPALESE RUPEE X NZD NEW ZEALAND DOLLAR X OMR OMANI RIAL X PAB PANAMANIAN BALBOA X PAB US DOLLAR X PEN PERUVIAN NUEVO SOL X PGK PAPUA NEW GUINEA KINA X PHP PHILIPPINE PESO X PKR PAKISTAN RUPEE X PYG PARAGUAY GUARANI X QAR QATARI RIAL X QTQ GUATEMALAN QUETZAL X RON ROMANIAN NEW LEU X RSD DINAR X RUB RUSSIAN RUBLE X RWF RWANDA FRANC X SAR SAUDI RIYAL X SBD SOLOMON ISLANDS DOLLAR X SCR SEYCHELLES RUPEE X SEK SWEDISH KRONA X SGD SINGAPORE DOLLAR X SHP ST. HELENA POUND X SLL SIERRA LEONE LEONE X SOS SOMALI SHILLING X SRD SURINAM DOLLAR X
Page 133
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
SSP SOUTH SUDAN POUND X STD DOBRA X SVC EL SALVADOR COLON X SYP SYRIAN POUND X SZL SWAZILAND LILANGENI X THB THAI BAHT X TJS TAJIK SOMONI X TMT MANAT X TND TUNISIAN DOLLAR X TOP TONGAN PA'ANGA X TRY TURKISH LIRA X
TTD TRINIDAD AND TOBAGO DOL-LAR X
TWD TAIWAN DOLLAR X TZS TANZANIAN SHILLING X UAH UKRAINE HRYVNIA X UGX UGANDA SHILLING X UYU URUGUAYAN PESO X UZS UZBEKISTAN SUM X VEF VENEZUELAN BOLIVAR X VND VIETNAMESE DONG X VUV VANUATU VATU X WST SAMOAN TALA X XAF CFA FRANC BEAC X XCD EAST CARIBBEAN DOLLAR X XCD EAST CARRIBEAN DOLLAR X XOF CFA FRANC BCEAO X XPF CFP FRANC X YER YEMENI RIAL X ZAR SOUTH AFRICAN RAND X ZMW ZAMBIAN KWACHA X
Page 134
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix D : Bank Response Codes Auth Response Message Response Code Definition Exact Match 00 or 85 Exact match, nine-character numeric ZIP Exact Match 00 or 85 Exact match, five-character numeric ZIP Address Match 00 or 85 Address match only Zip Match 00 or 85 Nine-character numeric ZIP match only Zip Match 00 or 85 Five-character numeric ZIP match only No Match 00 or 85 No address or ZIP match Ver Unavailable 00 or 85 Address unavailable Ver Unavailable 00 or 85 Non-U.S. Issuer does not participate Retry 00 or 85 Issuer system unavailable Error Ineligible 00 or 85 Not a mail/phone order Serv Unavailable 00 or 85 Service not supported Approval 00 Approved and completed Card Ok 85 No reason to decline Call 1 Refer to issuer Call 2 Refer to issuer-Special condition No Reply 28 File is temporarily unavailable No Reply 91 Issuer or switch is unavailable Hold-call or Pick Up Card 4 Pick up card (no fraud)
Hold-call or Pick Up Card 7 Pick up card, special condition (fraud account)
Hold-call or Pick Up Card 41 Lost card, pick up (fraud account) Hold-call or Pick Up Card 43 Stolen card, pick up (fraud account) Acct Length Error EA Verification error Already Reversed 79 Already reversed at switch Amount Error 13 Invalid amount Can't Verify PIN 83 Cannot verify PIN Can't Verify PIN 86 Cannot verify PIN Card No. Error 14 Invalid card number Cashback Not App 82 Cash back limit exceeded Cashback Not Avail N3 Cash back service is not available Check Digit Error EB Verification error CID Format Error EC Verification error Date Error 80 Invalid date Decline 5 Do not honor Decline 51 Insufficient funds Decline N4 Exceeds issuer withdrawal limit Decline 61 Exceeds withdrawal limit Decline 62 Invalid service code, restricted Decline 65 Activity limit exceeded Decline 93 Violation, cannot complete Encryption Error 81 Cryptographic error Error XXXX 6 General error
Page 135
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Auth Response Message Response Code Definition Expired Card 54 Expired card Failure HV HV Hierarchy verification failure Failure CV CV Card type verification error Invalid Routing 92 Destination not found Invalid Trans 12 Invalid transaction No Account 78 No account No Action Taken 21 Unable to back out transaction Unsolic Reversal 76 Unable to locate, no match No Action Taken 77 Inconsistent data, rev., or repeat No Check Account 52 No checking account No Credit Acct 39 No credit account No Save Acct 53 No savings account No Such Issuer 15 No such issuer PIN Exceeded 75 PIN tries exceeded RE Enter 19 Re-enter transaction Sec Violation 63 Security violation Serv Not Allowed 57 Transaction not permitted-Card Serv Not Allowed 58 Transaction not permitted-Terminal
Srchg Not Allowed B1
Surcharge amount not permitted on Visa cards or EBT food stamps
Srchg Not Allowed B2
Surcharge amount not supported by debit network issuer
Stop Recurring R0
Customer requested stop of specific recurring payment
Approval T0 First check is OK and has been converted
Cannot Convert T1 Check is OK but cannot be converted - declined transaction
Invalid ABA T2 Invalid ABA number, not an ACH participant
Amount Error T3 Amount greater than the limit Unpaid Items T4 Unpaid items, failed negative file check Duplicate Number T5 Duplicate check number MICR Error T6 MICR error
Too Many Checks T7 Too many checks (over merchant or bank limit)
Page 136
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix E : Dynamic Descriptors Guide Scope
This section describes how to integrate to the Dynamic Descriptors feature in the
GlobalOnePay gateway.
Feature Description
• Descriptors
Transaction descriptors describe a particular payment in order to help to identify
that transaction on a bank statement or online bank interface. A good practice to help
minimize the risk of chargeback and in turn, to save money! Provide your customers with
your brand name and contact information to help them recognize their purchase, that’s
all it takes to make descriptors work for your business.
• Dynamic Descriptors
These types of descriptors describe a specific product or service and can vary from
one merchant to another. If your website sells applications or software services, this type
of descriptor can be a great way to let your customers know what they bought. Usually
customers know the name of an application they purchased and they will therefore
recognize that name on their bank statement.
The text that appears on the cardholders statement will be made up of:
• A “Prefix”, which is a static text value up to 12 characters long that is the
same for every transaction followed by
• The dynamic value, which is sent in by the website with the transaction.
Length is detailed in pseudo-code below.
Note: If there is no dynamic value sent with the transaction then we also store a
“default” value that will be displayed instead of the combination above.
Note: The “Prefix” will be right space padded up to 2, 7 or 12 characters,
whichever is the shortest.
Page 137
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Support and Activation
Currently Dynamic Descriptors is only available on TSYS Saratoga terminal IDs.
They are available on XML, Hosted Payment Page annd Virtual Terminal transactions. The
RESTful interface does not support this feature.
• Merchant Request
If required the merchant must raise a support ticket to request that this feature be
enabled on their Terminal ID. We will require 3 values to be able to enable this feature:
• The Terminal ID that it is to be enabled on,
• The “Prefix” string up to 12 characters long
• The “Default” string up to 25 characters long
Overview of Implementation
• Merchant Access & Configuration
Dynamic Descriptors are implemented using GlobalOnePays “custom fields”
functionality. When the feature is enabled on the terminal ID any user that has “Terminal
Setup” permissions, and therefore access to the Settings
=> Custom Fields control panel.
A new section for the Dynamic Descriptors is shown on the Custom Fields control
panel. This will allow the user to assign the desired custom field to be the Dynamic
Descriptor. A single custom field may be used by all possible integrations (Example
above), or a different custom field can be set per different integration method. Note that
“Other” will cover the XML gateway.
Page 138
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• Implementation/Integration
As stated above, the dynamic value for the transaction must be sent along with the
transaction parameters as a custom fields with the correct name, as defined by the
merchant when they configured the Dynamic Descriptors in section 4.1 above. Please
refer to the Integrator Guide document for detials about how to send custom fields with
transactions.
• Logic Flow
The logic of how Dynamic Descriptors are handled by our host is described
in this pseudo-code:
if (Terminal ID allows Dynamic Descriptors) if (Prefix is not blank AND correct custom field is sent and valid) Set the Dynamic Descriptor to the Prefix value followed by a “*” character and then the sent custom field value, and then truncate to 25 characters. else if (Default value is not blank) Set the Dynamic Descriptor to the first 25 characters of the Default value. end if else Set the Dynamic Descriptor to the “terminal merchant name” value from the terminal settings. end if
Note: a valid custom field value in not blank and contains only letters numbers and
spaces.
The terminal merchant name is the one in terminal settings:
Page 139
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Examples Terminal cases with Dynamic descriptor enabled.
Add details configured and sent
Terminal merchant name = “GlobalOnePay Example”
Dynamic Descriptor Prefix = “Order N”
Dynamic Descriptor Default Value = “Storename” Custom Field value = “1234”
• If a transaction is sent with order number “1234”, the result would be:
Order N * 1234
• If a transaction is sent with no order number, the result would be:
Storename
No default
Terminal merchant name =”GlobalOnePay Example”
Dynamic Descriptor Prefix= “Order N”
Dynamic Descriptor Default = “”
Custom Field value = “Order Number”
• If a transaction is sent with order number “1234”, the result would be:
Order N * 1234
• If a transaction is sent with no order number, the result would be:
GlobalOnePay Example
No default and no prefix
Terminal merchant name =”GlobalOnePay Example”
Dynamic Descriptor Prefix = “” Dynamic
Descriptor Default = “” Custom Field value = “”
• If a transaction is sent, the result would be:
GlobalOnePay Example
Page 140
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix F : Smart Transaction Routing Guide
Introduction
The GlobalOnePay system is a secure server-based transaction processing service
that will enable your business to authorise and process credit/debit card transactions
online in real-time. The information needed to process the transactions is sent over a
secure, encrypted internet connection.
Large enterprises often have many strategies that require the use of multiple
merchants accounts. This can be for:
• Geographical independence
• Authorization maximisation
• Load balancing
• Fraud/chargeback balancing & mitigation
• Interchange optimization
• Acquirer value capping
• Card scheme routing
• Currency management
• Affiliate management
The GlobalOnePay routing and balancing functionality can be used for automation
of all of these tasks across all of the acquirers that GlobalOnePay support.
Concepts
GlobalOnePay routing and balancing is based on the concepts of “Processing
Terminals” and “Routing Terminals”. Both are 7-8 digit numbers beginning in your 4-
5 digit Merchant ID
Page 141
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Processing Terminals Processing terminals are the same as standard Terminals (Terminal IDs) if you are
familiar with basic processing through GlobalOnePay.
They can be thought of as having a 1:1 relationship to an acquiring Merchant
Account. It is possible to have multiple processing terminals pointing at one merchant
account though, if required.
Processing terminals are where transactions actually belong to, and are available
after authorisation/settlement for reporting purposes.
Processing terminal IDs end in 001, 002, 003, etc.
Routing Terminals Routing terminals are pseudo terminals that you can send all of your transactions
to and based on the “routing rules” and “balancing types” that are set up for that routing
terminal it will choose the appropriate processing terminals (acquirer merchant account)
and send the transaction through it for authorisation/settlement.
Multiple Routing Terminals can be set up also, each with its own set up processing
terminals, routing rules and balancing configuration.
Routing terminal IDs end in 999, 998, 997, etc.
If using routing or balancing all transactions must be submitted to us via a Routing
Terminal.
Routing and Balancing Routing and Balancing are two different but complimentary features in the
GlobalOnePay system. A simple way to describe them is:
• Routing rules are purely based on the data in the transaction being
processed. They look at the data and depending on the rules configured in
the routing terminal they decide which processing terminal to use for the
transaction. They can be based on the card or order details or any custom
fields/data that the merchant chooses to send in with the transaction, such
as Product SKU, affiliate ID, etc. The rules are boolean and prioritised. They
can also be used to automatically authorise transactions only for later
capture, or decline transactions immediately.
Page 142
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• Balancing is more concerned with the bigger picture of overall acquirer
volume management, high volume load balancing, and high availability.
Priority Routing rules take preference over balancing. If a rule transaction to a processing
terminal is a match then that rule will be applied. Otherwise balancing will be applied.
Balancing
Balancing is not as granular as Routing. The choices made per transaction are
made by the system, not by rules that a merchant can configure. There are 4 types of
balancing:
• Round Robin: Tries eligible processing terminals in sequential order (load
balancing)
• Processed Value Ratio: Prioritises processing terminals based on their
“processed value/value limit” ratio (in reverse). This method effectively
sends a transaction to whichever eligible processing terminal has used up the
lowest percentage of its value limit.
• Value Processed: Sends transactions to the processing terminal with the
lowest value processed, regardless of limits.
• Terminal Priority: Prioritises one processing terminal. All eligible trans will get
sent through this by default. If that terminal reaches it's value limit then the
next highest priority eligible processing terminal will be used.
Value Limits
Value limits are normally set at a processing terminal level, however greater
granularity can be achieved by setting the limits at a card type (card scheme) level also,
under that processing terminal. Card Type limits take precedence over processing
terminal level limits.
Page 143
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Balancing Eligibility
A processing terminal is only considered eligible to be considered in the group of
balancing terminals for a specific transaction if:
• It is not deactivated
• Its card type value limit (if set) for the transactions card type has not been
exceeded
• Its processing terminal level value limit (if set) has not been exceeded
• It supports the card type, base currency and transaction type of the
transaction being processed
Implementation
Balancing Balancing is purely configured by GlobalOnePay. If you have multiple merchant
accounts and want to avail of our balancing functionality please contact our support help-
desk at [email protected] with the details of the configuration you are
looking for.
Routing Rules Access Permissions
To enable configuration of routing rules you will require:
• Routing/Balancing enabled on the terminal by GlobalOnePay,
• Access to a user login that has permission to modify the routing rules (“Allow
Routing Terminal” permission).
Please contact us if you have any problems configuring these.
Page 144
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Navigating to the Rules Editor To access the rules editor once you are logged in you will have to:
1. Switch to the appropriate Routing ter-
minal from the Terminal Selection box
in the top right of the SelfCare System
(see across).
2. Select Settings -> Routing Rules from
the menu. If either of these are not
present then ensure that you have
successfully selected a routing terminal
(step 1) and that your user has “Allow
Routing Terminal” permissions.
3. You will be displayed the rules editor page. Initially there may be “No rules
defined”. To start creating a rule click “Add Routing Rule”.
Page 145
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Creating a rule The images below and their descriptions describe how rules are created. The rules
are boolean based and so should be very familiar in structure to anyone with any
development experience at all, but even without that the interface is very
straightforward.
As you can see from above the first thing you must do is give the rule a name. This
allows for easy reference later on if multiple rules are configured.
Once a name is configured you must select the data field that you want the rule to
act upon. Note that the fields in the image above are always available. Any fields that
you set up as Custom Fields (Settings -> Custom Fields) under that routing terminal will
also appear here and can be used as routing parameters.
Custom Fields can be sent either via the XML or Hosted Payment Page integration
methods (please see integration documentation for more information).
Page 146
© 2017 GlobalOnePay Corp. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Next you must select the Operator that you need for the rule. That the list above
are available for number based fields such as the Amount in this demonstration, but for
strings another operator called LIKE is also available and operates the same way as the
SQL LIKE string operator. Note that the IN operator will cause a preview to be shown in
the value input box. Also note that strings are automatically converted to numbers and
numbers to strings as necessary.
The next thing to do is to enter the string or amount or list that the transaction
parameter you selected is to be compared to. Again this generally adheres to SQL
comparison rules.
Once the comparison/identification part of the rule is complete you will see a
logical synopsis of it in text at the bottom of the rule box. Now you need to define the
action. You can:
Page 147
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Route To Terminal
This will use a specific Processing Terminal to process the transaction. The
Processing Terminal should be selected from the dedicated drop down box next to it
(right).
• Authorize Only: This will Authorize against a Processing Terminal chosen
by the Balancing functionality. The transaction will not settle by default,
but instead will appear in the Routing Terminals “Authorized Transaction
Queue”. You will be able to see the Processing Terminal that was used in
this list. This queue is used for merchants who need to manually flag
transactions for settlement, such as merchants who perform delayed
delivery of goods.
• Decline: Simply declines the transaction without going online. Again it
will balance the transaction before declining it to determine which
Processing Terminal it should be stored under.
Page 148
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Once a rule is complete click “Save Routing Rule” and it will appear as
above. They can individually be edited, disabled or removed using the links next to
them.
When multiple rules are configured you can re-order/prioritise then using drag
and drop.
Note that you must enable the “Enable Routing” checkbox is you want the rule set
to take affect!
Features Not Supported
• eDCC
Dynamic Currency Conversion relies on rates from a specific acquirer. As multiple
rates may be available, and DCC is a two-step process, when invoked via XML, there is
no way to currently ensure that the correct rate is used with the correct acquirer.
Therefore eDCC or any other DCC or is not supported by Routing Terminals through
XML. It is however supported via the Hosted Pay- ment Page for Routing Terminals.
• 3D Secure
The same applies for 3D Secure and for eDCC above. It is not available via XML
but is available for Hosted Payment Page transactions on the Routing Ter- minal.
Page 149
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
• SecureCards & Subscriptions (Recurring Billings)
SecureCards are configured under a particular Processing Terminal only, and so
cannot be supported by Routing Terminals. Subscriptions are based on SecureCards
and so also cannot be processed under Routing Terminals.
Page 150
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix G : Gateway Secure ACH Error Codes
Error Code Description E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E04 INVALID REFERENCE DETAILS E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF
E09 INVALID DATETIME E13 INVALID HASH E23 INVALID PERMITTED TERMINALID E24 Invalid Account Type
Page 151
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix H : XML Gateway Subscription Error Codes These are subscription specific error codes:
Error Code
Description
E01 SYSTEM ERROR – TRY AGAIN E03 OPERATION NOT ALLOWED E06 INVALID TERMINALID E07 METHOD NOT SUPPORTED E08 INVALID MERCHANTREF E09 INVALID DATETIME E13 INVALID HASH E20 INVALID LENGTH E21 INVALID PERIOD TYPE E22 INVALID NAME E23 INVALID DESCRIPTION E24 INVALID RECURRINGAMOUNT E25 INVALID INITIALAMOUNT E26 INVALID TYPE E27 INVALID ONUPDATE E28 INVALID ONDELETE E29 INVALID TERMINAL CURRENCY E30 INVALID STORED SUBSCRIPTION REF E31 INVALID STORED SUBSCRIPTION MERCHANT REF E32 INVALID SECURE CARD MERCHANT REF E33 INVALID STARTDATE E34 INVALID ENDDATE E35 INVALID EDCCDECISION E36 SETUP PAYMENT PROCESSING ERROR E37 INVALID SUBSCRIPTIONRECURRINGAMOUNT E38 INVALID SUBSCRIPTIONINITIALAMOUNT E41 PASS ONLY ONE OF CARDREFERENCE OR SECURECARDMERCHANTREF
OR SECUREACHACCOUNTMERCHANTREF OR ACHREFERENCE E42 INVALID_SECUREACHACCOUNT_MERCHANTREF E43 INVALID_PAYMENT_AMOUNT E44 INVALID_ORDERID E45 INVALID_MULTIPLE_PAYMENTS E46 INVALID_PAYMENT_SKIP_PERIOD E47 INVALID_BANK_IDENTIFIER E60 INVALID_SECUREACH_MERCHANTREF E61 INVALID_SECUREACH_ACHREFERENCE E62 SECUREACHACCOUNTMERCHANTREF_ACHREFERENCE_ABSENT E63 SECUREACHACCOUNTMERCHANTREF_ACHREFERENCE_BOTH_PRESENT E64 INVALID_SEC_CODE E65 INVALID_RECEIPT_SUBSCRIPTION_URL
Page 152
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix I : Transaction Types/Statuses Types:
• PAYMENT: a new Payment transaction
• REFUND: a new Refund transaction
• VOID: Temporary type using during send authorization request
Status:
• IN_PROGRESS: Initial approve got from the Gateway, NET Traxion is
expecting the final result
• COMPLETE: the final result is approved
• DECLINED: the final result is declined or the Gateway declined transaction
at authorization request, for instance check amount is more than
acceptable value
• VOID: Gateway approved Void transaction
Note: See section 4.2.
Per response from the gateway the Reversal transaction cannot be voided.
Page 153
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix J : Provence/State Codes Code State Name AB Alberta AK Alaska AL Alabama AR Arkansas AS American Samoa AZ Arizona BC British Columbia CA California CO Colorado CT Connecticut DC District of Columbia DE Delaware FL Florida GA Georgia GU Guam HI Hawaii IA Iowa ID Idaho IL Illinois IN Indiana KS Kansas KY Kentucky LA Louisiana MA Massachusetts MB Manitoba MD Maryland ME Maine MI Michigan MN Minnesota MO Missouri MS Mississippi MT Montana NB New Brunswick NC North Carolina ND North Dakota NE Nebraska
Page 154
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Code State Name NF Newfoundland NH New Hampshire NJ New Jersey NM New Mexico NS Nova Scotia NT Northwest Territories NU Nunavut NV Nevada NY New York OH Ohio OK Oklahoma ON Ontario OR Oregon PA Pennsylvania PE Prince Edward Island PR Puerto Rico QC Quebec RI Rhode Island SC South Carolina SD South Dakota SK Seskatchewan TN Tennessee TX Texas UT Utah VA Virginia VI Virgin Islands VT Vermont WA Washington WI Wisconsin WV West Virginia WY Wyoming YT Yukon Territory
Page 155
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix K : Glossary ACH -- Automated Clearing House
AVS -- Address Verification System
HTML -- Hypertext Mark Up Language
HTTPS -- Hypertext Transfer Protocol Secure
MIS -- Management Information System
TPS -- Transaction Processing Services
URL -- Universal Resource Locator
BIN -- Bank Identification Number
CVV -- Card Verification Value
eDCC -- Electronic Dynamic Currency Conversion
MCP -- Multi Currency Processing
MSR -- Magnetic Stripe Reader
CHP -- Card Holder Present
Page 156
© 2017 GlobalOnePay. All rights reserved. This material is not to be reproduced, disclosed, or used except in accordance with program license or other written authorization of GlobalOnePay. All other trademarks, service marks, and trade names referenced in this material are the property of their respective owners.
Appendix L : Version Control Author Version Date Changes Alexandre A. 4.3 2017-11-02 - Added Level 2 processing and
ThreatMetrix information to section 4.1 / 5.1.1 / 5.1.3
- Updated section 5.3 to accommodate ThreatMetrix
- Added section 2 / 3.10