For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Card Storage

See the full range of request types and field values for this solution

In this API reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on Card Storage, see our main article.

Authorization

Once you have the card stored you can easily raise an authorization against it. In the place of collected card data you simply send the customer token (Payer) and card (Payment Method) reference, we obtain the securely stored card data from our vault and builds an authorization which we then send on to the Issuer.

Under PCI Compliance rules the security code (CVN, CVV) cannot be stored. However if in your application or website you are providing the customer the option of using a stored card, you can prompt them for their security code again and include this in the request.

To understand how to utilize Credential on File functionality in relation to this request type, see the API Reference for Credential on File.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="receipt-in" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>AiCibJ5UR7utURy_slxhJw</orderid>
  <foreignretailer flag="false"/>
  <amount currency="EUR">1001</amount>
  <autosettle flag="1"/>
  <payerref>03e28f0e-492e-80bd-20ec318e9334</payerref>
  <paymentmethod>3c4af936-483e-a393-f558bec2fb2a</paymentmethod>
  <paymentdata>
    <cvn>
      <number>123</number>
    </cvn>
  </paymentdata>
  <sha1hash>f0b45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Channel	string	enum	O		Specify how a transaction is to be processed. Compatible with us and certain other acquirers. Allowed values: ECOM - Ecommerce MOTO - Mail Order/Telephone Order
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Amount	integer		M	1-11	The amount should be in the smallest unit of the required currency. For example: 2000 = €20.00
Currency	string	ISO 4217	M	3	The processing currency of the transaction. Please see the list of Currency Codes.
AutoSettle/AutoCapture Flag	string	enum	M		Used to specify the settlement/capture type. Allowed values: 0 - Delayed Settle (Capture) / Authorize, don't automatically add to the settlement file. 1 - Auto Settle (Capture) / Charge, automatically added to the next settlement file. MULTI - Multi Settle (Capture), don't automatically add to the settlement file. Enables multiple settlement/capture requests up to 115% of the original transaction value.
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
Security Code Number	string	numeric	O	0-4	The 3 digit number on the reverse of the card (known as CVC for Visa and CVV2 for MasterCard). For American Express the code is 4 digits long.
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <authcode>12345</authcode>
  <result>00</result>
  <cvnresult>M</cvnresult>
  <avspostcoderesponse>M</avspostcoderesponse>
  <avsaddressresponse>M</avsaddressresponse>
  <batchid>319623</batchid>
  <message>[ test system ] AUTHORISED</message>
  <pasref>14610544313177922</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <srd>MMC0F00YE4000000715</srd>
  <cardissuer>
    <bank>AIB BANK</bank>
    <country>IRELAND</country>
    <countrycode>IE</countrycode>
    <region>EUR</region>
  </cardissuer>
  <sha1hash>8f4dfe7460ce91f78a144a2ed4f334617feaaab4</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
CVN Result	string	enum	The result of the Security Code (CVN, CVV) check: M - Matched N - Not Matched I - Not checked due to circumstances U - Not checked - issuer not certified P - Not Processed
AVS Postcode Response	string	enum	The result of the Address Verification Service (AVS) check on the postcode and first line of the billing address: M - Matched N - Not Matched I - Problem with check U - Unable to check - Issuer not certified, for example P - Partial Match Available for US, CA and GB cardholders only.
AVS Address Response	string	enum	See AVS Postcode Response
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Time Taken	integer		The total time taken to process the request in seconds.
Auth Time Taken	integer		The total time taken by the Acquirer to process the request in seconds.
Bank	string	alphanumeric

Validate (OTB)

This request type is supported by us. However, it is not supported by all acquirers. Please contact your account manager for more information.

Sample request

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<request type='receipt-in-otb' timestamp='20190723133011'>
    <merchantid>MerchantId</merchantid>
    <account>internet</account>
    <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
    <foreignretailer flag="false"/>
    <payerref>03e28f0e-4cf0-492e-80bd-20ec318e9334</payerref>
    <paymentmethod>3c4af936-3732-483e-a393-f558bec2fb2a</paymentmethod>
    <paymentdata>
        <cvn>
            <number>123</number>
        </cvn>
    </paymentdata>
    <comments>
        <comment id='1'>Verification Only</comment>
        <comment id='2'>Mobile Channel</comment>
    </comments>
    <sha1hash>20ebb67e527a9ae01c4b17d55becdefe19300978</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Channel	string	enum	O		Specify how a transaction is to be processed. Compatible with us and certain other acquirers. Allowed values: ECOM - Ecommerce MOTO - Mail Order/Telephone Order
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
Security Code Number	string	numeric	O	0-4	The 3 digit number on the reverse of the card (known as CVC for Visa and CVV2 for MasterCard). For American Express the code is 4 digits long.
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <authcode>12345</authcode>
  <result>00</result>
  <cvnresult>M</cvnresult>
  <avspostcoderesponse>M</avspostcoderesponse>
  <avsaddressresponse>M</avsaddressresponse>
  <batchid>319623</batchid>
  <message>[ test system ] AUTHORISED</message>
  <pasref>14610544313177922</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <srd>MMC0F00YE4000000715</srd>
  <cardissuer>
    <bank>AIB BANK</bank>
    <country>IRELAND</country>
    <countrycode>IE</countrycode>
    <region>EUR</region>
  </cardissuer>
  <sha1hash>8f4dfe7460ce91f78a144a2ed4f334617feaaab4</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
CVN Result	string	enum	The result of the Security Code (CVN, CVV) check: M - Matched N - Not Matched I - Not checked due to circumstances U - Not checked - issuer not certified P - Not Processed
AVS Postcode Response	string	enum	The result of the Address Verification Service (AVS) check on the postcode and first line of the billing address: M - Matched N - Not Matched I - Problem with check U - Unable to check - Issuer not certified, for example P - Partial Match Available for US, CA and GB cardholders only.
AVS Address Response	string	enum	See AVS Postcode Response
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Time Taken	integer		The total time taken to process the request in seconds.
Auth Time Taken	integer		The total time taken by the Acquirer to process the request in seconds.
Bank	string	alphanumeric

Credit a Card

For security reasons this request type is not enabled by default. It must be requested by one of the main contacts on the account. The request type cannot be executed using archived Payers.

This request type allows you to credit an amount to a stored card. To process this request you must supply the Refund Password, which you can set with a member of our support team (this is a different password than the Rebate Password). This password must be hashed using the SHA-1 algorithm before being added to the request. Credits requests are not sent on to the Issuer, they are placed directly into the next day's settlement file.

Sample request

<?xml version='1.0' encoding='UTF-8'?>
<request type='payment-out' timestamp='20180821100546'>
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>Xh9cavLrTqK32lT97AeVIw</orderid>
  <amount currency='EUR'>1001</amount>
  <payerref>03e28f0e-492e-80bd-20ec318e9334</payerref>
  <paymentmethod>3c4af936-3732-a393-f558bec2fb2a</paymentmethod>
  <comments>
    <comment id='1'>Returned item</comment>
    <comment id='2'>Break in transit</comment>
  </comments>
  <refundhash>a51118f58785274e117efe1bf99d4d50ccb96949</refundhash>
  <sha1hash>f0a45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Channel	string	enum	O		Specify how a transaction is to be processed. Compatible with us and certain other acquirers. Allowed values: ECOM - Ecommerce MOTO - Mail Order/Telephone Order
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Amount	integer		M	1-11	The amount should be in the smallest unit of the required currency. For example: 2000 = €20.00
Currency	string	ISO 4217	M	3	The processing currency of the transaction. Please see the list of Currency Codes.
AutoSettle/AutoCapture Flag	string	enum	M		Used to specify the settlement/capture type. Allowed values: 0 - Delayed Settle (Capture) / Authorize, don't automatically add to the settlement file. 1 - Auto Settle (Capture) / Charge, automatically added to the next settlement file. MULTI - Multi Settle (Capture), don't automatically add to the settlement file. Enables multiple settlement/capture requests up to 115% of the original transaction value.
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>klmnjrTQRpaseGCzKCYCpQ</orderid>
  <authcode>005056</authcode>
  <result>00</result>
  <cvnresult>U</cvnresult>
  <avspostcoderesponse>U</avspostcoderesponse>
  <avsaddressresponse>U</avsaddressresponse>
  <batchid>319623</batchid>
  <message>REFUND ACCEPTED</message>
  <pasref>14610630569586471</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>1</authtimetaken>
  <cardissuer>
    <bank>AIB BANK</bank>
    <country>IRELAND</country>
    <countrycode>IE</countrycode>
    <region>EUR</region>
  </cardissuer>
  <sha1hash>57e526abbebe6a721c2aab2271d42e9d4dba9f33</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
CVN Result	string	enum	The result of the Security Code (CVN, CVV) check: M - Matched N - Not Matched I - Not checked due to circumstances U - Not checked - issuer not certified P - Not Processed
AVS Postcode Response	string	enum	The result of the Address Verification Service (AVS) check on the postcode and first line of the billing address: M - Matched N - Not Matched I - Problem with check U - Unable to check - Issuer not certified, for example P - Partial Match Available for US, CA and GB cardholders only.
AVS Address Response	string	enum	See AVS Postcode Response
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Time Taken	integer		The total time taken to process the request in seconds.
Auth Time Taken	integer		The total time taken by the Acquirer to process the request in seconds.
Bank	string	alphanumeric

Create a customer

To store a card, the first thing we need to do is set up a customer reference (Payer). You can also choose to store address and contact details alongside it.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payer-new" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <payer ref="0f357b45-9aa4-4453-a685-c69232e9024f" type="Retail">
    <title>Mr.</title>
    <firstname>James</firstname>
    <surname>Mason</surname>
    <company>Global Payments</company>
    <address>
      <line1>Flat 123</line1>
      <line2>House 456</line2>
      <line3>The Cul-De-Sac</line3>
      <city>Halifax</city>
      <county>West Yorkshire</county>
      <postcode>W6 9HR</postcode>
      <country code="GB">United Kingdom</country>
    </address>
    <phonenumbers>
      <home>+35312345678</home>
      <work>+3531987654321</work>
      <fax>+124546871258</fax>
      <mobile>+25544778544</mobile>
    </phonenumbers>
    <email>text@example.com</email>
    <dateofbirth>19851222</dateofbirth>
    <state>Yorkshire and the Humber</state>
    <passphrase>montgomery</passphrase>
    <vatnumber>GB 123456789</vatnumber>
    <varref>Car Part HV</varref>
    <custnum>E8953893489</custnum>
  </payer>
  <sha1hash>8d7e42bba0d9f6ca81f6106bfd74d2911fad888b</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Title	string	alphanumeric	O	0-10	Title of the customer.
First Name	string	alphanumeric	O	0-30	First name of the customer.
Surname	string	alphanumeric	O	0-50	Surname of the customer.
Company	string	alphanumeric	O	0-50	Company of the customer.
Line 1	string	alphanumeric	O	0-50	Line 1 of the customer address.
Line 2	string	alphanumeric	O	0-50	Line 2 of the customer address.
Line 3	string	alphanumeric	O	0-50	Line 3 of the customer address.
City	string	alphanumeric	O	0-50	City of the customer address.
County	string	alphanumeric	O	0-50	County of the customer address.
Postcode	string	alphanumeric	O	0-20	Postcode of the customer address.

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Batch Id	integer		The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests.
Time Taken	integer		The total time taken to process the request in seconds.
Processing Time Taken	integer		The total time taken to process the request in seconds.
Sha1hash	string	alphanumeric	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Edit a customer

Once a customer has been created you can update their name, address or contact details which can be viewed in Ecommerce Portal.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payer-edit" timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <payer ref="0f357b45-9aa4-4453-a685-c69232e9024f" type="Subscriber">
    <title>Sir</title>
    <firstname>Philip</firstname>
    <surname>Marlowe</surname>
    <company>Pinkerton</company>
    <address>
      <line1>Flat 456</line1>
      <line2>House 321</line2>
      <line3>Basement Flat</line3>
      <city>Chicago</city>
      <county>DuPage County</county>
      <postcode>50001</postcode>
      <country code="US">United States</country>
    </address>
    <phonenumbers>
      <home>+0013538547854</home>
      <work>+0013535611177</work>
      <fax>+001412459498488</fax>
      <mobile>+0012554457774</mobile>
    </phonenumbers>
    <email>test123@example.com</email>
    <dateofbirth>19740517</dateofbirth>
    <state>IL</state>
    <passphrase>Babette</passphrase>
    <vatnumber>EU826010755</vatnumber>
    <varref>REF1447741</varref>
    <custnum>E473637626</custnum>
    <comments>
      <comment id="1">New Subscription</comment>
      <comment id="2">Detective Magazine</comment>
    </comments>
  </payer>
  <sha1hash>8d7e42bba0d9f6ca81f6106bfd74d2911fad888b</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Title	string	alphanumeric	O	0-10	Title of the customer.
First Name	string	alphanumeric	O	0-30	First name of the customer.
Surname	string	alphanumeric	O	0-50	Surname of the customer.
Company	string	alphanumeric	O	0-50	Company of the customer.
Line 1	string	alphanumeric	O	0-50	Line 1 of the customer address.
Line 2	string	alphanumeric	O	0-50	Line 2 of the customer address.
Line 3	string	alphanumeric	O	0-50	Line 3 of the customer address.
City	string	alphanumeric	O	0-50	City of the customer address.
County	string	alphanumeric	O	0-50	County of the customer address.
Postcode	string	alphanumeric	O	0-20	Postcode of the customer address.

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Batch Id	integer		The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests.
Time Taken	integer		The total time taken to process the request in seconds.
Processing Time Taken	integer		The total time taken to process the request in seconds.
Sha1hash	string	alphanumeric	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Store a card

Once we have our customer entity created, we can now add cards to it. This request must contain the card data to be stored, a unique reference for it and the customer reference it is to be added to. We'd always recommend processing an authorization against a card or validating it (OTB) before adding it.

Sample request

Addresses stored against customer/card tokens are not used for AVS. Should AVS be required, integrators need to add the address to the payment request as outlined in AVS.

<?xml version="1.0" encoding="UTF-8"?>
<request type="card-new" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>F-2knQ0iShKK6ezfaSLh2Q</orderid>
  <card>
    <ref>10c6a2c7-be7b-a13f-12638937a012</ref>
    <payerref>0f357b45-9aa4-4453-a685-c69232e9024f</payerref>
    <number>4263970000005262</number>
    <expdate>0519</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
  </card>
  <storedcredential>
    <srd>MCCDX3FTU0212</srd>
   </storedcredential>
  <sha1hash>85fbaf68bb0e4fccd634facf6592b0677489709e</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Payment Reference	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Card Number	string	numeric	M	12-19	The full Primary Account Number (PAN) of the card.
Expiry Date	string	MMYY	M	4	The expiry date of the card.
Cardholder Name	string	alphanumeric	M	1-100	The cardholder name.
Card Type	string	enum	M	0-15	Please see the list of supported Card Type Strings.
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Batch Id	integer		The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests.
Time Taken	integer		The total time taken to process the request in seconds.
Processing Time Taken	integer		The total time taken to process the request in seconds.
Sha1hash	string	alphanumeric	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Edit a card

If your customer's card details change, for example if the expiry date is updated or they get a new card number, you can update the reference in Card Storage using this request. You can update all the card details at once or just the individual bits of data, for example just the expiry date. In the example below we are completely replacing the card with a new one.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="card-update-card" timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account> 
  <orderid>PNjvzlWpS4WWv4V6yPoEuw</orderid>
  <card>
    <ref>3c4af936-3732-f558bec2fb2a</ref>
    <payerref>03e28f0e-40-492e-20ec318e9334</payerref>
    <number>5425230000004415</number>
    <expdate>1020</expdate>
    <chname>Philip Marlowe</chname>
    <type>MC</type>
  </card>
  <storedcredential>
    <srd>MCCDX3FTU0212</srd>
  </storedcredential>
  <sha1hash>403b6d13bf2bfb4e69cac96096a6cd7a44436b29</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Currency	string	ISO 4217	M	3	The processing currency of the transaction. Please see the list of Currency Codes.
Card Number	string	numeric	M	12-19	The full Primary Account Number (PAN) of the card.
Expiry Date	string	MMYY	M	4	The expiry date of the card.
Cardholder Name	string	alphanumeric	M	1-100	The cardholder name.
Card Type	string	enum	M	0-15	Please see the list of supported Card Type Strings.
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Batch Id	integer		The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests.
Time Taken	integer		The total time taken to process the request in seconds.
Processing Time Taken	integer		The total time taken to process the request in seconds.
Sha1hash	string	alphanumeric	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Delete a card

If you want to remove a card from Card Storage you can send us a Card Delete request.

There is no ability to UNDO this action so please use with caution.

Sample request

<?xml version='1.0' encoding='UTF-8'?>
<request type='card-cancel-card' timestamp='20180821100546'>
  <merchantid>Merchant ID</merchantid>
  <account>internet</account>
  <orderid>V8-JEKaJSPqN28vCs91Gxw</orderid>
  <card>
    <ref>3c4af936-3732-f558bec2fb2a</ref>
    <payerref>03e28f0e-40-492e-20ec318e9334</payerref>
  </card>
  <comments>
    <comment id='1'>Subscription Expiry</comment>
    <comment id='2'>Customer panel</comment>
  </comments>
  <sha1hash>6bd2521179a61b721e4becc7afd076f6bfd24d46</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Authcode	string	alphanumeric	The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣]
Batch Id	integer		The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests.
Time Taken	integer		The total time taken to process the request in seconds.
Processing Time Taken	integer		The total time taken to process the request in seconds.
Sha1hash	string	alphanumeric	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

3DS2 - Check Version

To start the 3D Secure authentication process, the first step is to check the version that the card supports. To carry out authentication on a stored card rather than a full PAN is listed below. We maintain an up-to-date database of BIN ranges and the versions of 3D Secure they support.

If the card is enrolled in 3D Secure 2, the exact version will be returned (2.x.x) along with the necessary URL to facilitate the gathering of device data by the Issuer ACS (if supported). If the card is not enrolled, just the Server Transaction ID will be returned.

Sample request

curl https://api.sandbox.globalpay-ecommerce.com/3ds2/protocol-versions
-H "Content-type: application/json"
-H "Authorization: securehash fb2c8058ce4d03bd66e610fce8a476db722b0f9a" 
-X POST 
-d '{
  "request_timestamp": "2019-04-26T10:16:10.154248",
  "merchant_id": "MerchantId",
  "account_id": "internet",
  "payer_reference": "e193c21a-ce64-4820-b5b6-8f46715de931",
  "payment_method_reference": "10c3e089-fa98-4352-bc4e-4b37f7dcf108",
  "method_notification_url": "https://www.example.com/dsNotificationUrl"
}'

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
Method Notification URL	string	URL	M	1-256	The URL that will receive the Method Completion message. European merchants: mandatory for SCA.

3DS2 - Authentication

Assuming you have already gathered the relevant device data and (conditionally) the ACS Method URL process is complete, your application can now kick-off 3D Secure 2 authentication. We’ve outlined below the required and recommended data to be sent to the authentication endpoint. This includes the billing and shipping details of the customer, at least one phone number, the device data and the transaction details (amount, currency and so on).

You must also include your application’s Challenge Notification URL, a flag indicating the outcome from the ACS Method URL (or whether it took place at all) and a link to an About or Contact page on your website with customer care information.

Sample request (mandatory and recommended fields)

In this example, we’re only passing mandatory fields along with some recommended ones. The more optional fields you send and data you supply, the more likely the authentication for the transaction will be frictionless. For the full list of optional fields and the allowed values in each, see the API Reference for 3D Secure 2.

curl https://api.sandbox.globalpay-ecommerce.com/3ds2/authentications
-H "Content-type: application/json"
-H "Authorization: securehash cdf7f92bb0d80d20ba73034ee7ad2dada9d91825" 
-X POST 
-d '{
  "request_timestamp": "2019-04-26T10:19:32.552327",
  "authentication_source": "BROWSER",
  "authentication_request_type": "PAYMENT_TRANSACTION",
  "message_category": "PAYMENT_AUTHENTICATION",
  "challenge_request_indicator":"NO_PREFERENCE",
  "server_trans_id": "af65c369-59b9-4f8d-b2f6-7d7d5f5c69d5",
  "merchant_id": "MerchantId",
  "account_id": "internet",
  "card_detail": {
   "payer_reference": "e193c21a-ce64-4820-b5b6-8f46715de931",
   "payment_method_reference": "10c3e089-fa98-4352-bc4e-4b37f7dcf108"
  },
  "order": {
    "amount": "1001",
    "currency": "USD",
    "id": "3400dd37-101d-4940-be15-3c963b6109b3",
    "address_match_indicator": false,
    "shipping_address": {
      "line1": "Apartment 852",
      "line2": "Complex 741",
      "line3": "House 963",
      "city": "Chicago",
      "postal_code": "50001",
      "state": "IL",
      "country": "840"
    }
  },
  "payer": {
    "email": "james.mason@example.com",
    "billing_address": {
      "line1": "Flat 456",
      "line2": "House 456",
      "line3": "Unit 4",
      "city": "Halifax",
      "postal_code": "W5 9HR",
      "country": "826"
    },
    "mobile_phone": {
      "country_code": "44",
      "subscriber_number": "7123456789"
    }
  },
  "challenge_notification_url": "https://www.example.com/challengeNotificationUrl",
  "method_url_completion": "YES",
  "browser_data": {
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "color_depth": "TWENTY_FOUR_BITS",
    "ip": "123.123.123.123",
    "java_enabled": "true",
    "javascript_enabled": "true",
    "language": "en-US",
    "screen_height": "1080",
    "screen_width": "1920",
    "challenge_window_size": "FULL_SCREEN",
    "timezone": "0",
    "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36"
  },
  "merchant_contact_url": "https://www.example.com/about"
}'

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	timestamp	numeric	M	24-32	The timestamp of the request. Minimum of 3 microseconds precision, can be up to 6. Format: yyyy-MM-ddTHH:mm:ss.SSS
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Reference	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
Message Category	string	enum	M	N/A	Indicates the type of channel used to initiate the transaction. Allowed Values: PAYMENT_AUTHENTICATION NON_PAYMENT_AUTHENTICATION - non-payment activity such as adding or maintaining cards or card verification (OTB). European merchants: required for SCA.
Challenge Request Indicator	string	enum	O	N/A	Indicates whether a challenge is requested for this transaction. The Issuer may override whatever preference is specified in this field. Allowed values: NO_PREFERENCE - No preference as to whether the customer is challenged NO_CHALLENGE_REQUESTED - Preference is for the customer not to be challenged. CHALLENGE_PREFERRED - Preference is for the customer to be challenged. CHALLENGE_MANDATED - A challenge is required for the transaction to be authorized due to local/regional mandates or other variables. NO_CHALLENGE_REQUESTED_TRANSACTION_RISK_ANALYSIS_PERFORMED NO_CHALLENGE_REQUESTED_DATA_SHARE_ONLY NO_CHALLENGE_REQUESTED_SCA_ALREADY_PERFORMED NO_CHALLENGE_REQUESTED_WHITELIST CHALLENGE_REQUESTED_PROMPT_FOR_WHITELIST European merchants: optional for SCA.

3DS2 - Authorization

If you are processing the payment with us, now that the 3D Secure process is complete, and depending on the ECI value returned, we can proceed to authorization while including the authentication data. The transaction will be processed as normal and may be successful or declined based on standard criteria; sufficient funds, correct security code entered and so on.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="receipt-in" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>AiCibJ5UR7utURy_slxhJw</orderid>
  <amount currency="EUR">1001</amount>
  <autosettle flag="1"/>
  <payerref>03e28f0e-492e-80bd-20ec318e9334</payerref>
  <paymentmethod>3c4af936-483e-a393-f558bec2fb2a</paymentmethod>
  <paymentdata>
    <cvn>
      <number>123</number>
    </cvn>
  </paymentdata>
  <mpi>
    <eci>5</eci>
    <ds_trans_id>c272b04f-6e7b-43a2-bb78-90f4fb94aa25</ds_trans_id>
    <authentication_value>ODQzNjgwNjU0ZjM3N2JmYTg0NTM=</authentication_value>
    <message_version>2.1.0</message_version>
  </mpi>
  <sha1hash>f0b45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Channel	string	enum	O		Specify how a transaction is to be processed. Compatible with us and certain other acquirers. Allowed values: ECOM - Ecommerce MOTO - Mail Order/Telephone Order
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Amount	integer		M	1-11	The amount should be in the smallest unit of the required currency. For example: 2000 = €20.00
Currency	string	ISO 4217	M	3	The processing currency of the transaction. Please see the list of Currency Codes.
AutoSettle/AutoCapture Flag	string	enum	M		Used to specify the settlement/capture type. Allowed values: 0 - Delayed Settle (Capture) / Authorize, don't automatically add to the settlement file. 1 - Auto Settle (Capture) / Charge, automatically added to the next settlement file. MULTI - Multi Settle (Capture), don't automatically add to the settlement file. Enables multiple settlement/capture requests up to 115% of the original transaction value.
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]

Dynamic Currency Conversion

Use this request to initiate the DCC (Dynamic Currency Conversion) process and determine if there is a currency conversion opportunity with a stored card.

The Order ID used in this request must also be used in the subsequent Authorization.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="realvault-dccrate" timestamp="20180731152924">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>4OBdkOuZRPCXarMcaU7ywQ</orderid>
  <amount currency="EUR">1001</amount>
  <payerref>03e28f0e-4cf0-80-20ec318e9334</payerref>
  <paymentmethod>3c4af936-483ea33-f558bec2fb2a</paymentmethod>
  <dccinfo>
    <ccp>Currency Conversion Processor</ccp>
    <type>1</type>
  </dccinfo>
  <sha1hash>30596f1d07084d533547c3cbf860d5b24f7034a5</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Currency	string	ISO 4217	M	3	The processing currency of the transaction. Please see the list of Currency Codes.
Payer Reference	string	alphanumeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
Payment Method	string	alphanumeric	M	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
CCP	string	enum	M		The name of the Currency Conversion Processor (CCP) the request is to be sent to. Allowed values: FEXCO EUROCONEX
Type	integer		M		The type of Conversion. Should always be set to 1.
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Sample response

<response timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>HUrD-jsFSniaul_g0_z4YA</orderid>
  <authcode/>
  <result>00</result>
  <message>Success</message>
  <pasref>14622680939731425</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <cardissuer>
    <bank>ING BANK (AUSTRALIA) LIMITED</bank>
    <country>AUSTRALIA</country>
    <countrycode>AU</countrycode>
    <region>A/P</region>
  </cardissuer>
  <dccinfo>
    <cardholdercurrency>AUD</cardholdercurrency>
    <cardholderamount>1674</cardholderamount>
    <cardholderrate>1.6728</cardholderrate>
    <merchantcurrency>EUR</merchantcurrency>
    <merchantamount>1001</merchantamount>
    <marginratepercentage>03.0000</marginratepercentage>
    <exchangeratesourcename>Reuters Wholesale Interbank</exchangeratesourcename>
    <commissionpercentage>00.0000</commissionpercentage>
    <exchangeratesourcetimestamp>20180802 13:13</exchangeratesourcetimestamp>
  </dccinfo>
  <sha1hash>118b9d2dc037dfa5525dbaf409e828c51c2016e7</sha1hash>
</response>

Response syntax

Element/Field	Category	Format	Description
Timestamp	string	numeric	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Order Id	string	alphanumeric	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Result	string	numeric	The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes.
CVN Result	string	enum	The result of the Security Code (CVN, CVV) check: M - Matched N - Not Matched I - Not checked due to circumstances U - Not checked - issuer not certified P - Not Processed
Message	string	alphanumeric	Text of the response from the Gateway, Acquirer, Issuer or Payment Method.
Payments Reference	string	alphanumeric	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Time Taken	integer		The total time taken to process the request in seconds.
Auth Time Taken	integer		The total time taken by the Acquirer to process the request in seconds.
Bank	string	alphanumeric	The name of the card Issuer.
Country	string	alphanumeric	The country of the card Issuer.
Country Code	string	alphanumeric	Country code of the card Issuer.
Region	string	enum	The region the card was issued in: MEA - Middle East/Asia LAT - Latin America US - United States EUR - Europe CAN - Canada A/P - Asia/Pacific
Cardholder Currency

Credential on File

Various data elements need to be passed for merchants to manage their own implementation of Credential on File (COF) and Merchant Initiated Transactions (MITs) using our API solution.

For a full description of COF fields and use cases, see our main Credential on File article.

If you're using our Card Storage solution for one-off and recurring transactions, if the first transaction is flagged correctly, we will automatically manage COF, MIT, and Transaction Grandfathering for all subsequent transactions. COF and MIT can be used in the Authorization, Validation (Open-to-Buy/OTB), Charge a Stored Card (Receipt-in), and Validate a Stored Card (Receipt-In-OTB) request types.

For any payment types — regardless of whether you're using our solution or a third-party's or are storing card details yourself — you can manage all of the messaging yourself. To see how to do this, see the example below.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180613141207">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">1001</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>0425</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <!-- Begin CoF Fields -->
  <storedcredential>
	<type>oneoff</type>
	<initiator>cardholder</initiator>
	<sequence>first</sequence>
	<srd></srd>
  </storedcredential>
  <!-- End CoF Fields -->
  <sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
type	string	enum	C	N/A	The conditions of the payment under which the stored card details are being used. Allowed values: oneoff - payment is unscheduled and not part of a prearranged plan. installment - payment is part of a pre-arranged installment plan. recurring - payment is being processed for an undefined period. Must be included if the stored credential element is included in the request.
initiator	string	enum	C	N/A	Whether the payment was initiated by the customer or the merchant. Allowed values: cardholder - customer is actively participating in the payment. merchant - merchant initiates a payment request where the customer is aware, but does not actively participate in the payment. scheduled - merchant and customer agree to a payment plan. The payment is initiated by the merchant. Must be included if the stored credential element is included in the request.
sequence	string	enum	C	N/A	Where in the sequence of transactions the payment appears. Allowed values: first - this is the first time the card details are being used to facilitate a payment between the customer and the merchant. This must only be used in transactions where COF initiator is set to cardholder. subsequent - the request is for payment is using previously stored card details. Must be included if the stored credential element is included in the request.
Scheme Reference Data	string	enum	C	30	This is the Scheme ID provided by Visa and Mastercard. Provides a link to the payment history between a customer and a merchant.

Generate hash

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the tag instead of the tag. For more information, contact our support team.

Build the request hash

Use the tabs below to follow the steps for a certain request type: Authorization, Validate (OTB), Credit, Create a Customer, Edit a Customer, Store a Card, Edit a Card, Delete a Card, 3DS2 - Check Version, 3DS2 - Authentication, 3DS2 - Authorization, or Dynamic Currency Conversion.

Check hash

Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the Response hash

Use the tabs below to follow the steps for a certain request type: Authorization, Validate (OTB), Credit, Create a Customer, Edit a Customer, Store a Card, Edit a Card, Delete a Card, 3DS1 - Verify Enrollment or Dynamic Currency Conversion. After making a selection, the steps on how to check the response hash for that type are provided.

1. Create a SHA-1 hash made up of request values

The blueprint of the hash for this request is:

"timestamp.merchantid.orderid.amount.currency.payerref"

Based on the XML example above our initial string will be:

"20200414103508.Merchant ID.AiCibJ5UR7utURy_slxhJw.1001.EUR.03e28f0e-492e-80bd-20ec318e9334"

2. Concatenate the hashed string with your Shared Secret

After step 1, you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret, for example:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

3. SHA-1 hash the concatenated string

Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269

1. Create a SHA-1 hash made up of response values

The blueprint of the hash for this response is:

"timestamp.merchantid.orderid.result.message.pasref.authcode"

So, based on the above example, the initial string to check the hash of the response will be:

"20200204155942.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.[ test system ] Authorised.14631546336115597.12345"

2. Concatenate the hashed string with your Shared Secret

After step 1, you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret, for example:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

3. SHA-1 hash the concatenated string

Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269

We create the hash in the same way on our side and send it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha1hash element.