Saved payment methods
Avoid asking customers to re-enter their card details by storing payment methods as merchant tokens and reusing them for later transactions.
When a customer's first API payment completes successfully, we return a cardToken and a customer reference. You can use either one in place of the card's Primary Account Number (PAN) on a future Payment, Authorisation or Payout request.
A customer can have multiple registered cards. You can submit a transaction using a specific merchant token, or use the customer's default card by providing their customer reference. Merchant tokens differ from CardLock tokens, which replace raw card details while they are transmitted to us.
Visa and Mastercard apply requirements to storing and reusing payment credentials, including tokenised card details. We automatically classify transactions when they issue or use a merchant token. Review the Stored Credentials Framework to confirm that the default classification is correct and to learn how to override it when necessary.
Pay with a merchant token
Submit the token in paymentMethod.cardToken.token. You can also provide the card's CV2 and update its nickname or expiry date in cardUpdates. The customer reference identifies the customer who owns the token.
Submit payment with a merchant token
POST /acceptor/rest/transactions/{instId}/payment{
"transaction": {
"currency": "GBP",
"amount": 1000.0,
"description": "Sample Transaction",
"merchantRef": "mer_txn_1234556",
"commerceType": "MOTO",
"channel": "WEB"
},
"paymentMethod": {
"cardToken": {
"token": "hJzbc9ccR9CHLlita5g5Jg",
"cv2": "111",
"cardUpdates": {
"nickname": "John",
"expiryDate": "0130"
}
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"countryCode": "GBR"
}
},
"customer": {
"merchantRef": "mer_cust_131241413"
}
}curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/payment" \
-u "{apiUser}:{apiPassword}" \
-H "Content-Type: application/json" \
-d '{
"transaction": {
"currency": "GBP",
"amount": 1000.0,
"description": "Sample Transaction",
"merchantRef": "mer_txn_1234556",
"commerceType": "MOTO",
"channel": "WEB"
},
"paymentMethod": {
"cardToken": {
"token": "hJzbc9ccR9CHLlita5g5Jg",
"cv2": "111",
"cardUpdates": {
"nickname": "John",
"expiryDate": "0130"
}
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"countryCode": "GBR"
}
},
"customer": {
"merchantRef": "mer_cust_131241413"
}
}'HTTP/1.1 201
{
"processing": {
"authResponse": {
"statusCode": "00",
"message": "ACQUIRER OK",
"authCode": "100000",
"gatewayReference": "9518952499526614-PASS",
"gatewayCode": "1",
"gatewayMessage": "ACCEPTED",
"avsAddressCheck": "NOT_MATCHED",
"avsPostcodeCheck": "NOT_MATCHED",
"cv2Check": "MATCHED",
"status": "AUTHORISED"
},
"route": "MCPE"
},
"paymentMethod": {
"card": {
"cardToken": "hJzbc9ccR9CHLlita5g5Jg",
"new": false,
"cardType": "VISA_DEBIT",
"cardUsageType": "DEBIT",
"cardScheme": "VISA",
"maskedPan": "444433******1111",
"expiryDate": "0130",
"issuer": "Lloyds",
"issuerCountry": "GBR",
"cardHolderName": "John Smith",
"cardNickname": "John"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 1AA",
"country": "United Kingdom",
"countryCode": "GBR"
},
"paymentClass": "CARD"
},
"customer": {
"id": "10501",
"merchantRef": "mer_cust_131241413"
},
"transaction": {
"transactionId": "13502877397",
"merchantRef": "mer_txn_1234556",
"status": "SUCCESS",
"type": "PAYMENT",
"amount": 1000,
"consumerSpend": 1000,
"currency": "GBP",
"transactionTime": "2014-01-06T17:12:25.828Z",
"receivedTime": "2014-01-06T17:12:25.828Z",
"channel": "WEB"
},
"outcome": {
"status": "SUCCESS",
"reasonCode": "S100",
"reasonMessage": "Authorised"
}
}Pay with the customer's default card
When a customer has multiple registered cards, use paymentMethod.fromCustomer to charge the default card. Supply the customer's merchantRef and include the CV2 when it is available.
Payment using default card for an existing customer
POST /acceptor/rest/transactions/{instId}/payment{
"transaction": {
"currency": "GBP",
"amount": 25.00,
"merchantRef": "TXN-0003",
"description": "Sample Payment",
"commerceType": "ECOM"
},
"customer": {
"merchantRef": "CUST-0001",
"ip": "185.161.165.20"
},
"paymentMethod": {
"fromCustomer": {
"cv2": "123"
}
}
}curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/payment" \
-u "{apiUser}:{apiPassword}" \
-H "Content-Type: application/json" \
-d '{
"transaction": {
"currency": "GBP",
"amount": 25.00,
"merchantRef": "TXN-0003",
"description": "Sample Payment",
"commerceType": "ECOM"
},
"customer": {
"merchantRef": "CUST-0001",
"ip": "185.161.165.20"
},
"paymentMethod": {
"fromCustomer": {
"cv2": "123"
}
}
}'HTTP/1.1 201 Created
{
"processing": {
"model": "MANAGE",
"authResponse": {
"statusCode": "00",
"acquirerName": "Barclays Merchant Services",
"message": "AUTH CODE:572009",
"authCode": "572009",
"gatewayReference": "a689a7919a629904ddd164209ba78894",
"gatewayMessage": "AUTH CODE:572009",
"avsAddressCheck": "FULL_MATCH",
"avsPostcodeCheck": "FULL_MATCH",
"cv2Check": "MATCHED",
"status": "AUTHORISED"
},
"route": "CPE"
},
"paymentMethod": {
"registered": true,
"card": {
"cardToken": "MT_QXG4ltszTiyiz1nWbQydnA",
"cardFingerprint": "l313hfHapXJiLXyROD3X6P75k9E=",
"new": false,
"cardType": "VISA_DEBIT",
"cardUsageType": "DEBIT",
"cardScheme": "VISA",
"cardCategory": "DEBIT",
"maskedPan": "990200******0018",
"expiryDate": "1229",
"issuer": "PAY360 TESTING",
"issuerCountry": "GBR",
"cardHolderName": "John Smith"
},
"billingAddress": {
"line1": "1 Some Street",
"city": "Metropolis",
"postcode": "AA1 2BB",
"country": "United Kingdom",
"countryCode": "GBR"
},
"paymentClass": "CARD",
"reuse": {
"storage": "EXISTING",
"agreement": "ADHOC",
"originalSchemeReference": "XWM3I9SBV3ORCO",
"receivedSchemeReference": "699VJDIILOHYP4"
}
},
"customFields": {
"fieldState": []
},
"customer": {
"id": "2453687",
"merchantRef": "CUST-0001"
},
"transaction": {
"transactionId": "10213520966",
"merchantRef": "TXN-0003",
"merchantDescription": "Sample Payment",
"status": "SUCCESS",
"stage": "COMPLETE",
"type": "PAYMENT",
"amount": 25,
"consumerSpend": 25,
"currency": "GBP",
"transactionTime": "2024-09-02T19:26:25.953+01:00",
"receivedTime": "2024-09-02T19:26:25.953+01:00",
"customerInitiated": true
},
"outcome": {
"status": "SUCCESS",
"reasonCode": "S100",
"reasonMessage": "Authorised"
},
"trace": "TPUoVKGedfrLUvFZCiTKB1Q",
"link": [
{
"href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10213520966",
"rel": "transaction"
}
]
}The same token and customer-reference patterns can be used for Authorisation and Payout requests by sending the corresponding transaction request instead of a Payment request.
To list, retrieve, update and remove the payment methods saved against a customer, see Manage Customers.