Paythru Gateway API

Version 3

Back to Developers

Paythru Gateway API

Version 3

1.0 Introduction

Paythru is a service provider offering a range of services to merchants enabling them to accept payments for goods and services within websites and mobile applications. The range of services includes a variety of different payment types as well as number of APIs offering the merchant a choice of integration options.

The integration options include both 'direct' methods where Paythru simply process payment details captured and submitted by the merchant as well as 'hosted' methods where Paythru host the customer facing interface and process the details provided by the customer.

This API is intended for merchants who wish to host the customer's entire payment experience themselves and simply forward the payment details to Paythru for processing. The API is a web service that accepts requests directly from the merchant's servers, and returns the result of the process within the response. Methods are available to conduct new Auth and PreAuth transactions using cards, card tokens and card details submitted to Paythru Client POST sessions. Merchants wishing to process new transactions using cards will be required to produce evidence of their PCI DSS compliance certification.

Below is a summary of activities supported by this API:

  • Conducting an Auth transaction with a credit or debit card
  • Conducting an Auth transaction with a card key*
  • Conducting an Auth transaction with a session key**
  • Conducting an PreAuth transaction with a credit or debit card
  • Conducting an PreAuth transaction with a card key*
  • Conducting an PreAuth transaction with a session key**
  • Capturing the funds reserved in a previous PreAuth transaction (release funds to the merchant)
  • Cancelling a previous PreAuth transaction (release funds to the cardholder)
  • Initiating a 3-D Secure transaction with credit or debit card
  • Initiating a 3-D Secure transaction with card key*
  • Initiating a 3-D Secure transaction with session key**
  • Returning the status of a 3-D Secure authentication
  • Authorising a 3-D Secure transaction
  • PreAuthorising a 3-D Secure transaction
  • Refunding a previous transaction
  • Returning the details of a transaction
  • Updating transaction data

* Card key generated using Paythru Card Tokenisation API

** Session key returned using Paythru Client POST API

1.1 Scope

This document describes the web services available to merchants wishing to conduct payments on behalf of their customers.

1.2 Audience

This document is aimed largely at developers tasked with integrating with Paythru on behalf of a merchant. This document is technical in nature and only offers a high level view of Paythru's business processes. Readers who are to implement the API should have a good understanding of HTTP, XML, as well as a server-side scripting language capable of performing requests to the API e.g. ASP.NET, PHP or Java. It is also assumed that readers of this document have already created an account with Paythru, and Paythru have configured their account to accept the requests on behalf of the merchant.


2.0 API Overview

This API is web service. All functionality of the API is accessed by performing HTTP POST method requests directly from the merchant's web servers using an SSL connection.

2.1 API Requests

The Paythru Payments API accepts HTTP POST method requests using an SSL connection (HTTPS). The key-value parameters sent in body of the request must be encoded using the application/form-url-encoded Internet media type.

The data returned in the response to the HTTP request can be encoded in a choice of either XML or JSON encoding.

The request must be submitted from the merchant's servers to Paythru's servers using the URL below. Under no circumstances should requests be made to the API directly from the customer's web browser or mobile application.

2.2 Request URL

Requests to the Paythru Payments API should be sent to a URL constructed in the following manner:

https://ws.paythru.com/v{version number}/transaction/{method name}/{response encoding}

The {version number} segment within the URL should be replaced with the version of the API. The current version of the API is 3.

The {method name} segment within the URL should be replaced with the method of the API being requested.

The last segment of the URL - {response encoding} indicates whether the response from the web service should be encoded in XML or JSON.

Example URL

For example, a request to the auth method of version 3 of the API with the response encoded in JSON should be sent to the following URL:

https://ws.paythru.com/v3/transaction/auth/json

Please note that if the response encoding segment of the URL is not provided, the response will be encoded in XML.

2.3 API Responses

Requests to the API processed successfully will be responded to with a 200 (OK) HTTP response code. The data contained within the body of the response will be encoded in either XML or JSON encoding types a requested. Requests that are unable to be processed will be responded to with either the HTTP response code 400 (Bad Request), 401 (Unauthorized) or 403 (Forbidden) depending on the nature of the error.

XML encoded responses

The response parameters within an XML encoded response will be returned as XML elements, the name of which will be the parameter name, and the value contained within, its associated value. All the response data elements will be contained within a root element named 'paythruResponse'.

<?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <responseParameter>Response value</responseParameter> ... </paythruResponse>

JSON encoded responses

The response parameters within a JSON encoded response will be returned as properties of a single JSON object, the name of which will be parameter name and the value, its associated value.

{"responseParameter":"response Value", ...}

2.4 Authentication

All requests made to the API require authentication. Two request parameters (apiKey and apiPassword) are required to be sent with each request to the service. These parameters will be provided by Paythru when the account is created.

If more than 5 requests are made containing invalid credentials within the same day, Paythru will not accept any further requests from the originating IP address for a period of one minute. After 10 requests failing authentication, the IP address will be blocked for 5 minutes.

2.5 Signing the request

All requests to this API must be signed by constructing a hash the request parameters and the shaKey (provided by Paythru) using the following steps:

  • Arrange all request parameters in order by parameter name (not including the shaSignature parameter)
  • Remove parameters with no value
  • Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
  • Concatenate all resulting strings in order
  • Hash the resulting string using SHA512

The value of the hash must be provided in the shaSignature parameter within each request.

The following example indicates how to construct the signature for an auth method request using shaKey of HXUWeWG9gFa2ZHH1cQ:

Arrange parameters in alphabetical order by parameter name...

apiKey: tPkMAb7Hxxu6eGxLW1cW apiPassword: dBD82Go26Wsxyw1N6W1H cardCV2: 123 cardExpiryMonth: 01 cardExpiryYear: 18 cardholderName: MR John Smith cardNumber: 4444333322221111 terminalKey: NULL currency: GBP merchantReference: NULL transactionValue: 200

...remove the parameters with no value...

apiKey: tPkMAb7Hxxu6eGxLW1cW apiPassword: dBD82Go26Wsxyw1N6W1H cardCV2: 123 cardExpiryMonth: 01 cardExpiryYear: 18 cardholderName: MR John Smith cardNumber: 4444333322221111 currency: GBP transactionValue: 200

...concatenate the parameter names, an '=' symbol, parameter value and shaKey...

apiKey=tPkMAb7Hxxu6eGxLW1cWHXUWeWG9gFa2ZHH1cQ apiPassword=dBD82Go26Wsxyw1N6W1HHXUWeWG9gFa2ZHH1cQ cardCV2=123HXUWeWG9gFa2ZHH1cQ cardExpiryMonth=01HXUWeWG9gFa2ZHH1cQ cardExpiryYear=18HXUWeWG9gFa2ZHH1cQ cardholderName=MR John SmithHXUWeWG9gFa2ZHH1cQ cardNumber=4444333322221111HXUWeWG9gFa2ZHH1cQ currency=GBPHXUWeWG9gFa2ZHH1cQ transactionValue=200HXUWeWG9gFa2ZHH1cQ

...concatenate the strings in order...

apiKey=tPkMAb7Hxxu6eGxLW1cWHXUWeWG9gFa2ZHH1cQapiPassword=dBD 82Go26Wsxyw1N6W1HHXUWeWG9gFa2ZHH1cQcardCV2=123HXUWeWG9gFa2ZH H1cQcardExpiryMonth=01HXUWeWG9gFa2ZHH1cQcardExpiryYear=18HXU WeWG9gFa2ZHH1cQcardholderName=MR John SmithHXUWeWG9gFa2ZHH1cQ cardNumber=4444333322221111HXUWeWG9gFa2ZHH1cQcurrency=GBP HXUWeWG9gFa2ZHH1cQtransactionValue=200HXUWeWG9gFa2ZHH1cQ

...hash the resulting string using SHA512. This is your shaSignature for the request.

e80219288380040dbcb3b1b2b88cf1811258c624eb7e22868 66582742cae5983150db311623fae741aaca5a100338ca09d 91c05fdef3294f7a6e97a1c9211d46

2.6 API integration and testing

Upon request, Paythru can provide credentials to an API test service suitable for integration development work and testing. The test service acts as an exact replica of the live API although payment results are simulated and no transactions are actually submitted to the banks/card schemes.

Please contact Paythru to apply for test service credentials or for any further information regarding the service.


3.0 Methods

3.1 Card Auth method

Description

The auth method is used to request an 'auth' card payment on behalf of a customer. Authorisation and settlement of the transaction are both initiated from the single request. An auth request therefore requires no further request for settlement or clearing of the transaction.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/auth

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
cardholderName The cardholder's name as printed on their card. This is submitted with the transaction and may therefore be used by the card issuer to determine the authenticity of the request. This parameter is optional although may be required for approval of the transaction. Alpha and symbol characters
cardNumber The full primary account number (PAN) of the card number with no spaces or separators. See Appendix 5.4 for test card numbers. 13-19 numeric characters
cardExpiryMonth The expiration month of the card in MM format without spaces or separators. 2 numeric characters
cardExpiryYear The expiration year of the card in YY format without spaces or separators. 2 numeric characters
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
merchantCustomerReference A reference for the merchant to identify the customer (previously known as Merchant Authenticated ID, or MAID). This parameter is optional. Up to 45 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to refund the transaction using the API (see refund method). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/auth HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &cardholderName=Mr+John+Smith &cardNumber=4444333322221111 &cardExpiryMonth=01 &cardExpiryYear=18 &cardCV2=123 &merchantReference=12345678 &shaSignature=146583b28e89fgeb56ce2a8b925d25e9g05ddacf5b5f91 gbceb0e63f7321acd29bfe804e06eg0e017173f1bcb3a5b3g5f6b5337g0g a3bfg36bb64d78381f8249

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 363 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>Auth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>12345</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 197 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"Auth", "transactionKey":"bc415b822werwerrx4b03ce1d0950a2944", "bankTransId":"12345", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.2 Token Auth method

Description

The token auth method is used to request an 'auth' card payment on behalf of a customer using a card token. Authorisation and settlement of the transaction are both initiated from the single request. An auth request therefore requires no further request for settlement or clearing of the transaction.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/authCardKey

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
cardKey The reference of the card token to be used. Alpha and symbol characters
merchantCustomerReference A reference for the merchant to identify the customer. This parameter is optional and can be used for validating the card key Up to 45 characters
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to refund the transaction using the API (see refund method). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/authCardKey HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &cardKey=01239179-00df-a45a-497a-4f645463602e &cardCV2=123 &merchantReference=12345678 &shaSignature=146583b28e89fgeb56ce2a8b925d25e9g05ddacf5b5f91 gbceb0e63f7321acd29bfe804e06eg0e017173f1bcb3a5b3g5f6b5337g0g a3bfg36bb64d78381f8249

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 363 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>Auth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>12345</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 197 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"Auth", "transactionKey":"bc415b822werwerrx4b03ce1d0950a2944", "bankTransId":"12345", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.3 Session Auth method

Description

The session auth method is used to request an 'auth' card payment on behalf of a customer using a session key returned from Paythru's Client POST API. Card details must first be posted from the customer's browser or app to the 'postform' method of the Client POST API before calling the session auth method.

Authorisation and settlement of the transaction are both initiated from the single request. An auth request therefore requires no further request for settlement or clearing of the transaction.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/authSessionKey

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
sessionKey The reference of an active Client POST session to be used. Alpha and symbol characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
merchantCustomerReference A reference for the merchant to identify the customer (previously known as Merchant Authenticated ID, or MAID). This parameter is optional. Up to 45 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to refund the transaction using the API (see refund method). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/authSessionKey HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &sessionKey=1f5544277cbef70bf750336068ce5863 &merchantReference=12345678 &shaSignature=146583b28e89fgeb56ce2a8b925d25e9g05ddacf5b5f91 gbceb0e63f7321acd29bfe804e06eg0e017173f1bcb3a5b3g5f6b5337g0g a3bfg36bb64d78381f8249

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 363 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>Auth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>12345</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 197 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"Auth", "transactionKey":"bc415b822werwerrx4b03ce1d0950a2944", "bankTransId":"12345", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.4 Card PreAuth method

Description

The preauth method is used to request a 'pre-auth' card payment on behalf of a customer. A pre-auth transaction authorises the reservation of funds from a cardholder's account without actually debiting the account. A further request is required if the reserved funds are to be collected by the merchant (see capturepreauth method). The reservation will expire naturally (usually between 1 and 5 days later), however a request to cancel the reservation may also be conducted (see cancelpreauth method).

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/preauth

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
cardholderName The cardholder's name as printed on their card. This is submitted with the transaction and may therefore be used by the card issuer to determine the authenticity of the request. This parameter is optional although may be required for approval of the transaction. Alpha and symbol characters
cardNumber The full primary account number (PAN) of the card number with no spaces or separators. See Appendix 5.4 for test card numbers. 13-19 numeric characters
cardExpiryMonth The expiration month of the card in MM format without spaces or separators. 2 numeric characters
cardExpiryYear The expiration year of the card in YY format without spaces or separators. 2 numeric characters
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
merchantCustomerReference A reference for the merchant to identify the customer (previously known as Merchant Authenticated ID, or MAID). This parameter is optional. Up to 45 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/preauth HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &cardholderName=Mr+John+Smith &cardNumber=4444333322221111 &cardExpiryMonth=01 &cardExpiryYear=18 &cardCV2=123 &merchantReference=12345678 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>PreAuth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>71868</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"PreAuth", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.5 Token PreAuth method

Description

The token preauth method is used to request a 'pre-auth' card payment on behalf of a customer using a card token. A pre-auth transaction authorises the reservation of funds from a cardholder's account without actually debiting the account. A further request is required if the reserved funds are to be collected by the merchant (see capturepreauth method). The reservation will expire naturally (usually between 1 and 5 days later), however a request to cancel the reservation may also be conducted (see cancelpreauth method).

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/preauthCardKey

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
cardKey The reference of the card token to be used. Alpha and symbol characters
merchantCustomerReference A reference for the merchant to identify the customer. This parameter is optional and can be used for validating the card key Up to 45 characters
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/preauthCardKey HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &cardKey=01239179-00df-a45a-497a-4f645463602e &cardCV2=123 &merchantReference=12345678 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>PreAuth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>71868</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"PreAuth", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.6 Session PreAuth method

Description

The session preauth method is used to request an 'pre-auth' card payment on behalf of a customer using a session key returned from Paythru's Client POST API. Card details must first be posted from the customer's browser or app to the 'postform' method of the Client POST API before calling the session preauth method.

A pre-auth transaction authorises the reservation of funds from a cardholder's account without actually debiting the account. A further request is required if the reserved funds are to be collected by the merchant (see capturepreauth method). The reservation will expire naturally (usually between 1 and 5 days later), however a request to cancel the reservation may also be conducted (see cancelpreauth method).

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/preauthSessionKey

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
sessionKey The reference of an active Client POST session to be used. Alpha and symbol characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/preauthSessionKey HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &sessionKey=cb8ce0b3265b52b7d52badaf28574532 &merchantReference=12345678 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>PreAuth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>71868</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"PreAuth", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.7 Initiate Card 3-D Secure method

Description

The initiate card 3-D Secure method is used to initiate a 3-D Secure transaction with a credit or debit card.

3-D Secure transactions are conducted in three steps using this API. A request to initiate the transaction is first performed, which will return the URL of the 3-D Secure authentication page. Once the customer has completed authentication and is returned to the merchant, the second 'lookup' method is used to determine the result of the authentication. If the merchant is then willing to proceed, a third method is called to authorise the transaction. This method represents the first of these three steps.

The URL of the 3-D Secure authentication page is returned in the response from the API. This URL should be set as the 'src' parameter of a new window or iframe and presented to the customer to complete authentication (if the customer's card does not support 3-D Secure, the authentication URL will redirect immediately to the merchant's return URL).

If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/initiate3DSecure

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
cardholderName The cardholder's name as printed on their card. This is submitted with the transaction and may therefore be used by the card issuer to determine the authenticity of the request. This parameter is optional although may be required for approval of the transaction. Alpha and symbol characters
cardNumber The full primary account number (PAN) of the card number with no spaces or separators. See Appendix 5.4 for test card numbers. 13-19 numeric characters
cardExpiryMonth The expiration month of the card in MM format without spaces or separators. 2 numeric characters
cardExpiryYear The expiration year of the card in YY format without spaces or separators. 2 numeric characters
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
returnUrl The URL that the customer will be returned to after completing authentication. Valid URL
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the 3-D Secure initiation ('607' or '608'). 3 numeric characters
transactionStatus The human readable status of the 3-D Secure initiation ('Success' or 'Failed'). Success / Failed
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bankECIValue The ECI value returned from the bank. 2 numeric characters
authenticationKey A unique key that will be needed to authorise a transaction. (This parameter will only be present if 3-D Secure was initiated successfully.) 32 alpha numeric characters
authenticationUrl The authentication URL. (This parameter will only be present if 3-D Secure was initiated successfully.) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/initiate3DSecure HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &cardholderName=Mr+John+Smith &cardNumber=4444333322221111 &cardExpiry=0118 &cardCV2=123 &merchantReference=12345678 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>607</transactionStatusCode> <transactionStatus>Success</transactionStatus> <transactionType>3DSecureCheck</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankECIValue>06</bankECIValue> <authenticationKey>b3c1a4a94b4b1dbb8dfe4ffecd070ca4</authenticationKey> <authenticationUrl> http://ws.dev.paythru.com/threeDSRedirect/form/b3c1a4a94b4b1dbb8dfe4ffecd070ca4 </authenticationUrl> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":607, "transactionStatus":"Success", "transactionType":"3DSecureCheck", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654", "authenticationKey":"b3c1a4a94b4b1dbb8dfe4ffecd070ca4", "authenticationUrl":"http://ws.dev.paythru.com/threeDSRedirect/form/b3c1a4a94b4b1dbb8dfe4ffecd070ca4"}


3.8 Initiate Token 3-D Secure method

Description

The initiate card 3-D Secure method is used to initiate a 3-D Secure transaction with a card token.

3-D Secure transactions are conducted in three steps using this API. A request to initiate the transaction is first performed, which will return the URL of the 3-D Secure authentication page. Once the customer has completed authentication and is returned to the merchant, the second 'lookup' method is used to determine the result of the authentication. If the merchant is then willing to proceed, a third method is called to authorise the transaction. This method represents the first of these three steps.

The URL of the 3-D Secure authentication page is returned in the response from the API. This URL should be set as the 'src' parameter of a new window or iframe and presented to the customer to complete authentication (if the customer's card does not support 3-D Secure, the authentication URL will redirect immediately to the merchant's return URL).

If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/initiate3DSecureCardKey

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
cardKey The reference of the card token to be used. Alpha and symbol characters
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
returnUrl The URL that the customer will be returned to after completing authentication. Valid URL
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
merchantCustomerReference A reference for the merchant to identify the customer. This parameter is optional and can be used for validating the card key Up to 45 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the 3-D Secure initiation ('607' or '608'). 3 numeric characters
transactionStatus The human readable status of the 3-D Secure initiation ('Success' or 'Failed'). Success / Failed
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bankECIValue The ECI value returned from the bank. 2 numeric characters
authenticationKey A unique key that will be needed to authorise a transaction. (This parameter will only be present if 3-D Secure was initiated successfully.) 32 alpha numeric characters
authenticationUrl The authentication URL. (This parameter will only be present if 3-D Secure was initiated successfully.) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/initiate3DSecureCardKey HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &cardKey=01239179-00df-a45a-497a-4f645463602e &cardCV2=123 &merchantReference=12345678 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>607</transactionStatusCode> <transactionStatus>Success</transactionStatus> <transactionType>3DSecureCheck</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankECIValue>06</bankECIValue> <authenticationKey>b3c1a4a94b4b1dbb8dfe4ffecd070ca4</authenticationKey> <authenticationUrl> http://ws.dev.paythru.com/threeDSRedirect/form/b3c1a4a94b4b1dbb8dfe4ffecd070ca4 </authenticationUrl> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":607, "transactionStatus":"Success", "transactionType":"3DSecureCheck", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654", "authenticationKey":"b3c1a4a94b4b1dbb8dfe4ffecd070ca4", "authenticationUrl":"http://ws.dev.paythru.com/threeDSRedirect/form/b3c1a4a94b4b1dbb8dfe4ffecd070ca4"}


3.9 Initiate Session 3-D Secure method

Description

The initiate card 3-D Secure method is used to initiate a 3-D Secure transaction with a session key returned from Paythru's Client POST API. Card details must first be posted from the customer's browser or app to the 'postform' method of the Client POST API before calling this method.

3-D Secure transactions are conducted in three steps using this API. A request to initiate the transaction is first performed, which will return the URL of the 3-D Secure authentication page. Once the customer has completed authentication and is returned to the merchant, the second 'lookup' method is used to determine the result of the authentication. If the merchant is then willing to proceed, a third method is called to authorise the transaction. This method represents the first of these three steps.

The URL of the 3-D Secure authentication page is returned in the response from the API. This URL should be set as the 'src' parameter of a new window or iframe and presented to the customer to complete authentication (if the customer's card does not support 3-D Secure, the authentication URL will redirect immediately to the merchant's return URL).

If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes. See appendix 5.3 for more information.

URL

https://ws.paythru.com/v3/transaction/initiate3DSecureSessionKey

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
itemName0 The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0 The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Numeric characters
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer (e.g. '2')
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 32 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
sessionKey The reference of an active Client POST session to be used. Alpha and symbol characters
returnUrl The URL that the customer will be returned to after completing authentication. Valid URL
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
merchantCustomerReference A reference for the merchant to identify the customer (previously known as Merchant Authenticated ID, or MAID). This parameter is optional. Up to 45 characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric and symbol characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the 3-D Secure initiation ('607' or '608'). 3 numeric characters
transactionStatus The human readable status of the 3-D Secure initiation ('Success' or 'Failed'). Success / Failed
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bankECIValue The ECI value returned from the bank. 2 numeric characters
authenticationKey A unique key that will be needed to authorise a transaction. (This parameter will only be present if 3-D Secure was initiated successfully.) 32 alpha numeric characters
authenticationUrl The authentication URL. (This parameter will only be present if 3-D Secure was initiated successfully.) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/initiate3DSecureSessionKey HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &itemName0=Baseball+cap &itemPrice0=500 &itemQuantity0=1 &currency=GBP &sessionKey=9a085ace3035b9a40e739d0fc01e2ce1 &merchantReference=12345678 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>607</transactionStatusCode> <transactionStatus>Success</transactionStatus> <transactionType>3DSecureCheck</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankECIValue>06</bankECIValue> <authenticationKey>b3c1a4a94b4b1dbb8dfe4ffecd070ca4</authenticationKey> <authenticationUrl> http://ws.dev.paythru.com/threeDSRedirect/form/b3c1a4a94b4b1dbb8dfe4ffecd070ca4 </authenticationUrl> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":607, "transactionStatus":"Success", "transactionType":"3DSecureCheck", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654", "authenticationKey":"b3c1a4a94b4b1dbb8dfe4ffecd070ca4", "authenticationUrl":"http://ws.dev.paythru.com/threeDSRedirect/form/b3c1a4a94b4b1dbb8dfe4ffecd070ca4"}


3.10 3-D Secure Authentication Status method

Description

The 3-D Secure authentication status method returns the result of a 3-D Secure authentication initiated using one of Paythru's initiate 3-D Secure methods. The response includes a flag indicating whether liability has shifted away from the merchant or not. This indicator may be used by the merchant to decide whether or not to continue with authorisation.

If the liabilityShift parameter returns 'Y', the merchant will not be liable for chargebacks after the transaction is authorised. If the liabilityShift parameter returns 'N', the merchant will remain liable for chargebacks if the transaction is authorised.

3-D Secure transactions are conducted in three steps using this API. A request to initiate the transaction is first performed, which will return the URL of the 3-D Secure authentication page. Once the customer has completed authentication and is returned to the merchant, the second 'lookup' method is used to determine the result of the authentication. If the merchant is then willing to proceed, a third method is called to authorise the transaction. This method represents the second of these three steps.

The result of the 3-D Secure authentication is returned in the response from the API. If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/getAuthenticationStatus

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
authenticationKey The authentication key from the initiate 3DSecure function Alpha-numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to capture or cancel the transaction using the API (see capturepreauth and cancelpreauth methods). 32 alpha numeric characters
bankECIValue The ECI value returned from the bank. 2 numeric characters
liabilityShift If the authentication has resulted in a liability shift. Y / N

Example Requests

HTTP Request

POST /v3/transaction/getAuthenticationStatus HTTP/1.1 Host: ws.paythru.com Content-Length: 355 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &authenticationKey=b3c1a4a94b4b1dbb8dfe4ffecd070ca4 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 369 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>3DSAuthenticatedOnly</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankECIValue>05</bankECIValue> <liabilityShift>Y</liabilityShift> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":607, "transactionStatus":"Success", "transactionType":"3DSAuthenticatedOnly", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654", "liabilityShift":"Y"}


3.11 3-D Secure Auth method

Description

The 3-D Secure auth method is used to authorise an authenticated 3-D Secure transaction.

3-D Secure transactions are conducted in three steps using this API. A request to initiate the transaction is first performed, which will return the URL of the 3-D Secure authentication page. Once the customer has completed authentication and is returned to the merchant, the second 'lookup' method is used to determine the result of the authentication. If the merchant is then willing to proceed, a third method is called to authorise the transaction. This method represents the third of these three steps.

The result of the transaction is returned in the response from the API. If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/auth3DSecure

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
authenticationKey The authentication key from the initiate 3DSecure function Alpha-numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to refund the transaction using the API (see refund method). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/auth3DSecure HTTP/1.1 Host: ws.paythru.com Content-Length: XXX Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &authenticationKey=b3c1a4a94b4b1dbb8dfe4ffecd070ca4 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 363 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>Auth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>12345</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 197 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"Auth", "transactionKey":"bc415b822werwerrx4b03ce1d0950a2944", "bankTransId":"12345", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.12 3-D Secure PreAuth method

Description

The 3-D Secure preauth method is used to preauthorise an authenticated 3-D Secure transaction.

3-D Secure transactions are conducted in three steps using this API. A request to initiate the transaction is first performed, which will return the URL of the 3-D Secure authentication page. Once the customer has completed authentication and is returned to the merchant, the second 'lookup' method is used to determine the result of the authentication. If the merchant is then willing to proceed, a third method is called to preauthorise the transaction. This method represents the third of these three steps.

The result of the transaction is returned in the response from the API. If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/preauth3DSecure

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
authenticationKey The authentication key from the initiate 3DSecure function Alpha-numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. The transaction key is required to refund the transaction using the API (see refund method). 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example Requests

HTTP Request

POST /v3/transaction/preauth3DSecure HTTP/1.1 Host: ws.paythru.com Content-Length: XXX Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &authenticationKey=b3c1a4a94b4b1dbb8dfe4ffecd070ca4 &shaSignature=8f0206f12dc90f7d1f3601252471d7b9438c7440c3cb15 d25d63602a9e1553e1ab9a0796bdf9f82e1575fb8b5ea38db9400647ab5c b044f0073f8a3b4cae8ea4

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 363 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>PreAuth</transactionType> <transactionKey>bc415b822werwerrx4b03ce1d0950a2944</transactionKey> <bankTransId>12345</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 197 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"PreAuth", "transactionKey":"bc415b822werwerrx4b03ce1d0950a2944", "bankTransId":"12345", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.13 Capture preauth method

Description

The capture preauth method is used to capture funds that were reserved by a previous preauth transaction for settlement to the merchant's account. If transactionValue is not passed, the original amount that was reserved will be captured. If the transactionValue is smaller than the original preauth, the remaining amount will remain as reserved for a few days until the bank removes the reservation of funds. If an attempt to capture a value higher than the reserved funds is made, an error message is returned.

Please note that capturepreauth transactions must be conducted in the same currency as the original preauth requests. The currency is therefore not required.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/capturepreauth

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
transactionKey The transaction key of the preauth transaction requiring capture. 32 alpha numeric characters
transactionValue The value of to be captured specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. This parameter is optional. If not, provided, the full value of the preauth transaction will be used. Numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example requests

HTTP Request

POST /v3/transaction/capturepreauth HTTP/1.1 Host: ws.paythru.com Content-Length: 237 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &transactionKey=87955fee774df1d219784a38482f3082 &shaSignature=05543a0cf7ea63338b85903914a92168cf0d5baee15222 fe365a4c314d93c99ef36b90de5de6cd168163886add8538d16c4e6f8c78 04774ba7f43d3d3b3be98d

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 368 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>Capture</transactionType> <transactionKey>bc415b82204dfvdfvd03ce1d0950a2944</transactionKey> <bankTransId>72348</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 225 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"Capture", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankResponseCode":"1", "bankAuthCode":"987654"}


3.14 Cancel Preauth method

Description

This method should be used to request cancellation of the reservation of the funds held by a previous preauth transaction. Please note that card issuers may not always respect the cancellation request and a successful response from this method does not mean that cancellation has been completed. Also note that cancellation may take a period of time to complete.

It may be possible to cancel a part of the reservation of funds by passing a transactionValue. If the transactionValue is not passed, cancellation of the entire value of the original preauth transaction will be requested.

Please note that cancelpreauth transactions must be conducted in the same currency as the original preauth requests. The currency is therefore not required.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/cancelpreauth

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
transactionKey The transaction key of the preauth transaction requiring cancellation. 32 alpha numeric characters
transactionValue The value to be cancelled specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. This parameter is optional. If not, provided, the full value of the preauth transaction will be used. Numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example requests

HTTP Request

POST /v3/transaction/cancelpreauth HTTP/1.1 Host: ws.paythru.com Content-Length: 237 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &transactionKey=87955fee774df1d219784a38482f3082 &shaSignature=c88d17e85a3929ae1cd5f0b195a639c818a82b2edb0310 d46391fcb98cca7d96ce98c1694417ed36fb33f5fe694f3463ce9cb84b67 b528a179f2ce7da0b6fe71

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 368 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>CancelPreAuth</transactionType> <transactionKey>bc415b82204dfvdfvd03ce1d0950a2944</transactionKey> <bankTransId>72348</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"CancelPreAuth", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.15 Refund method

Description

The refund method is used to return funds from a previous auth or capturepreauth transaction to the cardholder.

Partial refunds may be requested by specifying the amount to be refunded. If transactionValue is not passed, the full amount of the original transaction will be refunded. If the amount requested exceeds the original amount, an error is returned.

Please note that refund transactions must be conducted in the same currency as the original auth or capturepreauth requests. The currency is therefore not required.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/refund

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
transactionKey The transaction key of the auth or capturepreauth transaction requiring refunding. 32 alpha numeric characters
transactionValue The value to be refunded specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. This parameter is optional. If not, provided, the full value of the transaction to be refunded will be used. Numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactionType The human readable type of the transaction (See Appendix 5.5) Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): * bankAuthCode (Card issuer's authorisation code) * bankTransId (Transaction ID issued by acquiring bank) * bankResponseCode (Transaction status code issued by acquiring bank) * bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank) Alpha numeric characters and symbols

Example requests

HTTP POST Request

POST /v3/transaction/refund HTTP/1.1 Host: ws.paythru.com Content-Length: 237 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &transactionKey=87955fee774df1d219784a38482f3082 &shaSignature=a640356f8f4eecfa7366e26ba93b6334f85475f31e4ac8 72dbfd390a1c1e5522abf6f6ee6d134134ee0959df9aa4da22f688b9356f 2ffcb59441c06135be6d8e

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 368 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Transaction approved</transactionStatus> <transactionType>Refund</transactionType> <transactionKey>bc415b82204dfvdfvd03ce1d0950a2944</transactionKey> <bankTransId>72348</bankTransId> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>987654</bankAuthCode> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"transactionStatusCode":600, "transactionStatus":"Transaction approved", "transactionType":"Refund", "transactionKey":"87955fee774df1d219784a38482f3082", "bankTransId":"14766", "bankResponseMessage":"OK", "bankAuthCode":"987654"}


3.16 Update method

Description

Although many transaction fields cannot be modified, as they form part of the transaction audit trail, this update method can be used to update analytical and meta data related to a transaction. Any type of transaction (except EFTs) can be updated in this way, all that's required is the transaction key.

At least one field must be provided with valid update data for the call to succeed. For a little added security if any field already has a value in our system, the call will be rejected. If any field values are passed as blank, the field will be ignored (it is not possible to 'unset' a value.

The result of the request is returned in the response from the API. If the request could not be processed, an error response will be returned (See section 4.0 Error Handling).

URL

https://ws.paythru.com/v3/transaction/update

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
transactionKey The transaction key of the transaction to be updated. 32 alpha numeric characters
merchantCustomerReference A reference for the merchant to identify the customer (previously known as Merchant Authenticated ID, or MAID). Up to 45 characters
merchantReference The merchant's reference for the transaction. Up to 32 characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
result Value = OK 2 characters

Example requests

HTTP POST Request

POST /v3/transaction/update HTTP/1.1 Host: ws.paythru.com Content-Length: 237 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &transactionKey=87955fee774df1d219784a38482f3082 &merchantCustomerReference=user987654321 &merchantReference=ref1234 &shaSignature=a640356f8f4eecfa7366e26ba93b6334f85475f31e4ac8 72dbfd390a1c1e5522abf6f6ee6d134134ee0959df9aa4da22f688b9356f 2ffcb59441c06135be6d8e

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 368 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <result>OK</result> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 {"result":"OK"}


3.17 Lookup method

Description

The lookup method provides a service to lookup the details stored in a transaction. The method returns transaction details queried either by passing the transaction key or merchant reference. Please note that in order for the service to return transaction details by merchant reference, the transaction must have been created with the merchantReference present. Please also note that if both transactionKey and merchantReference are provided in the request the service will return transactions where both criteria match.

URL

https://ws.paythru.com/v3/transaction/lookup

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
transactionKey The transaction key of the transaction to be updated. 32 alpha numeric characters
merchantReference The merchant's reference for the transaction. Up to 32 characters
uniqueMerchantReference A unique merchant's reference Up to 128 characters
shaSignature The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature. 128 Alpha numeric characters

Response parameters

Name Description Format
transactions Node containing details of each transaction record returned Alpha numeric characters
transactions > transaction Node containing details of the transaction Alpha numeric characters
transactions > transaction > transactionStatusCode The status code of the transaction (See Appendix 5.2) 3 numeric characters
transactions > transaction > transactionStatus The human readable status of the transaction (See Appendix 5.2) Up to 100 characters
transactions > transaction > transactionKey The unique reference for the transaction generated by Paythru 32 alpha numeric characters
transactions > transaction > bankTransId Any transaction id that might be returned by the bank Alpha numeric characters
transactions > transaction > bankResponseCode A response code returned by the bank Alpha numeric characters
transactions > transaction > bankResponseMessage The bank response message returned by the bank Alpha numeric characters
transactions > transaction > bankAuthCode Card issuer's authorisation code Alpha numeric characters
transactions > transaction > transactionType The type of the transaction Alpha numeric characters
transactions > transaction > transactionValue The total value of transaction Alpha numeric characters
transactions > transaction > currency The ISO 4217 currency (e.g. GBP) that was used in the transaction Alpha numeric characters
transactions > transaction > checkoutKey The checkout key stored against the transaction Alpha numeric characters
transactions > transaction > merchantCustomerReference A reference for the merchant to identify the customer Alpha numeric characters
transactions > transaction > merchantReference The merchant's reference for the transaction Alpha numeric characters
transactions > transaction > uniqueMerchantReference The unique merchant's reference for the transaction Alpha numeric characters
transactions > transaction > customer Node containing details of the customer Alpha numeric characters
transactions > transaction > customer > customerTitle The customer's title Alpha numeric characters
transactions > transaction > customer > customerFirstName The customer's first name Alpha numeric characters
transactions > transaction > customer > customerSurname The customer's surname Alpha numeric characters
transactions > transaction > customer > customerEmail The customer's name Alpha numeric characters
transactions > transaction > customer > customerMobile The customer's mobile phone number Alpha numeric characters
transactions > transaction > customer > customerTelephone The customer's telephone number Alpha numeric characters
transactions > transaction > card Node containing details of the card Alpha numeric characters
transactions > transaction > card > cardDescription Card Description Alpha numeric characters
transactions > transaction > card > cardholderName Cardholder's name Alpha numeric characters
transactions > transaction > card > cardNumber Masked card number Alpha numeric characters
transactions > transaction > card > cardLastFour Last four digits of the card number 4 numeric characters
transactions > transaction > card > cardFirstSix First six digits of the card number 6 numeric characters
transactions > transaction > card > cardExpiryMonth Card expiry month 2 numeric characters
transactions > transaction > card > cardExpiryYear Card expiry year 2 numeric characters
transactions > transaction > card > cardBank Card's bank Alpha numeric characters
transactions > transaction > card > cardCountry Card's country Alpha numeric characters
transactions > transaction > card > cardType Card type Alpha numeric characters
transactions > transaction > card > cardScheme Card Scheme Alpha numeric characters
transactions > transaction > card > cardholderAddress Node containing details of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressPropertyName Property name of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressLine1 Line 1 of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressLine2 Line 2 of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressLine3 Line 3 of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressTown Town of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressCounty County of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressPostcode Postcode of the cardholder's address Alpha numeric characters
transactions > transaction > card > cardholderAddress > cardholderAddressCountry Country of the cardholder's address Alpha numeric characters
transactions > transaction > customerAddress Node containing details of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressPropertyName Property name of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressLine1 Line 1 of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressLine2 Line 2 of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressLine3 Line 3 of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressTown Town of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressCounty County of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressPostcode Postcode of the customer's address Alpha numeric characters
transactions > transaction > customerAddress > customerAddressCountry Country of the customer's address Alpha numeric characters

Example requests

HTTP POST Request

POST /v3/transaction/update HTTP/1.1 Host: ws.paythru.com Content-Length: 237 Content-Type: application/x-www-form-urlencoded apiKey=************ &apiPassword=********** &transactionKey=6eb92d9e5621b5a53201709a2ec8f727 &merchantReference=ref1234 &shaSignature=a640356f8f4eecfa7366e26ba93b6334f85475f31e4ac8 72dbfd390a1c1e5522abf6f6ee6d134134ee0959df9aa4da22f688b9356f 2ffcb59441c06135be6d8e

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 368 <paythruResponse> <transactions> <transaction> <transactionStatusCode>600</transactionStatusCode> <transactionStatus>Approved</transactionStatus> <transactionKey>6eb92d9e5621b5a53201709a2ec8f727</transactionKey> <bankTransId>35289</bankTransId> <bankResponseCode>1</bankResponseCode> <bankResponseMessage>OK</bankResponseMessage> <bankAuthCode>20200</bankAuthCode> <transactionType>Auth</transactionType> <transactionValue>1517</transactionValue> <currency>ZAR</currency> <checkoutKey/> <merchantCustomerReference>ref1234</merchantCustomerReference> <merchantReference>apiTest281</merchantReference> <customer> <customerTitle>Mr</customerTitle> <customerFirstName>Bob</customerFirstName> <customerSurname>Marty</customerSurname> <customerEmail>bmatry@example.com</customerEmail> <customerMobile>0784561230</customerMobile> <customerTelephone>141998445220</customerTelephone> </customer> <card> <cardDescription/> <cardholderName>John Smith</cardholderName> <cardNumber>444433******1111</cardNumber> <cardLastFour>1111</cardLastFour> <cardFirstSix>444433</cardFirstSix> <cardExpiryMonth>12</cardExpiryMonth> <cardExpiryYear>16</cardExpiryYear> <cardBank>paythru</cardBank> <cardCountry>GB</cardCountry> <cardType>CREDIT</cardType> <cardScheme/> <cardholderAddress> <cardholderAddressPropertyName>Block 1</cardholderAddressPropertyName> <cardholderAddressLine1>Paythru</cardholderAddressLine1> <cardholderAddressLine2>Bell lane</cardholderAddressLine2> <cardholderAddressLine3/> <cardholderAddressTown>Amersham</cardholderAddressTown> <cardholderAddressCounty>Bucks</cardholderAddressCounty> <cardholderAddressPostcode>HP66GL</cardholderAddressPostcode> <cardholderAddressCountry>UK</cardholderAddressCountry> </cardholderAddress> </card> <customerAddress/> </transaction> </transactions> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Type: text/json; charset=utf-8 Content-Length: 202 { "transactions": [ { "transactionStatusCode": "600", "transactionStatus": "Approved", "transactionKey": "6eb92d9e5621b5a53201709a2ec8f727", "bankTransId": "35289", "bankResponseCode": "1", "bankResponseMessage": "OK", "bankAuthCode": "20200", "transactionType": "Auth", "transactionValue": "1517", "currency": "ZAR", "checkoutKey": null, "merchantCustomerReference": "ref1234", "merchantReference": "apiTest281" "customer": { "customerTitle": "Mr", "customerFirstName": "Bob", "customerSurname": "Marty", "customerEmail": "bmatry@example.com", "customerMobile": "0784561230", "customerTelephone": "141998445220" }, "card": { "cardDescription": null, "cardholderName": "John Smith", "cardNumber": "444433******1111", "cardLastFour": "1111", "cardFirstSix": 444433, "cardExpiryMonth": "12", "cardExpiryYear": "16", "cardBank": "paythru", "cardCountry": "GB", "cardType": "CREDIT", "cardScheme": null, "cardholderAddress": { "cardholderAddressPropertyName": "Block 1", "cardholderAddressLine1": "Paythru", "cardholderAddressLine2": "Bell lane", "cardholderAddressLine3": "", "cardholderAddressTown": "Amersham", "cardholderAddressCounty": "Bucks", "cardholderAddressPostcode": "HP66GL", "cardholderAddressCountry": "UK" } }, "customerAddress": null } ] }


4.0 Error Handling

If the server is unable to process the request, an error is thrown. The nature of the error is returned as an error code and error message encoded in the expected response encoding format.

Error response format

All errors are returned with either the HTTP response code 400 (Bad Request), 401 (Unauthorized) or 403 (Forbidden) depending on the nature of the error.

The error response will contain the following parameters:

Name Description Format
errorCode The code indicating the type of error 3 numeric characters
traceCode The trace code of the error. The trace code should be used in any communication with Paythru to assist in determining the cause of the error. 8 numeric characters
errorMessage The human readable error message Up to 100 characters

For example, if an XML response has been requested from the API, the error will be returned in XML encoding.

Example XML error response

HTTP/1.1 401 Unauthorized Content-Type: text/json; charset=utf-8 Content-Length: 183 <?xml version="1.0" encoding="utf-8"?> <paythruResponse> <errorCode>102</errorCode> <traceCode>010502102</traceCode> <errorMessage>Invalid API credentials</errorMessage> </paythruResponse>

See Appendix 5.1 for possible error messages.


5.0 Appendix

5.1 Error codes and messages

Error code Error message
101 No data sent
102 Invalid API credentials
103 Invalid function call
104 Invalid return type
105 Cannot find API settings for merchant
106 Permission denied to access this function
107 Invalid transaction value
108 Invalid card number
109 Invalid card expiry
110 Invalid card CV2
111 Currency not supported
112 Error finding previous transaction
113 Invalid transaction key
114 Refund not allowed for the transaction key
115 Capture not allowed for the transaction key
116 Cancel not allowed for the transaction key
117 Excess refund
118 Excess capture or cancel
119 No response from bank
120 Currency not supplied
121 This IP has been blocked for 1 minute due to excessive failed attempts
122 This IP has been blocked for 5 minutes due to excessive failed attempts
123 SHA Signature could not be verified
124 Invalid terminal key
125 Invalid merchant reference
126 Invalid items
127 Invalid item price
128 Invalid transaction type
137 Total amount cannot be negative
138 Total amount cannot be zero
139 Total amount is too large
143 Invalid merchant customer reference
144 No data sent for update
145 One or more fields are already populated and cannot be overwritten
146 Invalid card key
147 Card key not found
149 Permission denied to use card key
150 Card details cannot be sent along with card key
152 This function does not accept card key
154 Multiple card key found in session
155 Invalid return URL
156 Transaction not authenticated successfully
157 Invalid authentication key
158 Authentication key is no longer available

5.2 Transaction Status

Status code Status message
600 Transaction approved
601 Transaction declined
602 Transaction pending
603 Connection error
604 3D secure pending
605 Blacklisted
607 Success
608 Failed (if returned on a 3DSecure transaction, you may proceed as non-authenticated)
609 Duplicate
610 Rejected (if returned on a 3DSecure transaction, do not proceed with the authorisation)
699 Unknown error

5.3 Optional Fields

Below are the optional fields that can be passed for the following functions

  • auth
  • authCardKey
  • authSessionKey
  • preauth
  • preauthCardKey
  • preauthSessionKey
  • initiate3DSecure
  • initiate3DSecureCardKey
  • initiate3DSecureSessionKey

The data values are stored by Paythru for reporting and reconciliation purposes only.

Name Description Format
customerTitle The customer's title (e.g. Mr) Up to 12 alpha numeric characters and symbols
customerFirstName The customer's first name (e.g. John) Up to 50 alpha numeric characters and symbols
customerSurname The customer's surname (e.g. Smith) Up to 50 alpha numeric characters and symbols
customerEmail The email address of the customer Up to 50 alpha numeric characters and symbols
customerMobile The mobile phone number of the customer Up to 14 alpha numeric characters and symbols
customerLandline The telephone number of the user Up to 14 alpha numeric characters and symbols
customerAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
customerAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
customerAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols

5.4 Test Card Numbers

Card Number Auth / Preauth Initiate3DSecure
4444333322221111 Successful Transaction Success: Card enrolled
4111111111111111 Declined Transaction Failed: Unable to verify enrolled
5454545454545454 Successful Transaction Failed: Unable to verify enrolled
4222222222222 Successful Transaction Success: Card not enrolled

Any other card that Luhn validates will result in a successful transaction or card enrolled. Card expiry can be any date in the future and Card CV2 can be any 3 or 4 digit number

5.5 Transaction Type

Type Requested Action
Auth Authorise and capture the amount
PreAuth Reserve the funds without actually debiting the account
Capture Capture the funds that have been reserved
CancelPreAuth Cancel the reserved funds and release it back to the cardholder
Refund Return the amount back to the cardholder
3DSecureCheck Perform an enrollment check. The 3-D secure journey is pending
3DSAuthenticatedOnly Complete 3-D secure Authentication. No amount has been authorised
3DSecureAuth Authorise the amount and capture it after a successful 3-D secure authentication
3DSecurePreAuth Reserve the amount after a successful 3-D secure authentication
VoidAuth Cancel an authorised transaction

6.0 Revision History

Version Changes Published
0 First issue of v3 March 2015
1 Supports Unique merchant reference March 2015
1.1 Added Appendix for test cards May 2015
2 Modified initiate3DSecure & getAuthenticationStatus to add ECI value in the response. May 2015
3 Added new functionality to PreAuth after 3DS Authentication. June 2016
3 Added Transaction type within the response. Added Appendix with a list of all transaction types. Feb 2017