Card Tokenisation API

Version 3

Back to Developers

Card Tokenisation API

Version 3

1.0 Introduction

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

The integration options include both 'direct' methods where Paythru simply process payment details captured and submitted by the merchant as well as 'hosted' methods where Paythru host the customer facing interface and process the details provided by the customer. The 'direct' integration methods ('Gateway' and "Client POST" APIs) offer the further integration option of card tokenisation.

Card Tokenisation provides the merchant with the ability effectively 'store' the customer's payment card details, but without the PCI DSS compliance burden of storing the card's PAN (Primary Account Number). The merchant may then offer the stored card for use by the customer when they return, to avoid them having the enter the card details again. Whenever customer's card details are submitted to Paythru (for example during payment or account registration processes), Paythru can store the card details, and return a reference to the merchant along with some masked particulars of the card. These details (known as the card token) may be submitted at a later date by the merchant in substitution of raw card details.

This API provides methods for managing card tokens. It supports the following activities:

  • Querying tokens (Querying the details stored in a token, or return all customer tokens)
  • Disabling tokens (Preventing a token from being used)
  • Enabling tokens (Enabling a disabled token)
  • Deleting tokens (Deleting a token completely)
  • Updating tokens (Updating the details stored within a token e.g. expiry date)
  • Creating tokens (Creating a new token at a time other than payment)

Please note that this API does not enable merchants to perform transaction with a card token. For transacting with a card token, please refer to the Paythru Gateway API. Please also note that the Create Token method in this API requires the merchant to submit the customer's card details from their servers, requiring them to certified to the appropriate level of PCI DSS compliance. Please refer to the Paythru Client POST API for a method of creating card token without exposure to the unmasked card details.

1.1 Scope

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

1.2 Audience

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

2.0 API Overview

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

2.1 API Requests

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

https://ws.paythru.com/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:

https://ws.paythru.com/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:

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

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

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

Arrange parameters in alphabetical order by parameter name...

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

https://ws.paythru.com/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

https://ws.paythru.com/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

https://ws.paythru.com/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

https://ws.paythru.com/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

https://ws.paythru.com/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
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

https://ws.paythru.com/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

https://ws.paythru.com/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
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" } } } }

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

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