XML API Integration Guide

Transcription

1 XML API Integration Guide Version July 10th,2015

2 For support contact

3 Table of Contents 1 Introduction Choosing an Integration Method Scope Integration Methods to Consider Hosted Payment Page XML Gateway Costs Items for Consideration A Word on Functionality Secure Communication/Card Types Supported Secure Communication with HASH Parameters Card Types Multi-Currency Terminal IDs Integration and Validation Procedure GlobalOne Testing Guide Merchant Validation Document Hosted Pages Hosted Page Styling Basic Mode Styling Advanced Mode Styling Hosted Pay Page Test Credentials Sandbox Test Details Test Cards MaxMind MinFraud (Where Available) Payment Page Hosted Pre-Auth Page Background Validation

4 5.6 Hosted Pages in iframe Format SecureCard Storage via Hosted Payment Page XML Payments Integration Test Credentials Sandbox Test Details Test Cards MaxMind MinFraud (Where Available) Request Types XML Payments Pre-Authorization Request Pre-Auth Completion Request Refunds XML Requests with edcc (Where Available) edcc Exchange Rate Request edcc Information in the XML Requests Transaction Status Updates Retrieve Foreign Currency Exchange Rates D Secure for XML transactions (Where Available) Secure Card Storage Secure Card Registration and Updating from the Hosted Page XML Secure Card Integration Secure Card Details Registration and Updating Card Detail Removal Card Details Search XML Payments Using a Stored Secure Card Subscriptions Subscription Registration From Hosted Pay Page XML Subscription Integration Stored Subscription Request Stored Subscription Deletion Request Subscription Creation Request

5 8.2.4 Update Subscription Request Subscription Deletion Request Subscription Payments Request Subscription Notifications Bulk Payments Request File Submission Request CSV File Format Request File Submission Response Response File Request Response File Format Appendix A: CVV & AVS Responses CVV results: AVS results: Appendix B: Supported Currencies Appendix C: Bank Response Codes Glossary Version Control Author Version Date Changes Raj Sandhu /07/2015 Updated TOC; Added new section 4 Hosted Pages, 4.1 Hosted Page Styling, 4.2 Basic Mode Styling, 4.3, Advanced Mode Styling; Update under XML Payments section added Recurring Payment Flagging and under Pre-Authorization Request. Updated Test Card details under section Updated under Request File Submission added /submit to test link Raj Sandhu /11/2014 Under XML Payments section added MSR/CHP to TRACKDATA added new terminal type #3 Cardholder Present & #0 Cardholder Present (CHP) transaction, also added new note #4. Added +BANKRESPONSECODE+ to hash return in section under note #2b; Updated glossary with MSR & CHP description Raj Sandhu /10/2014 Removed Section 2.4.1, added new notes #2 Under Section added +BANKRESPONSECODE+, Added new Section 5.7, Added Appendix C for response codes, under Section modified & added new Field Names; XID,CAVV,MPIREF,DEVICEID,CUSTOMFIELD also added BANKRESPONSECODE. Under Section Notes 5

6 #2a added BANKRESPONSECODE and added new note #3. Under Section under Field Name added BANKRESPONSECODE, modified note #2 under section also corrected the respond hash calculation; and under Section 7.1 removed MERCHANT and replaced with REFERENCE, removed AVSONLY Under Section XML Payments table, & updated TOC Raj Sandhu /08/2014 Changed ORDERID to UNIQUEREF in Section 4.3 Section4.5 and section Added new section Transaction Status Updated Kevin Goddard /07/2014 Added note about pre-auths, added information to card expiry and cardholdername in sect 5 XML Payment Integration, added processing terminal sect 5, Deleted reference and added payment request fields section under Pre-Auth Requests, added section under unreferenced refunds, carddetails tag in XML requests. Kevin Goddard /04/2014 Changed references to UTF8 to UTF-8, Added section FX Terminal Rates Lookup, Added Subscription Notifications, added user setup section added currency table Kevin Goddard /03/2014 Added section on Testing Guide and merchant Validation, added two successful trx per trx type required. Removed reference to MCP in hash for preauth. Update URL to globalone.me. Changed GlobalONE to GlobalOne Kevin Goddard /02/2014 Added Development team modifications Kevin Goddard /02/2014 Revised Version 6

7 1 Introduction The GlobalOne system is a secure server-based transaction processing service that will enable your business to authorize 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 GlobalOne server connects with your acquiring bank for payment authorization and if the sale is authorized, returns a receipt to the customer. GlobalOne settles the transactions automatically and the acquiring bank deposits the funds into your bank account. GlobalOne automatically archives sales that are finalized 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 hence take automatic credit card payments. 2 Choosing an Integration Method There are two integration methods available to GlobalOne; the Hosted Payment Page and full XML integration. You can use one or a combination of them as required, but you should consider the integration method carefully before starting any development planning. 2.1 Scope This section may be used as a guide to help you decide to most appropriate method of Integrating with the GlobalOne gateway. It is intended for review after you have decided upon your Merchant Account but before you start integrating with us. All costs should be considered including integration cost, ongoing maintenance costs, PCI DSS compliance costs and GlobalOne s own charges. Different technologies, languages, consumer industries, server environments and other technical challenges should also be considered. 2.2 Integration Methods to Consider Hosted Payment Page The Hosted Payment Page (HPP) has been created as a method for small-to medium sized organizations to integrate their websites with our payment gateway. 7

8 This is a hosted service with the highest levels of Internet security, whose appearance can be customized to look just like your site. This is solely for use as a payment gateway for websites. The benefits of the HPP: SSL certificate Costs: PCI DSS requires that web pages accepting credit card information must have SSLv3 128-bit minimum certificates. Our host has a 128-bit to 256-bit certificate with full "green bar" functionality for extra customer confidence. The equivalent certificate from VeriSign is the "Secure Site Pro with EV" which currently costs upwards of $1,500/year. PCI considerations: PCI also states that any site accepting card information must NEVER store the CVV, and if it does store the card number, it must be 256- bit AES encrypted. Most web servers log traffic to and from them, which may include card numbers. These logs would have to be audited on a continual basis to ensure that card numbers are not being stored. Also, if you accept any sensitive card information on your site you jump up from a PCI SAQ A (Self- Assessment Questionnaire) to an SAQ D. The required documentation grows significantly at this point Ease of integration: As opposed to other integration methods, the HPP integration is VERY simple. You just have to submit a simple web form to us and then display the response that our host sends back. Functionality Deployment: The robust functionality of GlobalOne may be added to the HPP without additional development. As a result you may offer your customers with the many features of GlobalOne quickly and easily. Plug-in availability: Off the shelf Hosted Payment Page plug-ins have been developed for many popular shopping carts. Please contact our integration team for a list of current carts supported. iframe implementable: If you do not want the customer to leave your site you can implement the HPP within a frame. This is preferable for some merchants, but also means that the customer will not see the green bar that would be displayed otherwise XML Gateway The XML gateway is intended for larger, more complex integrations. This method offers full access to all of our products and functionality through a high speed, common platform gateway. As a result the payment and related functionality is seamlessly integrated into your existing corporate infrastructure. 8

9 Companies using the XML gateway must maintain their own security and are subject to rigorous PCI security criteria. Benefits of the XML gateway: Access: All of our products can be accessed through the XML gateway, whether you want to process a payment, register card information for secure storage on our system, setup a recurring payment, check the status of existing subscriptions or refund a customer. Other related functionality may be available depending on your merchant agreement and specific needs. Site integration: For a seamless experience, XML site integration may be more beneficial to an organization. Cards may be securely billed via tokenization, allowing for easy, yet secure PCI compliant reoccurring billing. Integration to CRM/Internal Systems: Larger more complex companies may require an interface to CRM or accounting systems. This is more easily achieved when data is passed via XML. Control: XML integrations give your company more control over the flow of data, assuming it meets PCI compliance. 2.3 Costs Items for Consideration For small businesses the Hosted Payment Page is generally a more cost effective solution. There may be extra costs involved with using a HPP service; however this is greatly outweighed by the savings on purchasing an SSL certificate, and the cost in time and money ensuring that the development and processes are PCI compliant. For larger enterprises or where seamless integration or CRM connectivity is critical, XML integration may outweigh the costs involved. Resource availability and programming costs should be considered carefully. However you choose to integrate our team of specialists is available to help you make your decision and implement your solution. 2.4 A Word on Functionality This document encompasses all of the features and functionalities of the GlobalOne gateway. It is important to understand that not all features and functionalities may be utilized in your specific development and implementation. Although there are basic functionalities required, many are not and will be determined by your specific business needs. Please consider your business needs before you begin development. 9

10 3 Secure Communication/Card Types Supported 3.1 Secure Communication with HASH Parameters Every request to and response from GlobalOne 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-themiddle 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, MD5 input strings are listed as (Please note you should not include the + symbols in the calculation): TERMINALID+ORDERID+AMOUNT+DATETIME+SECRET For the example in the first section below if the shared SECRET was x4n35c32rt then the MD5 HASH would be calculated as: md5( :10:43:01:673x4n35c32RT ) This would equal to: dd77fde79d1039d6b39e20d Note that the MD5 function should always use a character set of UTF8 where appropriate. 3.2 Card Types The card types that your account supports are determined by your acquiring bank and Merchant Account. The options are: VISA, VISA DEBIT, ELECTRON, MASTERCARD, DEBIT MASTERCARD, MAESTRO, LASER, AMEX, DINERS, JCB, DISCOVER. All live accounts will be set up with the correct card types enabled as per the documentation that GlobalOne receives from your acquiring bank. ***Please send any amendments to your merchant account to our support team so we may keep your account details up to date. For testing purposes, use the test card numbers and sandbox test details are described in the sections below. 3.3 Multi-Currency Terminal IDs In some instances terminals that support multi-currency functionality are available depending on the issuing bank. Such terminals will have their own terminal ID and may be identified with the letters MC after the terminal ID. A Multi-currency terminal will allow processing of a transaction in one of a number of the listed currencies in the drop down menu via the single terminal ID. 10

11 When a terminal is set to process in multiple currencies the currency type ***MUST*** be included in the request and response hash. Details on the hash and response are listed in section 4 and in the sections relating to HPP and XML integration within this document. Please ask our integration team if you have any questions relating to multi-currency terminals. 3.4 Integration and Validation Procedure In order to integrate with the GlobalOne gateway you will be required to make the necessary modifications to your website to connect with the GlobalOne gateway. This document describes the cases and methods to achieve this GlobalOne Testing Guide In addition you must read the GlobalOne Testing Guide for more information on the process Merchant Validation Document 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 . The integration team will contact you to confirm that you have successfully validated against the GlobalOne Gateway. 4 Hosted Pages GlobalOne provide Hosted Pages for the entry of some sensitive data so that the merchant s servers do not have to be exposed to this data. This is advisable to reduce the security overhead of the integrated solution as GlobalOne is responsible for maintaining the security and integrity of the data sent to these pages. The payment is then processed by GlobalOne 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. 11

12 4.1 Hosted Page Styling The GlobalOne hosted pages can be heavily styles 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. As you can see different template can also be used for Mail Order (TEL) and ecommerce transactions (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. 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 12

13 4.2 Basic Mode Styling 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. 13

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

15 5 Hosted Pay Page 5.1 Test Credentials Sandbox Test Details The following values should be used when testing against the Pivotal test URLs. Please see the Testing and Certification guide for further details. The terminal details are: a. Currency Terminal ID Shared SECRET b. USD SandboxSecret001 c. CAD SandboxSecret002 d. EUR SandboxSecret003 e. GBP SandboxSecret004 f. MCP* SandboxSecret001 *MCP is the Multi Currency Terminal Settings Test Cards Test cards that may be used on our host are: Visa MasterCard Laser Maestro UK Domestic Maestro Electron Visa Debit Debit MasterCard American Express JCB Diners Solo All test cards can be used with any expiry date in the future, and any CVV (American Express cards have a 4 digit CVV) and any Issue number where appropriate. 5.2 MaxMind MinFraud (Where Available) Certain 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. More information about this service is available on the MaxMind website here: 15

16 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 read the MaxMind website linked above thoroughly before implementing this feature. 5.3 Payment Page The Hosted Payment Page (fig. 1) is built to allow merchants to easily integrate with the GlobalOne system for processing payments without requiring significant development by the merchant. The payment Page header and footer may be configured from the merchant Self Care system via Payment Page Layout. You will need to include HTML before ( Header ) and after ( Footer ) the payment form, all of which is within the BODY tag. As a result please do not include HTML header links or scripts. JavaScript may not be used; however inline CSS style tags may be included in the header. Please contact our integration team should you have further questions. Cardholders are redirected to the GlobalOne payment page once they have made the decision to buy. Upon the customer clicking the submit button, all payment details are collected, processed and GlobalOne gives a result to the cardholder. The cardholder is redirected to the merchants receipt page. GlobalOne may be configured at the terminal level to manage 3D Secure and edcc functionality when available. The above is accomplished by means of a simple HTML form post with a number of defined form fields (below). The following is the GlobalOne test payment page URL: The live URL will be provided once testing is complete. 16

17 Fig 1. An example of a hosted Payment Page The following table describes the form fields to be posted: Field Name Requi Description red TERMINALID Y A TerminalID provided by GlobalOne. 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 1 below. CARDHOLDERNAME N This will pre-populate the Cardholder Name field on the payment 17

18 page. This will be editable on the payment page. 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. N An address to send a confirmation to. Normally this is cardholder 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 5.5**** 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 Normal Mail Order/Telephone Order trans (Mail Order for First Data Latvia) 5 = 3DS fully authenticated trans 6 = 3DS attempted trans 7 = Normal ecommerce trans 9 = Telephone Order (First Data Latvia only) ADDRESS1 N Will pre-populate the ADDRESS1 field on the Hosted Payment Page if there is also a valid POSTCODE sent and AVS is enabled for the terminal. Handling of display is managed by the GlobalOne and can be to display read only, display editable or to hide them on form. ADDRESS2 N The same handling as ADDRESS1. POSTCODE N If sent then AVS data will be populated. Also required for MaxMind MinFraud fraud scoring. See section 5.2 CITY N Required for MaxMind MinFraud fraud scoring. See section 5.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 5.2 COUNTRY N ISO alpha-2 code. Required for MaxMind MinFraud fraud scoring. See section 5.2 PHONE N Customer phone number, to be stored against transaction. International format and numeric. CUSTOMFIELD1 N The merchant can configure any number of custom fields, which will be added to the transaction and returned to the receipt page. (See Note 2 below). CUSTOMFIELDN N Notes: 1. The MD5z hash is generated using the following as an input string: TERMINALID+ORDERID+AMOUNT+DATETIME+RECEIPTPAGEURL+VALIDATIONURL+SECRET If the RECEIPTPAGEURL or VALIDATIONURL parameters are not being sent, they should not be 18

19 included in the hash. When a terminal is setup to process more than one currency (Multi-currency) CURRENCY must be included in the hash. The three character currency code must be included after ORDERID and before AMOUNT, please refer to hash below (Also section 3.3) TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+RECEIPTPAGEURL+VALIDAT IONURL+secret) 2. 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. 3. 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. The following HTML shows the minimum required to initiate a transaction. <html> <body> <form action=" method="post"> <input type="hidden" name="terminalid" value=" " /> <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=" :10:43:01:673" /> <input type="hidden" name="hash" value="dd77fde79d1039d6b39e20d " /> <input type="submit" value="pay Now" /> </form> </body> <html> Utilize the Terminal Setup screen to define the URL where GlobalOne will send transaction processing results (Receipt Page URL field). The following fields are returned in the response, Field Name ORDERID APPROVALCODE RESPONSECODE RESPONSETEXT DATETIME Description The original order ID of the transaction. Six digit AuthCode. A or D or R(Approved or Declined or Referral). The text of the authorization. The time of the transaction created by the bank. Format: YYYY-MM- DDTHH:MM:SS. 19

20 AVSRESPONSE CVVRESPONSE UNIQUEREF PHONE COUNTRY CARDNUMBER HASH Any other field The result of the AVS check. See Appendix A for more information. The result of the CVV check. See Appendix A for more information. Generated reference that should be stored for tracking and remote XML refunding. If sent we will return this value. If sent we will return this value. If sent we will return this value. The card number (obfuscated) that was used for the transaction. An MD5 HASH. See Note1 below. Any other fields sent in the request; will be treated as a custom field. 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: 1. The MD5 HASH is generated using the following as an input string: TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+SECRET 2. Many code examples on how to generate an MD5 HASH can be found in the Internet. For assistance, please contact the GlobalOne integration team. 5.4 Hosted Pre-Auth Page The hosted Pre-Auth page allows for pre-authorization where the merchant account allows such requests. Approved pre-auth transactions must be flagged as completed using SelfCare system before they will be settled. Final transaction amount may 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: Note: Pre-auths don t go to an Auto Ready state. A pre-auth will always go into a READY state when completed via an XML. 5.5 Background Validation Background validation is a method of double-checking the result 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 20

21 redirect) can sometimes fail, leaving the site without a result for the transaction even though the transaction may have been authorized. 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. GlobalOne 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. GlobalOne will make further attempts to reach the validation URL; with this process repeating until the 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 a notification sent to the merchants address on file. Background Validation may be enabled through the SelfCare System in the Terminal Setup section. The following parameters are sent in the validation request: Field Name TERMINALID UNIQUEREF ORDERID RESPONSECODE RESPONSETEXT APPROVALCODE DATETIME AVSRESPONSE CVVRESPONSE HASH Custom Parameters Description Terminal Id. Generated reference that should be stored for tracking and remote XML refunding. Order ID supplied by merchant in request. A, D or R (Approved, Declined or Referral). Text describing transaction state. This will be populated with an error message if there was an issue during processing. Transaction approval code if transaction was authorized otherwise empty. Cardholder . Format: YYYY-MM-DDTHH:MM:SS. AVS response, available only when AVS is enabled for the terminal. See Appendix A CVV response, available only when CVV is enabled for the terminal. See Appendix A An MD5 HASH. See Note 1 below. Configured Terminal Custom Parameters. Notes: 1. The MD5 HASH is generated using the following as an input string: TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+SECRET 21

22 (For multi-currency Terminal IDs (see section 3.3 above) this should be: TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+secret) 5.6 Hosted Pages in iframe Format 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; however the implementation for the iframe is slightly different. There are two methods of implementing iframe: 1. Build and submit the form the same as the standard integration, but within the iframe. 2. Build the POST query string within the main page, creating an iframe with the string the SRC value. In either case the following parameter must be included: Field Name Value Description INIFRAME Y Ensures that all redirects performed by GlobalOne do not break out of the iframe. 5.7 SecureCard Storage via Hosted Payment Page The Hosted Payment Page can be configured to store the processed card as a SecureCard upon successful authorisation of the requested payment. This must be enabled by GlobalOne; if required please 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 22

23 48 chars. The following additional parameters will be sent to the Receipt Page URL: Field Name ISSTORED SCERROR MERCHANTREF CARDREFERENCE CARDTYPE CARDEXPIRY Description true or false Description of storage error if ISSTORED is false Original SecureCard Merchant Reference. Generated Card Reference. See section 3.2 above. Expiry date of the card. Notes: 1. The MD5 response HASH for Hosted Payment Page transactions where the card is stored is generated using the following as an input string: TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RE SPONSETEXT+MERCHANTREF+CARDREFERENCE+CARDTYPE+CARDNU MBER+CARDEXPIRY+secret 23

24 6 XML Payments Integration It is also possible to send XML directly to the GlobalOne 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: Test Credentials Sandbox Test Details The following values should be used when testing against the Pivotal test URLs. Please see the Testing and Certification guide for further details. The terminal details are: a. Currency Terminal ID Shared SECRET b. USD SandboxSecret001 c. CAD SandboxSecret002 d. EUR SandboxSecret003 e. GBP SandboxSecret004 f. MCP* SandboxSecret001 *MCP is the Multi Currency Terminal Settings Test Cards Test cards that may be used on our host are: DCC Card Scheme Currency Enabled Supports CVV Card Number American Express EUR N Y Debit MasterCard EUR Y Y Debit MasterCard GBP Y Y Debit MasterCard USD Y Y Diners EUR N N Diners USD N N JCB GBP N Y Maestro EUR Y Y Maestro GBP Y Y Maestro USD Y Y MasterCard EUR Y Y MasterCard GBP N Y MasterCard GBP Y Y MasterCard JPY Y Y MasterCard USD Y Y Switch EUR N N

25 Switch GBP N N Switch USD N N Visa Credit EUR N Y Visa Credit EUR Y Y Visa Credit GBP N Y Visa Credit GBP Y Y Visa Credit JPY N Y Visa Credit JPY Y Y Visa Credit USD N Y Visa Credit USD Y Y Visa Debit EUR N Y Visa Debit EUR Y Y Visa Debit GBP N Y Visa Debit GBP Y Y Visa Debit JPY N Y Visa Debit JPY Y Y Visa Debit USD N Y Visa Debit USD Y Y Visa Electron EUR Y Y Visa Electron GBP Y Y Visa Electron JPY Y Y Visa Electron USD Y Y All test cards can be used with any expiry date in the future, and any CVV (American Express cards have a 4 digit CVV) and any Issue number where appropriate. 6.2 MaxMind MinFraud (Where Available) Certain 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. More information about this service is available on the MaxMind website here: 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 read the MaxMind website linked above thoroughly before implementing this feature. 6.3 Request Types XML Payments The following is a simple example of a payment via an XML POST: 25

26 <?xml version="1.0" encoding="utf-8"?> <PAYMENT> <ORDERID> </ORDERID> <TERMINALID> </TERMINALID> <AMOUNT>10</AMOUNT> <DATETIME> :11:47:04:656</DATETIME> <CARDNUMBER> </CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>0807</CARDEXPIRY> <CARDHOLDERNAME>John Doe</CARDHOLDERNAME> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> <CURRENCY>EUR</CURRENCY> <TERMINALTYPE>1</TERMINALTYPE> <TRANSACTIONTYPE>7</TRANSACTIONTYPE> <CVV>214</CVV> </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> T12:53:18</DATETIME> <CVVRESPONSE>M</CVVRESPONSE> <HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH> </PAYMENTRESPONSE> Payment request field 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 GlobalOne. NB Please contact GlobalOne 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(MSR/CHP) 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. See Note 4 26

27 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. CARDHOLDERNAME N The name of the card holder required if TRACKDATA is not being sent and not using a SecureCard. HASH Y An MD5 HASH. See Note 1 & 2 below. CURRENCY Y A 3-character currency code of the transaction. ISO 4217 CURRENCY CODE FOREIGNCURRENCYINFOR MATION N TERMINALTYPE Y The type of the terminal: Tag contains Dynamic Currency Conversion information. It has to be present in the edcc-enabled transactions. Only available to edcc enabled merchants. TRANSACTIONTYPE Y 1 - MOTO (Mail Order/Telephone Order) 2 ecommerce 3 Cardholder Present 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 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 27

28 If sending XID & CAVV from non GlobalOne 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 (3D Secure not currently supported) 6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not participate in 3D Secure (3D Secure not currently supported). 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 GlobalOne 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. N Cardholders address. If populated the cardholder will be sent an receipt. The SelfCare Terminal Setup setting Disable Cardholder Receipt can override this. CVV N The security code entered by the cardholder. ADDRESS1 N The first address field for AVS. ADDRESS2 N The second address field for AVS. POSTCODE N The postal/zip code (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 GlobalOne Transaction Reference supplied in GlobalOne 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 alpha-2 code. Required for MaxMind MinFraud fraud scoring. IPADDRESS N Recommended inclusion. Required for MaxMind MinFraud 28

29 fraud scoring. SIGNATURE N Optional field if processing Cardholder Present (CHP) transaction using the TRACKDATA field. CUSTOMFIELD N Should also use the NAME xml attribute to assign the name of the custom field. See Note 3 below. 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 when not using our MPI. (3D secure not currently supported) MPIREF N 3D-Secure GlobalOne Transaction Reference supplied in GlobalOne 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. The following fields are returned in the response: Field Name UNIQUEREF RESPONSECODE RESPONSETEXT APPROVALCODE BANKRESPONSECODE AUTHORIZEDAMOUNT DATETIME AVSRESPONSE CVVRESPONSE Description Generated reference that should be stored for tracking and remote XML refunding. A or D or R (Approved or Declined or Referral). The text of the authorization. Six digit AuthCode. Only sent on TSYS terminals. The TSYS response code returned in the authorisation response. See Appendix C for response codes Only sent for specific acquirers. Partial amount authorized for some transactions. 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. The result of the AVS check. See Appendix A for more information. The result of the CVV check. See Appendix A for more information. 29

30 PROCESSINGTERMINAL HASH 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 An MD5 HASH. See Note2 below. Notes: 1. The MD5 HASH is generated using the following as an input string: a. TERMINALID+ORDERID+AMOUNT+DATETIME+secret b. (For multi-currency Terminal IDs (see section 3.3 above) this should be: TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+secret) 2. The MD5 HASH is generated using the following as an input string: a. TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+BAN KRESPONSECODE+secret For multi-currency Terminal IDs (see section 3.3 above) this should be: b. TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+RESPONSECODE+RESPONS ETEXT+BANKRESPONSECODE+secret) The DATETIME is the time returned by the bank for the transaction. Many code examples on how to generate an MD5 HASH can be found in the Internet. For assistance, please contact the GlobalOne integration team. 3. Custom Fields are configured in Terminal Settings to store details against a transaction. There can be a max of 30 custom fields 4. For card present transactions please add TRACKDATA information, you don t have to include credit card data it will be included in the TRACKDATA Error handling If there is an error processing the transaction, the error string is returned in an XML message with the simple: <ERROR><ERRORSTRING></ERRORSTRING></ERROR> tags. 30

31 6.3.2 Pre-Authorization Request Only certain acquiring banks support pre-authorization transactions Please check with the GlobalOne integration team if you wish to support Pre-authorizations. Example of a XML Pre-Auth request: <?xml version="1.0" encoding="utf-8"?> <PREAUTH> <ORDERID> </ORDERID> <TERMINALID> </TERMINALID> <AMOUNT>15.62</AMOUNT> <DATETIME> :09:24:16:105</DATETIME> <CARDNUMBER> </CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>1109</CARDEXPIRY> <CARDHOLDERNAME>John Doe</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> <UNIQUEREF>F523SJTZ0</UNIQUEREF> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>475318</APPROVALCODE> <DATETIME> T09:24:17</DATETIME> <CVVRESPONSE>M</CVVRESPONSE> <HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH> <PROCESSINGTERMINAL> </PROCESSINGTERMINAL> </PREAUTHRESPONSE> 31

32 Payment request fields description: Field Name Requi Description red ORDERID Y A unique identifier for the order created by the merchant. (Max 12 Characters). TERMINALID Y A Terminal ID provided by GlobalOne. NB Please contact GlobalOne to be issued with a test terminal ID. AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts. DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS. CARDNUMBER N The payment card number, 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. HASH Y An MD5 HASH. See Note 1 below. CURRENCY Y A 3 character currency code of the transaction. ISO 4217 Currency Code. FOREIGNCURRENCYINFORMA TION 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: TRANSACTIONTYPE Y Normally: 1 - MOTO (Mail Order/Telephone Order) 2 - ecommerce 4 - MOTO (Mail Order/Telephone Order) 7 ecommerce Recurring Payment Flagging: 32 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

33 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-globalone 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 N Cardholders address. If populated the cardholder will be sent an 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 The first address field for AVS. ADDRESS2 N The second address field for AVS. 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 scoring. See MaxMind definition of this field as it is forwarded to them without modification. 33

34 COUNTRY N ISO 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. CUSTOMFIELD N Should also use the NAME xml attribute to assign the name of the custom field. See Note 3 in PAYMEN T section. RECURRINGTXNREF N Should be set to the value of a UNIQUEREF returned in a PAYMENT response for a non-recurring transaction on a matching card. TRANSACTIONTYPE should be set to 2. The following fields are returned in the response: Field Name UNIQUEREF RESPONSECODE RESPONSETEXT BANKRESPONSECODE APPROVALCODE DATETIME AVSRESPONSE CVVRESPONSE PROCESSINGTERMINAL HASH Description Generated reference that should be stored for tracking and remote XML refunding. A or D or R (Approved or Declined or Referral). The text of the authorization. Only sent on TSYS terminals. The TSYS response code returned in the authorisation response. See Appendix C for response codes Six digit AuthCode. 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. The result of the AVS check. See Appendix A for more information. The result of the CVV check. See Appendix A for more information. 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. An MD5 HASH. See Note2 below. Notes: 1. The MD5 HASH is generated using the following as an input string: TERMINALID+ORDERID+AMOUNT+DATETIME+secret (For multi-currency Terminal IDs this should be: TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+secret) 2. The MD5 HASH is generated using the following as an input string: 34

35 TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+BANKRE SPONSECODE+secret (For multi-currency Terminal IDs) this should be: TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+s ecret) The DATETIME is the time returned by the bank for the transaction. Many code examples on how to generate an MD5 HASH can be found in the Internet. For assistance, please contact GlobalOne. Errors handling If there is an error processing the transaction, the error string is returned in an XML message with the simple tags: <ERROR><ERRORSTRING></ERRORSTRING></ERROR> Pre-Auth Completion Request Example of a Pre-Auth completion request: <?xml version="1.0" encoding="utf-8"?> <PREAUTHCOMPLETION> <UNIQUEREF>JJCVGCTOV3</UNIQUEREF> <TERMINALID> </TERMINALID> <AMOUNT>12.31</AMOUNT> <DATETIME> :14:47:51:307</DATETIME> <CVV>785</CVV> <HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH> </PREAUTHCOMPLETION> For testing, this XML is posted to: 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> T14:47:51</DATETIME> 35