WHen you store your shopper's payment details with Adyen, you can use our Checkout API to manage the lifecycle of your tokens to ensure that the stored payment details remain up-to-date, so that you can continue to offer your shopper's a smooth payment experiences.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | An online payments integration. |
| API credential roles | Make sure that you have the following role(s):
|
| Webhooks | Subscribe to the Recurring tokens life cycle events webhook. |
| Setup steps | Before you begin:
|
How it works
After you have created tokens, you can use the Checkout API to:
- Get a list of the shopper's stored payment details.
- Update stored payment details.
- Delete stored payment details.
When a token is updated, or deleted, you get notified with the Tokenization webhooks.
List stored payment details
To see all the payment details stored for a shopper, make a GET /storedPaymentMethods request including the following query parameters:
| Query parameter | Description |
|---|---|
merchantAccount |
Your merchant account name. |
shopperReference |
Your unique identifier for the shopper. |
The storedPaymentMethods array in the response includes:
| Parameter | Description |
|---|---|
id |
The storedPaymentMethodId value that you need to make payments with the shopper's stored payment details. |
supportedRecurringProcessingModels |
Defines the type of recurring payment that the stored payment details can be used for. Possible values:
|
Update stored details
On Checkout API v70 and later, updating stored details with an API request requires additional configuration on our side. Reach out to our Support Team to discuss your eligibility.
You can update the following fields without changing the storedPaymentMethodId of the stored payment details:
| Field | Description |
|---|---|
expiryMonth |
The expiry month. |
expiryYear |
The expiry year. |
holderName |
The cardholder's name. |
billingAddress |
The cardholder's address. |
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, holderName, or billingAddress, make a /payments request including:
| Parameter | Description |
|---|---|
amount.value |
0 |
storedPaymentMethodId |
The token with the stored payment details. |
shopperReference |
Your unique identifier for the shopper. |
merchantAccount |
Your merchant account name. |
shopperInteraction |
Defines the type of shopper interaction that the stored payment details can be used for. |
recurringProcessingModel |
Defines the type of recurring payment that the stored payment details can be used for. |
reference |
The reference to uniquely identify a payment |
Also include at least one of the fields you want to update:
| Parameter | Description |
|---|---|
expiryMonth |
The expiry month. |
expiryYear |
The expiry year. |
holderName |
The cardholder's name. |
For example, to update the cardholder name, make a /payments request including the required fields and paymentMethod.holderName:
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.
Delete stored payment details
You can delete a single token by its identifier, which is returned when you create a token. Alternatively, to find all tokens for a given shopper, you can list stored payment details and get the id from the relevant item in the storedPaymentMethods array.
To delete the token, make a DELETE /storedPaymentMethods/{storedPaymentMethodId} request including the following parameters:
| Parameter name | Parameter type | Description |
|---|---|---|
storedPaymentMethodId |
Path parameter | The unique identifier for the token you want to delete. |
merchantAccount |
Query parameter | Your merchant account name. |
shopperReference |
Query parameter | Your unique identifier for the shopper. |
After you delete payment details stored with Adyen, you must also delete any remaining shopper details from your servers.
Receive token lifecycle webhooks
While you manage tokens, you can stay informed of status changes to your tokens with the Tokenization webhooks. Enable the Recurring tokens life cycle events webhooks in your Customer Area to receive these webhooks.
This webhook includes:
data.storedPaymentMethodId: the ID of the token that was created, updated, or disabled.data.shopperReference:: Your unique shopper reference. Use this to associate the shopper with the token.eventId: ThepspReferencefor the payment made to store the shopper's payment details.-
type: the type of webhook. The table below lists the possible values.typeDescription recurring.token.created A new token was created. recurring.token.disabled A token was disabled, this can happen when: - You delete stored payment details.
- A third-party disables the payment details.
recurring.token.updated The stored details for a token were updated. You can initiate the update, but stored details can also be updated by, for example, card networks. recurring.token.alreadyExisting A create or update operation was attempted with details that match an already existing token. The storedPaymentMethodIdfield contains the ID of the existing token.
For example, when you delete a token, you get a webhook that looks like the following: