Merchant Integration Guide - daks2k3a4ib2z.cloudfront.net · XML API Integration Guide . Version 4.3 . November 2, ... 3.9.1 GlobalOnePay Testing Guide ... 6.5 XML Secure ACH Integration

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


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


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


For support, contact

[email protected]

+1 (844) 864 9590

mailto:[email protected]

Page 6


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


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


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


• 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


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


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


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


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


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

https://testpayments.globalone.me/merchant/paymentpage

https://testpayments.globalone.me/merchant/preauthpage

https://testpayments.globalone.me/merchant/securecardpage

https://testpayments.globalone.me/merchant/subscriptionpage/register


Page 15


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:


The live URL will be provided once merchant testing is complete.

https://testpayments.globalone.me/merchant/xmlpayment

https://testpayments.globalone.me/merchant/gateway.xsd

https://testpayments.globalone.me/merchant/mpi

https://testpayments.globalone.me/merchant/bulkpayments/submit

https://testpayments.globalone.me/merchant/bulkpayments/result


Page 16


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


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


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


• 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


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



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


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:


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


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


Notes:


TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE



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


PERMITTEDTERMINALS N List of permitted terminals. Comma separated list without spaces.

Notes:


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


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:


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:


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


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


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


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


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


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:




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:







Terminals.

Page 32


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


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


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


TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME

+RESPONSECODE+RESPONSETEXT+SECRET

• The DATETIME is the time returned by the bank for the transaction.

ThreatMetrix Notes:




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>




“REJECT”.

Page 35



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


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


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



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:






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



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


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


Error handling


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


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.



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


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


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


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:






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:






Page 44



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


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.


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.




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


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


TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+


• The DATETIME is the time returned by the bank for the transaction.

ThreatMetrix Notes:




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>




“REJECT”.

Page 47



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


Error handling


XML message with the simple tags: <ERROR><ERRORSTRING></ERRORSTRING></ERROR>

Page 48


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>



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



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.




HASH An MD5 HASH. See Note2 below.

Notes:


TERMINALID+UNIQUEREF+AMOUNT+DATETIME+SECRET


TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+


• The MD5 HASH response is generated using the following as an input

string:

TERMINALID+UNIQUEREF+AMOUNT+DATETIME+


Error handling


XML message with the simple tags below: <ERROR><ERRORSTRING></ERRORSTRING></ERROR>

Page 50


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>



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


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.


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:


TERMINALID+UNIQUEREF+AMOUNT+DATETIME+SECRET

• The MD5 HASH response is generated using the following as an input

string:


+RESPONSETEXT+SECRET (n.b. the response UNIQUEREF is to be used

here)

Page 52


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>



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



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.


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.


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


Notes:


TERMINALID+ORDERID+CARDTYPE+CARDNUMBER+CARDEXPIRY

+CARDHOLDERNAME+AMOUNT+DATETIME+SECRET


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:


For multi-currency Terminal IDs (see section 3.3 above) this should be:

TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME

+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


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


Notes:


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:


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


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


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


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


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>



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>


Field Name Required Description UNIQUEREF Y The UNIQUEREF for the transaction

being updated. TERMINALID Y A TerminalID provided by GlobalOnePay.


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



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.


DATETIME Format DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See note 2 below.

Notes:


TERMINALID+UNIQUEREF+OPERATOR+FROMSTATUS+TOSTATUS

+APPROVALCODE+DATETIME+SECRET


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:


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


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:


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


Notes:


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


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:



Page 65



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


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


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:


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


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:



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


Notes:


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


Notes:


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


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


Notes:

• If permitted terminals are not used, the MD5 HASH is generated using the


TERMINALID+MERCHANTREF+DATETIME+CARDNUMBER+

CARDEXPIRY+CARDTYPE+CARDHOLDERNAME+SECRET

• If permitted terminals are used, The MD5 HASH of the request is


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>


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


Notes:


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


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:


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>


Field Name Description DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.

Notes:


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>


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


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:



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>


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


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:


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>



Page 76


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:


TERMINALID+MERCHANTREF+NAME+EMAIL+PHONE+

CREATIONDATE+DATETIME+SECRET

• No field accepts partial match

Page 77


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>


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


Notes:


TERMINALID+MERCHANTREF+CARDREFERENCE+CARDHOLDERNAME

+DATETIME+SECRET

Errors handling




Page 79


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


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


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:


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



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:


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


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


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-


Notes:


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>



request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.

Notes:



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


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:



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



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:


TERMINALID+MERCHANTREF+ACHREFERENCE+ACCOUNT_NAME+

DATETIME+SECRET

Error handling


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


• 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


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:


Subscription registration POST parameters description:

Field Name Required Description TERMINALID Y A TerminalID provided by GlobalOnePay.


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


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


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



STARTDATE+SECRET

Notes for ACH:


TERMINALID+MERCHANTREF+SECUREACHACCOUNTMERCHANTRE

F+DATETIME+STARTDATE+SECRET

• If “ACHREFERENCE ” is used, the MD5 HASH is generated using the


TERMINALID+MERCHANTREF+ACHREFERENCE+DATETIME+

STARTDATE+SECRET

Page 90


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


Notes:


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


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


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


Notes:


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>


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:



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


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


Notes:



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>



request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.

Notes:



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>


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


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


Fields description:


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


Notes:

• If "SECURECARDMERCHANTREF" is used, the MD5 HASH is generated


TERMINALID+MERCHANTREF+STOREDSUBSCRIPTIONREF+

SECURECARDMERCHANTREF+DATETIME+STARTDATE+SECRET

• If "CARDREFERENCE" is used, the MD5 HASH is generated using the


TERMINALID+MERCHANTREF+STOREDSUBSCRIPTIONREF+

CARDREFERENCE+DATETIME+STARTDATE+SECRET

• STOREDSUBSCRIPTIONREF should be omitted if it is not set.

NEWSTOREDSUBSCRIPTIONINFO fields description:


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.


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


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>



registration request. DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note 1 below.

Notes:



Error handling

If new subscription was not registered, error code and error message will be


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


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


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


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


TERMINALID+MERCHANTREF+SECURECARDMERCHANTREF+

DATETIME+STARTDATE+SECRET

• If "CARDREFERENCE" is used, the MD5 HASH is generated using the



STARTDATE+SECRET

Page 103


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>



registration request DATETIME Format: DD-MM-

YYYY:HH:MM:SS:SSS HASH An MD5 HASH. See Note below.

Notes:



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


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


Fields description:

Notes:



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>



registration request. DATETIME Format: DD-MM-

YYYY:HH:MM:SS:SSS. HASH An MD5 HASH. See Note below.

Notes:



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-


Page 105


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:


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:



Example of a successful subscription cancellation response: <CANCELSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </CANCELSUBSCRIPTIONRESPONSE>


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:



Page 106


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


<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:


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


Notes:


TERMINALID+MERCHANTREF+ACHREFERENCE+DATETIME+START

DATE+SECRET

• If using a secure ach account the MD5 HASH is generated using the


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.


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


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>



Notes:



Error handling

If new subscription was not registered, error code and error message will be


A listing of potential error results is listed in Appendix H XML Gateway Subscription

Error Codes.

Page 110


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:


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


HASH Y An MD5 HASH. See notebelow.

Page 111


Notes:


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>


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:



Error handling

If subscription was not updated, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>


Error Codes.

ACH Subscription Deletion Request 7.2.9

Note that Subscription MerchantRef's cannot be re-used after deletion. This is


for data integrity and issue tracing. Deleted Subscriptions can still be viewed in the

SelfCare System by using the Advanced Filter.

Page 112


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:



GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note 1 below.

Notes:



Example of a successful subscription deletion response: <DELETESUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </DELETESUBSCRIPTIONRESPONSE>



Notes:



Page 113


Error handling

If subscription was not deleted, error code and error message will be returned: <ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>


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:



GlobalOnePay. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH Y An MD5 HASH. See note below.

Notes:



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




Notes:



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


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.


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:


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>


Field Name Description RESPONSECODE A or D or R(Approved or Declined or Referral). RESPONSETEXT The text of the authorization.

Page 116


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:




Error handling

If subscription payment was not accepted, error message will be returned: <ERROR> <ERRORSTRING>Invalid HASH field</ERRORSTRING> </ERROR>


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




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:


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>


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:


TERMINALID+ORDERID+UNIQUEREF+AMOUNT+DATETIME+


Page 118



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>


Error Codes.

Page 119


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


TERMINALID+MERCHANTREF+NOTIFICATIONTYPE+DATETIME+

ORDERID+AMOUNT+RESPONSECODE+RESPONSETEXT+SECRET

Page 120


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:


UNIQUEREF Y Generated reference that should be stored for tracking and remote XML refunding.


DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS HASH Y An MD5 HASH. See Note below.

Notes:


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



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:


TERMINALID+RESPONSECODE+RESPONSETEXT+UNIQUEREF+

DATETIME+SECRET

Page 122


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:


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


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


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


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:


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:


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


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:


TERMINALID+ORDERID+AMOUNT+DATETIME+RESPONSECODE+

RESPONSETEXT+SECRET

Page 127


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


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


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


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


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


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


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


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


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


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


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


• 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


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


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


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


• 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


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.

mailto:[email protected]

Page 144


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


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


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


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


• 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


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


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


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


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


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


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


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

Documents

Merchant Integration Guide - daks2k3a4ib2z.cloudfront.net · XML API Integration Guide . Version 4.3 . November 2, ... 3.9.1 GlobalOnePay Testing Guide ... 6.5 XML Secure ACH Integration