CardLock allows you to use your own payment pages or mobile app without handling the card number or other sensitive data in your servers, reducing your exposure to PCI-DSS.
The CardLock service replaces the card number and security code (CVV2/CVC2/CID) with a single-use token that can be used in our payments API. We provide a JavaScript library which can perform this replacement automatically upon payment form submission, as well as a REST API for use in mobile apps, single-page applications and similar use cases.
You can use CardLock when processing payments (including deferred payments), account verification and payout transactions. CardLock tokens may only be used once, and are only valid for up to 20 minutes. Once the transaction is complete, you’ll receive a merchant token which allows for future re-use of the card.
CardLock needs to be enabled on your account, and we will issue you with a special credential (the publishable ID), which is used to access our tokenisation service. Please contact us if you would like this feature enabled.
This page describes how to send requests using a CardLock token in place of a card number. To get a CardLock token, you’ll need to integrate with one of the following:
- the CardLock JavaScript library for use on your web site
- the CardLock REST API for use in your mobile app or similar
See also: Payments, Authorisations, Account Verification and Payouts
API examples
Payment
POST /acceptor/rest/transactions/{instId}/payment
{
"transaction": {
"currency": "GBP",
"amount": "1000.00",
"description": "Merchant description",
"merchantRef": "TXN-0001"
},
"paymentMethod": {
"card": {
"cardLockToken": "TT_AbrAgCd4S_eWpV8HFI0FsQ",
"expiryDate": "1220",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"countryCode": "GBR"
}
},
"customer": {
"merchantRef": "CUST-0001",
"displayName": "John Smith"
}
}
HTTP/1.1 201
{
"processing": {
"authResponse": {
"statusCode": "00",
"acquirerName": "Barclays Merchant Services",
"message": "Approved - no action",
"authCode": "099119",
"gatewayReference": "111gbp98a87e7f3c305afFMee1000z00",
"gatewayCode": "000.000.000",
"gatewayMessage": "Transaction succeeded",
"avsAddressCheck": "FULL_MATCH",
"avsPostcodeCheck": "FULL_MATCH",
"cv2Check": "MATCHED",
"status": "AUTHORISED"
},
"route": "PAYON"
},
"paymentMethod": {
"registered": true,
"card": {
"cardToken": "MT_5nXK-imvRFWNmCwDinSPhA",
"cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
"new": false,
"cardType": "MC_DEBIT",
"cardUsageType": "DEBIT",
"cardScheme": "MASTERCARD",
"cardCategory": "DEBIT",
"maskedPan": "990000******0010",
"expiryDate": "1220",
"issuer": "PAY360 TESTING",
"issuerCountry": "GBR",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"country": "United Kingdom",
"countryCode": "GBR"
},
"paymentClass": "CARD",
"reuse": {
"storage": "NEW",
"agreement": "ADHOC",
"originalSchemeReference": "111gbp4745a1f0e0adddaFMee1000z00",
"receivedSchemeReference": "111gbp98a87e7f3c305afFMee1000z00"
}
},
"customFields": {
"fieldState": []
},
"customer": {
"id": "2176079",
"merchantRef": "CUST-0001"
},
"transaction": {
"transactionId": "10111564520",
"merchantRef": "TXN-0001",
"merchantDescription": "Merchant description",
"status": "SUCCESS",
"stage": "COMPLETE",
"type": "PAYMENT",
"amount": 1000,
"consumerSpend": 1000,
"currency": "GBP",
"transactionTime": "2019-12-12T19:20:38.801Z",
"receivedTime": "2019-12-12T19:20:38.801Z",
"customerInitiated": true
},
"outcome": {
"status": "SUCCESS",
"reasonCode": "S100",
"reasonMessage": "Authorised"
},
"trace": "ThX5V9VwgtydyPdc8cFbOqg",
"link": [
{
"rel": "transaction",
"href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10111564520"
}
]
}
Deferred payment
POST /acceptor/rest/transactions/{instId}/payment
{
"transaction": {
"currency": "GBP",
"amount": "1000.00",
"description": "Merchant description",
"merchantRef": "TXN-0002",
"deferred": true
},
"paymentMethod": {
"card": {
"cardLockToken": "TT_9EPng-tSTDOY6KKONWdABQ",
"expiryDate": "1220",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"countryCode": "GBR"
}
},
"customer": {
"merchantRef": "CUST-0001",
"displayName": "John Smith"
}
}
HTTP/1.1 201
{
"processing": {
"authResponse": {
"statusCode": "00",
"acquirerName": "Barclays Merchant Services",
"message": "Approved - no action",
"authCode": "073365",
"gatewayReference": "101gbp6a0a66d8a75f5a4FMee1000z00",
"gatewayCode": "000.000.000",
"gatewayMessage": "Transaction succeeded",
"avsAddressCheck": "FULL_MATCH",
"avsPostcodeCheck": "FULL_MATCH",
"cv2Check": "MATCHED",
"status": "AUTHORISED"
},
"route": "PAYON"
},
"paymentMethod": {
"registered": true,
"card": {
"cardToken": "MT_5nXK-imvRFWNmCwDinSPhA",
"cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
"new": false,
"cardType": "MC_DEBIT",
"cardUsageType": "DEBIT",
"cardScheme": "MASTERCARD",
"cardCategory": "DEBIT",
"maskedPan": "990000******0010",
"expiryDate": "1220",
"issuer": "PAY360 TESTING",
"issuerCountry": "GBR",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"country": "United Kingdom",
"countryCode": "GBR"
},
"paymentClass": "CARD",
"reuse": {
"storage": "NEW",
"agreement": "ADHOC",
"originalSchemeReference": "111gbp4745a1f0e0adddaFMee1000z00",
"receivedSchemeReference": "101gbp6a0a66d8a75f5a4FMee1000z00"
}
},
"customFields": {
"fieldState": []
},
"customer": {
"id": "2176079",
"merchantRef": "CUST-0001"
},
"transaction": {
"transactionId": "10111564535",
"deferred": true,
"merchantRef": "TXN-0002",
"merchantDescription": "Merchant description",
"status": "SUCCESS",
"stage": "AUTHORISATION",
"type": "PREAUTH",
"amount": 1000,
"consumerSpend": 0,
"currency": "GBP",
"transactionTime": "2019-12-12T20:08:58.618Z",
"receivedTime": "2019-12-12T20:08:58.618Z",
"customerInitiated": true
},
"outcome": {
"status": "SUCCESS",
"reasonCode": "S100",
"reasonMessage": "Authorised"
},
"trace": "T0YPsGk4YvYO9Id6ZFPZmgg",
"link": [
{
"rel": "transaction",
"href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10111564535"
}
]
}
Account verification
POST /acceptor/rest/transactions/{instId}/verify
{
"transaction": {
"currency": "GBP",
"description": "Merchant description",
"merchantRef": "TXN-0003"
},
"paymentMethod": {
"card": {
"cardLockToken": "TT_pOWtzymzSP69xyXi4jvpLA",
"expiryDate": "1220",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"countryCode": "GBR"
}
},
"customer": {
"merchantRef": "CUST-0001",
"displayName": "John Smith"
},
"verification": {
"acquirerPaymentMethod": true
}
}
HTTP/1.1 201
{
"processing": {
"authResponse": {
"statusCode": "00",
"acquirerName": "Barclays Merchant Services",
"message": "Approved - no action",
"authCode": "091358",
"gatewayReference": "101gbp94ce38d9628d6f6FMeeeeeeee0",
"gatewayCode": "000.000.000",
"gatewayMessage": "Transaction succeeded",
"avsAddressCheck": "FULL_MATCH",
"avsPostcodeCheck": "FULL_MATCH",
"cv2Check": "MATCHED",
"status": "AUTHORISED"
},
"route": "PAYON"
},
"paymentMethod": {
"registered": true,
"card": {
"cardToken": "MT_5nXK-imvRFWNmCwDinSPhA",
"cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
"new": false,
"cardType": "MC_DEBIT",
"cardUsageType": "DEBIT",
"cardScheme": "MASTERCARD",
"cardCategory": "DEBIT",
"maskedPan": "990000******0010",
"expiryDate": "1220",
"issuer": "PAY360 TESTING",
"issuerCountry": "GBR",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"country": "United Kingdom",
"countryCode": "GBR"
},
"paymentClass": "CARD",
"reuse": {
"storage": "NEW",
"agreement": "ADHOC",
"originalSchemeReference": "111gbp4745a1f0e0adddaFMee1000z00",
"receivedSchemeReference": "101gbp94ce38d9628d6f6FMeeeeeeee0"
}
},
"customFields": {
"fieldState": []
},
"customer": {
"id": "2176079",
"merchantRef": "CUST-0001"
},
"transaction": {
"transactionId": "10111564537",
"merchantRef": "TXN-0003",
"merchantDescription": "Merchant description",
"status": "SUCCESS",
"stage": "AUTHORISATION",
"type": "VERIFY",
"currency": "GBP",
"transactionTime": "2019-12-12T20:13:35.505Z",
"receivedTime": "2019-12-12T20:13:35.505Z",
"customerInitiated": true
},
"outcome": {
"status": "SUCCESS",
"reasonCode": "S100",
"reasonMessage": "Authorised"
},
"trace": "TRCwIoQVFn1_rG4vZL-mdnA",
"link": [
{
"rel": "transaction",
"href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10111564537"
}
]
}
Payout
POST /acceptor/rest/transactions/{instId}/payout
{
"transaction": {
"currency": "GBP",
"amount": "1000.00",
"description": "Merchant description",
"merchantRef": "TXN-0004"
},
"paymentMethod": {
"card": {
"cardLockToken": "TT_4BgN6VisSsmsfxZNu05KhQ",
"expiryDate": "1220",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"countryCode": "GBR"
}
},
"customer": {
"merchantRef": "CUST-0001",
"displayName": "John Smith"
}
}
HTTP/1.1 201
{
"processing": {
"authResponse": {
"statusCode": "00",
"acquirerName": "Barclays Merchant Services",
"message": "Approved - no action",
"authCode": "025223",
"gatewayReference": "121gbp18347476bc8d919FMee1000z00",
"gatewayCode": "000.000.000",
"gatewayMessage": "Transaction succeeded",
"avsAddressCheck": "FULL_MATCH",
"avsPostcodeCheck": "FULL_MATCH",
"cv2Check": "MATCHED",
"status": "AUTHORISED"
},
"route": "PAYON"
},
"paymentMethod": {
"registered": true,
"card": {
"cardToken": "MT_5nXK-imvRFWNmCwDinSPhA",
"cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
"new": false,
"cardType": "MC_DEBIT",
"cardUsageType": "DEBIT",
"cardScheme": "MASTERCARD",
"cardCategory": "DEBIT",
"maskedPan": "990000******0010",
"expiryDate": "1220",
"issuer": "PAY360 TESTING",
"issuerCountry": "GBR",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"country": "United Kingdom",
"countryCode": "GBR"
},
"paymentClass": "CARD"
},
"customFields": {
"fieldState": []
},
"customer": {
"id": "2176079",
"merchantRef": "CUST-0001"
},
"transaction": {
"transactionId": "10111564539",
"merchantRef": "TXN-0004",
"merchantDescription": "Merchant description",
"status": "SUCCESS",
"stage": "COMPLETE",
"type": "PAYOUT",
"amount": 1000,
"consumerSpend": 1000,
"currency": "GBP",
"transactionTime": "2019-12-12T20:15:41.781Z",
"receivedTime": "2019-12-12T20:15:41.781Z"
},
"outcome": {
"status": "SUCCESS",
"reasonCode": "S100",
"reasonMessage": "Authorised"
},
"trace": "TtMZckIIeq0nIi8sMNId8bQ",
"link": [
{
"rel": "transaction",
"href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10111564539"
}
]
}
API request
endpoint: see specific documentation for each request type
method: POST
summary: process transaction using CardLock token
parameters: see specific documentation for each request type
request body:
| { | ||
| … | ||
| paymentMethod { | ||
| … | ||
| card { | ||
| cardLockToken | string Mandatory CardLock token |
|
| expiryDate | string Mandatory Expiry date for the card (MMYY) |
|
| cv2 | string Conditional Card security code (CVV2/CVC2/CID/CSC) If the CardLock token is generated with this value (i.e. you specify a cvvElementId or provide the cvv value), this may be omitted and the value in the token will be used. Otherwise, you may provide the security code here if you collect it from the cardholder separately. If the token was generated with a value and this field is also provided, then the values must match, or the request will fail. If you do not provide a security code, either as part of the token or in this field, then your account configuration will determine whether or not the request is rejected. |
|
| cardHolderName | string Cardholder name, as printed on the card |
|
| startDate | string Start date for the card, where available (MMYY) |
|
| issueNumber | string Issue number for the card, where applicable |
|
| nickname | string Customer’s nickname for the card |
|
| defaultCard | boolean Indicates whether the card should become the customer’s default card |
|
| } | ||
| … | ||
| } | ||