Cards & Wallets · Your payment page · Advanced features · CardLock

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 Access PaySuite’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.

The example below tokenises the standard test card. The response returns the token to present to the payments API in place of the card number.

Tokenise card details
EndpointDefinition
POST /cardlock/createToken
Request body
{
  "publishableId": "Ihudyi6xTomATGMa5bluhQ",
  "pan": "9900000000005159",
  "cvv": "456"
}
cURL
curl -X POST "{targetEnvironmentPath}/cardlock/createToken" \
  -H "Content-Type: application/json" \
  -d '{
  "publishableId": "Ihudyi6xTomATGMa5bluhQ",
  "pan": "9900000000005159",
  "cvv": "456"
}'
Response
HTTP/1.1 200 OK

{
  "token": "TT_2gBBl8mbS_WIbfHuFgcSAg",
  "status": "S00",
  "message": "OK"
}
Notes:
  • The call carries no Authorization header. Your publishableId in the body is what identifies the account, which is why it is safe to call from a customer's device.
  • cvv is optional here, but send it when the customer has entered one — it cannot be added to the token later.
  • token is only present when status is S00; any other code means no token was created. See CardLock response codes and messages.
  • Code for additional response fields, which may be added to support 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.

See CardLock Tokens for how long a token remains valid and when a new one must be obtained.