Manage tokens

Your shoppers may need to update the payment methods they saved with you, or request you to remove a previously saved payment detail. You can also look up a particular shopper's stored payment details.

List saved payment details

To see all the payment details saved for a shopper, make a POST call to /paymentMethods and specify shopperReference and merchantAccount.

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

The storedPaymentMethods array in the response includes the shopper's saved payment details. The id field holds the recurringDetailReference (storedPaymentMethodId for API v49 and later) value that you need to make payments with the shopper's saved payment details.

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

Update saved details

Your shoppers can request changes to their saved payments details. The details associated with a token are card number, expiry month and year of the card, and the cardholder name. You can update the expiryMonth, expiryYear, and holderName of a card. The token remains unchanged when you update these details. If the shopper sends in a new card number, you need to save it as a new token.

To update the expiryMonth, expiryYear, or holderName, make a zero-value transaction with the recurringDetailReference (storedPaymentMethodId for API v49 and later) and include the values of the fields you want to update.

For example, to update the holder name of the card in the previous example, make a POST call to /payments and specify shopperReference, merchantAccount, shopperInteraction and the new 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.

Remove stored payment details

A shopper may request to delete their saved details for a certain payment method or leave your platform entirely. You can delete the tokens for your shopper's saved payment details with a /disable call.

To remove a single token, provide your merchantAccount, the shopperReference, and the recurringDetailReference you want to disable.

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

To remove a shopper and all their saved details, provide your merchantAccount and the shopperReference you want to disable.

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

See also

• Recurring API on API Explorer
• Account Updater