Paythru Gateway API

Version: 3


1.0 Introduction

The Gateway API is Paythru's processing solution for merchant hosted eCommerce transactions, allowing merchants greater control over the payment journey for their customers and sending the payment details to Paythru for processing. The API should only receive calls directly from your server, and not from a client or client-application.

This API is primarily used for completing a payment which has been started via some other mechanism, so you have a Session Key or Card Key value to process a payment against.

Those wishing to send raw card numbers must request permission to do so from Paythru, this is not enabled by default.

1.1 API URL

Environment URL
Live https://ws.paythru.com
Staging (or sandbox) https://ws.demo.paythru.com

The examples in the document use relative URLs, which must be prepended with a URL from the above table depending on the environment in use. To use the sandbox account, the format of the request will be the same but you will need to change the URL you send requests into. Note that credentials are not shared between Staging and Live.


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:

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

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

  1. Arrange all request parameters in order by parameter name (not including the shaSignature parameter)
  2. Remove parameters with no value
  3. Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
  4. Concatenate all resulting strings in order
  5. 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.

2.7 API Throughput

It is important to note that Paythru API's have a default maximum throughput of 100 requests per minute. This limit is flexible, and designed to protect the platform rather than limit your genuine usage. If you expect to exceed this limit because of a high number of users, or because you are doing batch processing with asynchronous calls or multiple threads (single, synchronous, threads we would not expect to encounter this limit) please contact Paythru support to talk through your expectations so we can adjust your throughput limits accordingly.


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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD
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

/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

/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

/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

/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

/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

/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

/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

/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

  1. auth
  2. authCardKey
  3. authSessionKey
  4. preauth
  5. preauthCardKey
  6. preauthSessionKey
  7. initiate3DSecure
  8. initiate3DSecureCardKey
  9. initiate3DSecureSessionKey

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

Name Description Format
paymentSource The source of the payment. See Appendix 5.6 for more details ecomm / moto
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

5.6 Payment Source

6.0 Revision History

Document Revision Changes Published
1 First issue of v3 March 2015
2 Supports Unique merchant reference March 2015
3 Added Appendix for test cards May 2015
4 Modified initiate3DSecure & getAuthenticationStatus to add ECI value in the response. May 2015
5 Added new functionality to PreAuth after 3DS Authentication. June 2016
6 Added Transaction type within the response. Added Appendix with a list of all transaction types. Feb 2017
7 Added support for MCC 6012 fields to be provided with most transaction methods. These fields are required for some merchant types. July 2019