Card Tokenisation API

Version: 3


1.0 Introduction

The Tokenisation API is Paythru's processing solution for storing payment card details with Paythru for later processing, allowing merchants flexible payment options.

This API can accept raw card numbers, but this is not enabled by default. Please ask for support if you require this feature. The typical use case for this API is to collect payment card information or process a transaction via another Paythru API and then provide the relevant details here of that card or payment to store the card and receive a Card Key in return. This Card Key can then be used to process future payments against those stored details.

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 PaythruCard Tokenisation API accepts HTTP POST method requests over 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}/token/{method name}/{response encoding}

The {version number} segment within the URL should be replaced with the version of the API. The current version of this 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 lookup method of version 3 of the API with the response encoded in JSON should be sent to the following URL:

/v3/token/lookup/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. For more details regarding error responses, please refer to chapter 4.0 of this document..

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 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: qyc2o6hvYyGFcGEL3K
apiPassword: 83M3hWArBIsduSMGVa
cardKey: 6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff
merchantCustomerReference: NULL

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

apiKey: qyc2o6hvYyGFcGEL3K
apiPassword: 83M3hWArBIsduSMGVa
cardKey: 6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff

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

apiKey=qyc2o6hvYyGFcGEL3Kds45k324l3k423k233
apiPassword=83M3hWArBIsduSMGVads45k324l3k423k233
cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fffds45k324l3k423k233

...concatenate the strings in order...

apiKey=qyc2o6hvYyGFcGEL3Kds45k324l3k423k233apiPassword=83M3hWArBIsduSMGVads45k324l3k423k233cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fffds45k324l3k423k233

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

3c1eabc2f773a6ac7a32274e6aa61917d35804516df7258bcb981fa9e6c0ff84999e841734e1894ae527de5662a7a063c2d51ac493caf07f13b4b600ef96fdfe

2.6 API integration and testing

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

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

3.0 Methods

3.1 Lookup method

Description

The lookup method provides a service to lookup the details stored in a token or tokens. The method returns card token details queried either by passing the token's reference (cardKey) or unique ID for the customer (merchantCustomerReferece). Please note that in order for the service to return tokens by customer ID, the tokens must have been created with the merchantCustomerReference present. Please also note that if both cardKey and merchantCustomerReference are provided in the request the service will return tokens where both criteria match.

URL

/v3/token/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
cardKey The reference of the card token provided by Paythru Alpha-numeric characters
merchantCustomerReference The merchant's unique reference for the customer 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
cardKeyDetails Node containing details of each card token returned Alpha-numeric characters
cardKeyDetails > cardKeyDetail Node containing the details of the card token n/a
cardKeyDetails > cardKeyDetail > cardKey The reference of the card token Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardUniqueIdentifier A unique identifier for a card Numeric characters
cardKeyDetails > cardKeyDetail > merchantCustomerReference The merchant's reference of the customer to whom the card belongs Alpha-numeric characters
cardKeyDetails > cardKeyDetail > enabled Flag indicating if the card token is enabled - "1" if enabled, "0" if disabled "1" or "0"
cardKeyDetails > cardKeyDetail > card Node containing the card details of the card token n/a
cardKeyDetails > cardKeyDetail > card > cardDescription The name for the card Alpha-numeric characters
cardKeyDetails > cardKeyDetail > card > cardHolderName The cardholder's name as printed on their card Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardNumber The full primary account number (PAN) of the card. (Please node that the card number will be masked) Up to 16 numeric an "*" characters
cardKeyDetails > cardKeyDetail > card > cardExpiryMonth The month of the card's expiration date 2 numeric characters
cardKeyDetails > cardKeyDetail > card > cardExipryYear The year of the card's expiration date 4 numeric characters
cardKeyDetails > cardKeyDetail > card > cardType The type of card (e.g. "CREDIT", "DEBIT" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardScheme The scheme of card (e.g. "VISA", "MasterCard" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardBank The issuing bank of the card where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer Node containing details of the customer to whom the card belongs n/a
cardKeyDetails > cardKeyDetail > customer > customerTitle The customer's title (e.g. Mr) Up to 12 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerFirstName The customer's first name (e.g. John) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerSurname The customer's surname (e.g. Smith) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerEmail The email address of the customer Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerMobile The mobile phone number of the customer Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress Node containing details of the cardholder's address n/a
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols

Example Requests

HTTP Request
POST /v3/token/lookup/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 273
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff&
merchantCustomerReference=&
shaSignature=3c1eabc2f773a6ac7a32274e6aa61917d35804516df7258bcb981fa9e6c0ff84999e841734e1894ae527de5662a7a063c2d51ac493caf07f13b4b600ef96fdf

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 1285
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <cardKeyDetails>
  <cardKeyDetail>
   <cardKey>6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff</cardKey>
   <cardUniqueIdentifier>6683778953</cardUniqueIdentifier>
   <merchantCustomerReference/>
   <enabled>0</enabled>
   <card>
    <cardDescription>My Savings card</cardDescription>
    <cardholderName>John Smith</cardholderName>
    <cardNumber>444433******1111</cardNumber>
    <cardExpiryMonth>12</cardExpiryMonth>
    <cardExpiryYear>2015</cardExpiryYear>
    <cardType>CREDIT</cardType>
    <cardScheme/>
    <cardBank>paythru</cardBank>
   </card>
   <customer>
    <customerTitle>Mr</customerTitle>
    <customerFirstName>Bob</customerFirstName>
    <customerSurname>Marty</customerSurname>
    <customerEmail>bmatry@example.com</customerEmail>
    <customerMobile>0784561230</customerMobile>
    <customerTelephone>141998445220</customerTelephone>
   </customer>
   <cardholderAddress>
    <cardholderAddressPropertyName/>
    <cardholderAddressLine1>10 Downing Street</cardholderAddressLine1>
    <cardholderAddressLine2/>
    <cardholderAddressLine3/>
    <cardholderAddressTown>London</cardholderAddressTown>
    <cardholderAddressCounty/>
    <cardholderAddressPostcode>SW1A 2AA</cardholderAddressPostcode>
    <cardholderAddressCountry>UK</cardholderAddressCountry>
   </cardholderAddress>
  </cardKeyDetail>
 </cardKeyDetails>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 778
Content-Type: application/json

{
  "cardKeyDetails": {
    "0": {
      "cardKey": "6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff",
      "cardUniqueIdentifier": 6683778953,
      "merchantCustomerReference": null,
      "enabled": "0",
      "card": {
        "cardDescription":"My Savings card",
        "cardholderName": "John Smith",
        "cardNumber": "444433******1111",
        "cardExpiryMonth": "12",
        "cardExpiryYear": "2015",
        "cardType": "CREDIT",
        "cardScheme": null,
        "cardBank": "paythru"
      },
      "customer": {
        "customerTitle": "Mr",
        "customerFirstName": "Bob",
        "customerSurname": "Marty",
        "customerEmail": "bmatry@example.com",
        "customerMobile": "0784561230",
        "customerTelephone": "141998445220"
      },
      "cardholderAddress": {
        "cardholderAddressPropertyName": "",
        "cardholderAddressLine1": "10 Downing Street",
        "cardholderAddressLine2": "",
        "cardholderAddressLine3": "",
        "cardholderAddressTown": "London",
        "cardholderAddressCounty": "",
        "cardholderAddressPostcode": "SW1A 2AA",
        "cardholderAddressCountry": "UK"
      }
    }
  }
}

3.2 Enable method

Description

The enable method changes the state of a token from 'disabled' to 'enabled'. The method is called by providing the card token reference (cardKey) of the token to be enabled. Please note that if the enable method is called on a token that is already enabled, a successful response will be returned even though no changes were actually made.

URL

/v3/token/enable

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
cardKey The reference of the card token provided by Paythru Alpha-numeric 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
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 "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) 2 alpha characters

Examples

HTTP Request
POST /v3/token/enable/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 245
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff&
shaSignature=3c1eabc2f773a6ac7a32274e6aa61917d35804516df7258bcb981fa9e6c0ff84999e841734e1894ae527de5662a7a063c2d51ac493caf07f13b4b600ef96fdf

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 92
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <result>OK</result>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 15
Content-Type: application/json

{
  "result": "OK"
}

3.3 Disable method

Description

The disable method changes the state of a token from 'enabled' to 'disabled'. The method is called by providing the card token reference (cardKey) of the token to be disabled. Please note that if the disable method is called on a token that is already enabled, a successful response will be returned even though no changes were actually made.

URL

/v3/token/disable

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
cardKey The reference of the card token provided by Paythru Alpha-numeric 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
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 "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) 2 alpha characters

Examples

HTTP Request
POST /v3/token/disable/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 245
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff&
shaSignature=3c1eabc2f773a6ac7a32274e6aa61917d35804516df7258bcb981fa9e6c0ff84999e841734e1894ae527de5662a7a063c2d51ac493caf07f13b4b600ef96fdf

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 92
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <result>OK</result>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 15
Content-Type: application/json

{
  "result": "OK"
}

3.4 Delete method

Description

The delete method removes the storage of a token. The method is called by providing the card token reference (cardKey) of the token to be deleted. Please note that once a token has been deleted it may not be recovered.

URL

/v3/token/delete

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
cardKey The reference of the card token provided by Paythru Alpha-numeric 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
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 "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) 2 alpha characters

Examples

HTTP Request
POST /v3/token/disable/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 245
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff&
shaSignature=3c1eabc2f773a6ac7a32274e6aa61917d35804516df7258bcb981fa9e6c0ff84999e841734e1894ae527de5662a7a063c2d51ac493caf07f13b4b600ef96fdf

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 92
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <result>OK</result>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 15
Content-Type: application/json

{
  "result": "OK"
}

3.5 Update method

Description

The update method allows the details stored in a token to be updated. This method is ideal for use when expiration date of the card changes (for example when a replacement card is issued), or if the cardholder changes their address.

Any of the token detail parameters passed to this method will be updated even if the parameter has no value. Passing a parameter with no value will remove the current stored value. Only parameters that are to be updated should therefore be provided in the request. For example, if only the expiry date is to be changed, only the cardExpiryMonth and cardExpiryYear parameters (and the authentication parameters) should be provided.

Please ensure when updating a customer's address to ensure that all address fields are updated. For example, is the new address does not have an 'address line 3', it is suggested that the cardholderAddressLine3 parameter is provided with no value to ensure any values in the previous address are overwritten.

URL

/v3/token/updateCardKeyDetails

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
cardKey The reference of the card token provided by Paythru Alpha-numeric 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
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
customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAdressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardHolderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols
cardDescription The name for the card Up to 50 alpha numeric characters and symbols
cardholderName The cardholder's name as printed on their card. Up to 50 alpha numeric characters and symbols
cardExpiryMonth The month of the card's expiration date 2 numeric characters
cardExpiryYear The year of the card's expiration date 2 or 4 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
result "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) Alpha-numeric characters

Examples

HTTP Request
POST /v3/token/updateCardKeyDetails/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 490
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
cardKey=6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff&
cardholderAddressPropertyName=&
cardholderAddressLine1=10+Downing+Street&
cardholderAddressLine2=&
cardholderAddressLine3=&
cardholderAddressTown=London&
cardholderAddressCounty=&
cardholderAddressPostcode=SW1A+2AA&
cardholderAddressCountry=UK&
shaSignature=eff95e366e2039f0d6ecc0acd9bc06daba5ab75266d5effe7ace2f8708df042cb06e371a8b4ed6f119a69d8aa31a8f42698aecc4aade3f126fe72af5d1e3d39

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 92
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <result>OK</result>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 15
Content-Type: application/json

{
  "result": "OK"
}

3.6 Card create method

Description

The card create method of the API is used to create a new card token from a debit or credit card. The method may be used to support an account registration process in which customers may store their payment cards, or to store a payment card immediately after a payment is processed.

URL

/v3/token/create/xml

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
merchantCustomerReference The merchant's unique identifier for the customer Alpha-numeric characters
cardDescription The name of the card Alpha-numeric characters
cardholderName The cardholder's name as printed on their card. Alpha-numeric characters
cardNumber The full primary account number (PAN) of the card number with no spaces or separators. See Gateway API Appendix 5.4 for test card numbers. 13-19 numeric characters
cardExpiryMonth The month of the expiration date as shown on the card ("MM" format) 2 numeric characters
cardExpiryYear The year of the expiration date as shown on the card ("YY" format) 2 numeric characters
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
customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAdressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardHolderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols
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
cardKeyDetails Node containing details of each card token returned Alpha-numeric characters
cardKeyDetails > cardKeyDetail Node containing the details of the card token n/a
cardKeyDetails > cardKeyDetail > cardKey The reference of the card token Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardUniqueIdentifier A unique identifier for a card Numeric characters
cardKeyDetails > cardKeyDetail > merchantCustomerReference The merchant's reference of the customer to whom the card belongs Alpha-numeric characters
cardKeyDetails > cardKeyDetail > enabled Flag indicating if the card token is enabled - "1" if enabled, "0" if disabled "1" or "0"
cardKeyDetails > cardKeyDetail > card Node containing the card details of the card token n/a
cardKeyDetails > cardKeyDetail > card > cardDescription The name for the card Alpha-numeric characters
cardKeyDetails > cardKeyDetail > card > cardHolderName The cardholder's name as printed on their card Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardNumber The full primary account number (PAN) of the card. (Please node that the card number will be masked) Up to 16 numeric an "*" characters
cardKeyDetails > cardKeyDetail > card > cardExpiryMonth The month of the card's expiration date 2 numeric characters
cardKeyDetails > cardKeyDetail > card > cardExipryYear The year of the card's expiration date 4 numeric characters
cardKeyDetails > cardKeyDetail > card > cardType The type of card (e.g. "CREDIT", "DEBIT" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardScheme The scheme of card (e.g. "VISA", "MasterCard" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardBank The issuing bank of the card where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer Node containing details of the customer to whom the card belongs n/a
cardKeyDetails > cardKeyDetail > customer > customerTitle The customer's title (e.g. Mr) Up to 12 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerFirstName The customer's first name (e.g. John) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerSurname The customer's surname (e.g. Smith) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerEmail The email address of the customer Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerMobile The mobile phone number of the customer Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress Node containing details of the cardholder's address n/a
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols

Examples

HTTP Request
POST /v3/token/create/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 703
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
cardDescription=My+shopping+card&
cardholderName=MR+JOHN+SMITH&
cardNumber=4444333322221111&
cardExpiry=1215&
customerTitle=Mr&
customerFirstName=John&
customerSurname=Smith&
customerEmail=johnsmith%40example.com&
customerMobile=07770123456&
customerTelephone=01234123456&
cardholderAddressPropertyName=&
cardholderAddressLine1=Flat+12B&
cardholderAddressLine2=34+The+Avenue&
cardholderAddressLine3=&
cardholderAddressTown=Amersham&
cardholderAddressCounty=Buckinghamshire&
cardholderAddressPostcode=HP6+6GL&
cardholderAddressCountry=UK&
shaSignature=617345f579d890109daab584fb149b428c8bd83995ec86c3625e0ddecf58e79fc5b0c78c098d35807217d563d776d881341d96302f86da88d91fe1f51baebd9

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 1285
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <cardKeyDetails>
  <cardKeyDetail>
   <cardKey>6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff</cardKey>
   <cardUniqueIdentifier>6683778953</cardUniqueIdentifier>
   <merchantCustomerReference/>
   <enabled>0</enabled>
   <card>
    <cardDescription>My shopping card</cardDescription>
    <cardholderName>John Smith</cardholderName>
    <cardNumber>444433******1111</cardNumber>
    <cardExpiryMonth>12</cardExpiryMonth>
    <cardExpiryYear>2015</cardExpiryYear>
    <cardType>CREDIT</cardType>
    <cardScheme/>
    <cardBank>paythru</cardBank>
   </card>
   <customer>
    <customerTitle>Mr</customerTitle>
    <customerFirstName>John</customerFirstName>
    <customerSurname>Smith</customerSurname>
    <customerEmail>johnsmith@example.com</customerEmail>
    <customerMobile>07770123456</customerMobile>
    <customerTelephone>01234123456</customerTelephone>
   </customer>
   <cardholderAddress>
    <cardholderAddressPropertyName/>
    <cardholderAddressLine1>Flat 12B</cardholderAddressLine1>
    <cardholderAddressLine2>34 The Avenue</>
    <cardholderAddressLine3/>
    <cardholderAddressTown>Amersham</cardholderAddressTown>
    <cardholderAddressCounty>Buckinghamshire</>
    <cardholderAddressPostcode>HP6 6GL</cardholderAddressPostcode>
    <cardholderAddressCountry>UK</cardholderAddressCountry>
   </cardholderAddress>
  </cardKeyDetail>
 </cardKeyDetails>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 778
Content-Type: application/json

{
  "cardKeyDetails": {
    "0": {
      "cardKey": "6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff",
      "cardUniqueIdentifier": 6683778953,
      "merchantCustomerReference": null,
      "enabled": "0",
      "card": {
        "cardDescription": "My shopping card",
        "cardholderName": "John Smith",
        "cardNumber": "444433******1111",
        "cardExpiryMonth": "12",
        "cardExpiryYear": "2015",
        "cardType": "CREDIT",
        "cardScheme": null,
        "cardBank": "paythru"
      },
      "customer": {
        "customerTitle": "Mr",
        "customerFirstName": "John",
        "customerSurname": "Smith",
        "customerEmail": "johnsmith@example.com",
        "customerMobile": "07770123456",
        "customerTelephone": "01234123456"
      },
      "cardholderAddress": {
        "cardholderAddressPropertyName": "",
        "cardholderAddressLine1": "Flat 12B",
        "cardholderAddressLine2": "34 The Avenue",
        "cardholderAddressLine3": "",
        "cardholderAddressTown": "Amersham",
        "cardholderAddressCounty": "Buckinghamshire",
        "cardholderAddressPostcode": "HP6 6GL",
        "cardholderAddressCountry": "UK"
      }
    }
  }
}

3.7 Session create method

Description

The card create method of the API is used to create a new card token from card (and other personal) details provided within a Client POST session. The method may be used to support an account registration process in which customers may store their payment cards, or to store a payment card immediately after a payment is processed

URL

/v3/token/tokeniseSessionKey/xml

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
merchantCustomerReference The merchant's unique identifier for the customer Alpha-numeric characters
sessionKey The reference of an active Client POST session to be used. Alpha-numeric characters
cardDescription The name of the card Alpha-numeric characters
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
customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardholderAdressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardHolderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols
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
cardKeyDetails Node containing details of each card token returned Alpha-numeric characters
cardKeyDetails > cardKeyDetail Node containing the details of the card token n/a
cardKeyDetails > cardKeyDetail > cardKey The reference of the card token Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardUniqueIdentifier A unique identifier for a card Numeric characters
cardKeyDetails > cardKeyDetail > merchantCustomerReference The merchant's reference of the customer to whom the card belongs Alpha-numeric characters
cardKeyDetails > cardKeyDetail > enabled Flag indicating if the card token is enabled - "1" if enabled, "0" if disabled "1" or "0"
cardKeyDetails > cardKeyDetail > card Node containing the card details of the card token n/a
cardKeyDetails > cardKeyDetail > card > cardDescription The name for the card Alpha-numeric characters
cardKeyDetails > cardKeyDetail > card > cardHolderName The cardholder's name as printed on their card Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardNumber The full primary account number (PAN) of the card. (Please node that the card number will be masked) Up to 16 numeric an "*" characters
cardKeyDetails > cardKeyDetail > card > cardExpiryMonth The month of the card's expiration date 2 numeric characters
cardKeyDetails > cardKeyDetail > card > cardExipryYear The year of the card's expiration date 4 numeric characters
cardKeyDetails > cardKeyDetail > card > cardType The type of card (e.g. "CREDIT", "DEBIT" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardScheme The scheme of card (e.g. "VISA", "MasterCard" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardBank The issuing bank of the card where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer Node containing details of the customer to whom the card belongs n/a
cardKeyDetails > cardKeyDetail > customer > customerTitle The customer's title (e.g. Mr) Up to 12 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerFirstName The customer's first name (e.g. John) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerSurname The customer's surname (e.g. Smith) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerEmail The email address of the customer Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerMobile The mobile phone number of the customer Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress Node containing details of the cardholder's address n/a
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols

Examples

HTTP Request
POST /v3/token/tokeniseSessionKey/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 703
Content-Type: application/x-www-form-urlencoded

apiKey=qyc2o6hvYyGFcGEL3K&
apiPassword=83M3hWArBIsduSMGVa&
sessionKey=xxx;
shaSignature=617345f579d890109daab584fb149b428c8bd83995ec86c3625e0ddecf58e79fc5b0c78c098d35807217d563d776d881341d96302f86da88d91fe1f51baebd9

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK
Content-Length: 1285
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
 <cardKeyDetails>
  <cardKeyDetail>
   <cardKey>6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff</cardKey>
   <cardUniqueIdentifier>6683778953</cardUniqueIdentifier>
   <merchantCustomerReference/>
   <enabled>0</enabled>
   <card>
    <cardDescription>My shopping card</cardDescription>
    <cardholderName>John Smith</cardholderName>
    <cardNumber>444433******1111</cardNumber>
    <cardExpiryMonth>12</cardExpiryMonth>
    <cardExpiryYear>2015</cardExpiryYear>
    <cardType>CREDIT</cardType>
    <cardScheme/>
    <cardBank>paythru</cardBank>
   </card>
   <customer>
    <customerTitle>Mr</customerTitle>
    <customerFirstName>John</customerFirstName>
    <customerSurname>Smith</customerSurname>
    <customerEmail>johnsmith@example.com</customerEmail>
    <customerMobile>07770123456</customerMobile>
    <customerTelephone>01234123456</customerTelephone>
   </customer>
   <cardholderAddress>
    <cardholderAddressPropertyName/>
    <cardholderAddressLine1>Flat 12B</cardholderAddressLine1>
    <cardholderAddressLine2>34 The Avenue</>
    <cardholderAddressLine3/>
    <cardholderAddressTown>Amersham</cardholderAddressTown>
    <cardholderAddressCounty>Buckinghamshire</>
    <cardholderAddressPostcode>HP6 6GL</cardholderAddressPostcode>
    <cardholderAddressCountry>UK</cardholderAddressCountry>
   </cardholderAddress>
  </cardKeyDetail>
 </cardKeyDetails>
</paythruResponse>
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Length: 778
Content-Type: application/json

{
  "cardKeyDetails": {
    "0": {
      "cardKey": "6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff",
      "cardUniqueIdentifier": 6683778953,
      "merchantCustomerReference": null,
      "enabled": "0",
      "card": {
        "cardDescription": "My shopping card",
        "cardholderName": "John Smith",
        "cardNumber": "444433******1111",
        "cardExpiryMonth": "12",
        "cardExpiryYear": "2015",
        "cardType": "CREDIT",
        "cardScheme": null,
        "cardBank": "paythru"
      },
      "customer": {
        "customerTitle": "Mr",
        "customerFirstName": "John",
        "customerSurname": "Smith",
        "customerEmail": "johnsmith@example.com",
        "customerMobile": "07770123456",
        "customerTelephone": "01234123456"
      },
      "cardholderAddress": {
        "cardholderAddressPropertyName": "",
        "cardholderAddressLine1": "Flat 12B",
        "cardholderAddressLine2": "34 The Avenue",
        "cardholderAddressLine3": "",
        "cardholderAddressTown": "Amersham",
        "cardholderAddressCounty": "Buckinghamshire",
        "cardholderAddressPostcode": "HP6 6GL",
        "cardholderAddressCountry": "UK"
      }
    }
  }
}

3.8 Tokenise transaction key method

Description

The tokenise transaction key method of the API is used to create a new card token using data from a previous transaction conducted using Paythru’s APIs. The method is most commonly used to generate cardKeys from transactions made using Paythru’s Hosted Payment Pages (Enterprise API).

URL

/v3/token/tokeniseTransactionKey

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 A ‘transactionKey’ or ‘trans_key’ returned in response to a previous transaction request, within a callback notification, or appended to a success_url. Alpha-numeric characters
merchantCustomerReference The merchant's unique reference for the customer. 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
cardKeyDetails Node containing details of each card token returned Alpha-numeric characters
cardKeyDetails > cardKeyDetail Node containing the details of the card token n/a
cardKeyDetails > cardKeyDetail > cardKey The reference of the card token Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardUniqueIdentifier A unique identifier for a card Numeric characters
cardKeyDetails > cardKeyDetail > merchantCustomerReference The merchant's reference of the customer to whom the card belongs Alpha-numeric characters
cardKeyDetails > cardKeyDetail > enabled Flag indicating if the card token is enabled - "1" if enabled, "0" if disabled "1" or "0"
cardKeyDetails > cardKeyDetail > card Node containing the card details of the card token n/a
cardKeyDetails > cardKeyDetail > card > cardDescription The name for the card Alpha-numeric characters
cardKeyDetails > cardKeyDetail > card > cardHolderName The cardholder's name as printed on their card Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardNumber The full primary account number (PAN) of the card. (Please note that the card number will be masked) Up to 16 numeric and "*" characters
cardKeyDetails > cardKeyDetail > card > cardExpiryMonth The month of the card's expiration date 2 numeric characters
cardKeyDetails > cardKeyDetail > card > cardExipryYear The year of the card's expiration date 4 numeric characters
cardKeyDetails > cardKeyDetail > card > cardType The type of card (e.g. "CREDIT", "DEBIT" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardScheme The scheme of card (e.g. "VISA", "MasterCard" etc.) where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > card > cardBank The issuing bank of the card where resolved Alpha-numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer Node containing details of the customer to whom the card belongs n/a
cardKeyDetails > cardKeyDetail > customer > customerTitle The customer's title (e.g. Mr) Up to 12 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerFirstName The customer's first name (e.g. John) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerSurname The customer's surname (e.g. Smith) Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerEmail The email address of the customer Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerMobile The mobile phone number of the customer Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > customer > customerTelephone The telephone number of the user Up to 14 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress Node containing details of the cardholder's address n/a
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
cardKeyDetails > cardKeyDetail > cardholderAddress > cardholderAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols

Example Requests

HTTP Request
POST /v3/token/tokeniseTransactionKey/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 273
Content-Type: application/x-www-form-urlencoded 

apiKey=qyc2o6hvYyGFcGEL3K& apiPassword=83M3hWArBIsduSMGVa& transactionKey=4c20cd2fb46e6a53ea40c590365e2174& merchantCustomerReference=& shaSignature=3c1eabc2f773a6ac7a32274e6aa61917d35804516df7258bcb981fa9e6c0ff84999e841734e1894ae527de5662a7a063c2d51ac493caf07f13b4b600ef96fdf

Example Responses

HTTP Response (XML)
HTTP/1.1 200 OK 
Content-Length: 1285 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
    <cardKeyDetails>
        <cardKeyDetail>
            <cardKey>6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff</cardKey>
            <cardUniqueIdentifier>6683778953</cardUniqueIdentifier>
            <merchantCustomerReference/>
            <enabled>0</enabled>
            <card>
                <cardDescription>My Savings card</cardDescription>
                <cardholderName>John Smith</cardholderName>
                <cardNumber>444433******1111</cardNumber>
                <cardExpiryMonth>12</cardExpiryMonth>
                <cardExpiryYear>2015</cardExpiryYear>
                <cardType>CREDIT</cardType>
                <cardScheme/>
                <cardBank>paythru</cardBank>
            </card>
            <customer>
                <customerTitle>Mr</customerTitle>
                <customerFirstName>Bob</customerFirstName>
                <customerSurname>Marty</customerSurname>
                <customerEmail>bmatry@example.com</customerEmail>
                <customerMobile>0784561230</customerMobile>
                <customerTelephone>141998445220</customerTelephone>
            </customer>
            <cardholderAddress>
                <cardholderAddressPropertyName/>
                <cardholderAddressLine1>10 Downing Street</cardholderAddressLine1>
                <cardholderAddressLine2/>
                <cardholderAddressLine3/>
                <cardholderAddressTown>London</cardholderAddressTown>
                <cardholderAddressCounty/>
                <cardholderAddressPostcode>SW1A 2AA</cardholderAddressPostcode>
                <cardholderAddressCountry>UK</cardholderAddressCountry>
            </cardholderAddress>
        </cardKeyDetail>
    </cardKeyDetails>
</paythruResponse> 

HTTP Response (JSON)

HTTP/1.1 200 OK 
Content-Length: 778 
Content-Type: application/json 

{
    "cardKeyDetails": {
        "0": {
            "cardKey": "6bede8cf-7f8b-a5dc-e1b7-5d4cc3618fff",
            "cardUniqueIdentifier": 6683778953,
            "merchantCustomerReference": null,
            "enabled": "0",
            "card": {
                "cardDescription": "My Savings card",
                "cardholderName": "John Smith",
                "cardNumber": "444433******1111",
                "cardExpiryMonth": "12",
                "cardExpiryYear": "2015",
                "cardType": "CREDIT",
                "cardScheme": null,
                "cardBank": "paythru"
            },
            "customer": {
                "customerTitle": "Mr",
                "customerFirstName": "Bob",
                "customerSurname": "Marty",
                "customerEmail": "bmatry@example.com",
                "customerMobile": "0784561230",
                "customerTelephone": "141998445220"
            },
            "cardholderAddress": {
                "cardholderAddressPropertyName": "",
                "cardholderAddressLine1": "10 Downing Street",
                "cardholderAddressLine2": "",
                "cardholderAddressLine3": "",
                "cardholderAddressTown": "London",
                "cardholderAddressCounty": "",
                "cardholderAddressPostcode": "SW1A 2AA",
                "cardholderAddressCountry": "UK"
            }
        }
    }
}

4.0 Error Handling

If the server is unable to process a request, an error is thrown. The nature of the error is returned as an error code and error message in the expected response 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
108 Invalid card number
109 Invalid card expiry
121 This IP has been blocked for 1 minute because of too many failed attempts
122 This IP has been blocked for 5 minutes because of too many failed attempts
123 SHA signature could not be verified
125 Invalid merchant reference
144 No data sent to update the transaction
146 Invalid card key
147 Card key not found
148 No card key with the merchant customer reference
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

6.0 Revision History

Doc version Changes Published
0 First issue of v3 March 2015
1 Supports sending and returning a card description March 2015
2 Unique card identifier feature added March 2015
3 Added tokeniseTransactionKey method March 2020