Using the JSON REST API

This API outline is an extension to the CardLock product allowing merchant applications (e.g. mobile applications, third party systems such as IVR software) to obtain CardLock tokens from customer PAN and CV2 values at source to be subsequently processed by a merchant’s systems through Pay360’s payment APIs.

The information provided supplements the existing CardLock integration guide and assumes knowledge of the server-to-server payments API components of CardLock.

API Outline

The API is exposed using REST/JSON over HTTPS and is accessed by a POST to the URL defined below – request and response bodies (including error responses) are encoded in JSON with a content type of application/json. This pattern is supported on most platforms either out of the box or using additional software libraries.

Protocol and Endpoint Details

Transport: HTTPS

Service Endpoint: https://api.pay360.com/cardlock/createToken

Request Method: HTTP POST

Content Type: application/json

Tokenise Card Details Request


POST https://api.pay360.com/cardlock/createToken
Content-type: application/json
{
  "publishableId": "Ihudyi6xTomATGMa5bluhQ",
  "pan": "9900000000005159",
  "cvv": "456"
}

The request payload is a JSON encoded object, consisting of the following fields:

Name	Required	Description	Example	Specification
publishableId	Y	Publishable ID, as issued to you by Pay360. This must be associated with the Pay360 account you intend to process the subsequent transaction on.	Ihudyi6xTomATGMa5bluhQ	String
pan	Y	Card number	9900000000005159	String: 13 through 19 digits (inclusive) (0 through 9, no spaces)
cvv	N	CVV2/CVC2/CID	456	String: 3 or 4 digits (0 through 9, no spaces)

Tokenise Card Details Response


HTTP/1.1 200 OK
Content-type: application/json
{
  "token" : "TT_2gBBl8mbS_WIbfHuFgcSAg",
  "status" : "S00",
  "message" : "OK"
}

The response payload is a JSON encoded object, consisting of the following fields:

Name	Required	Description	Example	Specification
status	Y	Status code	S00	String: Letter, two digits. See Response Codes and Messages – CardLock.
message	Y	Status message	OK	String: Text message.
token	N	CardLock token	TT_2gBBl8mbS_WIbfHuFgcSAg	String: Alphanumeric.

The token value will be returned in the event that status is S00.
We advise clients that they should code their implementations to cope with additional fields,which may be added to facilitate other features.

Mobile App Integration Guidelines

The following section outlines guidelines for integrating the CardLock API into a mobile app.

Obtaining the Publishable ID

Your application should obtain the CardLock Publishable ID for use in the API over the air from your servers, it should not be bundled with your application.

This allows Publishable IDs to be re-issued without requiring a release of your mobile app.

Once an application has received a publishable ID it may cache it until an “A01 Unknown Publishable ID” response is received over the CardLock API after which it should retrieve an updated value from your server.

Calling CardLock API

Your mobile app should call the CardLock API over HTTPS using the JSON API above in order to exchange customer-entered card details for a CardLock token.

Calls should be made asynchronously to avoid blocking in the client.

The app should set a reasonable time out (suggested 5 seconds) and report an error if a response is not received in this time.

Receiving CardLock Token

Once your app has received a CardLock token this should be transmitted back to your server securely (e.g. using HTTPS) to process the payment.

Storing Data

Your app must not store the full PAN or CVV persistently or log these values back to your servers.

CardLock Tokens

CardLock tokens are single-use and time-limited:

Once a CardLock token has been presented to the Pay360 API it should be discarded, regardless of the outcome of the transaction.
If a payment is declined or rejected and you wish to re-attempt the transaction you must obtain a new token by prompting the customer to re-enter their card details
The token is valid for a limited time (20 minutes) – once you have obtained a token you should present it to a Pay360 payments API for payment promptly.
If you wish to store card details for subsequent transactions you can use CardLock to obtain the card details for the first payment, subsequent payments should use the existing card on file mechanism in Pay360 APIs.

On the Advanced Payments API you should use the merchant token obtained from the original
payment.

Developer Documents