Manage tokens

You can use the Checkout API to:

• Get a list of the shopper's stored payment details.
• Update stored payment details.
• Disable stored payment details.

List stored payment details

To see all the payment details saved for a shopper, make a POST /paymentMethods request including:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "countryCode": "GB",
  "amount": {
    "currency": "GBP",
    "value": 1000
  }
}

The storedPaymentMethods array in the response includes:

{
    "storedPaymentMethods": [
        {
            "brand": "visa",
            "expiryMonth": "10",
            "expiryYear": "2020",
            "holderName": "SHOPPER_NAME",
            "id": "8415890871952836",
            "recurringProcessingModel":"Subscription",
            ...
        }
    ]
}

• id: The storedPaymentMethodId value that you need to make payments with the shopper's stored payment details.

{
    "storedPaymentMethods": [
        {
            "brand": "visa",
            "expiryMonth": "10",
            "expiryYear": "2020",
            "holderName": "SHOPPER_NAME",
            "id": "8415890871952836",
            ...
        }
    ]
}

Update stored details

You can update the following fields without changing the storedPaymentMethodId of the stored payment details:

If the shopper has a new card number, make a /payments request to store new payment details and receive a new identifier.

To update the expiryMonth, expiryYear, or holderName, make a /payments request including:

Also include at least one of the fields you want to update:

For example, to update the cardholder's name in the previous example, make a /payments request including the required fields and paymentMethod.holderName:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "amount": {
    "currency": "GBP",
    "value": 0
  },
  "paymentMethod": {
      "storedPaymentMethodId":"8415890871952836",
      "holderName": "NEW_SHOPPER_NAME"
  },
  "shopperInteraction": "ContAuth"
}

Updates from card networks

Card networks (for example, Visa and Mastercard) also send updates to your shopper's payment details. The way these updates are handled depends on the Account Updater service you use.

• If you are using our Real Time Account Updater, you do not have to do anything to handle the updates from the card networks. The card details are automatically updated, and the token remains unchanged.
• If you are using our Batch Account Updater, then you will receive the updated card details in a batch result file. You then need to make a zero-value transaction with the updated card details.

Disable stored payment details

You can either delete one token with the shopper's stored payment details or all the shopper's stored payment details.

To delete a single token, make a DELETE /storedPaymentMethod request including:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "recurringDetailReference": "8313147988756818"
}

To delete the shopper's unique identifier and all the stored payment details, make a DELETE /storedPaymentMethod request including:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID"
}

See also

• Recurring API on API Explorer
• Account Updater