Real Time Account Updater

With our Real Time Account Updater, you can be informed of updates to shoppers' Visa, Mastercard, or Cartes Bancaires cards in real time.

When you submit a payment that is refused, our Real Time Account Updater instantly checks for updated card details. If there is an update, we immediately retry the payment with the updated card details. This all happens while the payment is being processed, and appears as a single transaction.

You can optionally receive the updated card details in the payment response. If you use Adyen Tokenization, the token storing the card details is updated automatically and the recurringDetailReference stays the same.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

1. Each time a payment request is declined, Adyen sends an account update request in real time.
2. When we receive the up-to-date billing information, we immediately retry the payment.
3. Optionally, you can receive card updates in the payment responses.
   You can use those new details to update your other systems, such as a CRM tool.
4. In the payment response, you get the account update status.
5. Optionally, you can include card updates in the Received Payment Details report.

Receive card updates in payment responses

To enable receiving changed card details in your payment response:

1. Log in to your Customer Area.

2. Go to Developers > Additional data.

   For a description and an example of additional data items, click on the row of the item.

3. Under Card, select the card details that you want to receive. We recommend selecting at least the following:

   • Card bin details
   • Card summary
   • Expiry date

4. Under Payment, select Realtime Account Updater Status.

5. Select Save configuration.

If the details of a card have changed, you receive this information as additionalData in the payment response.

If you are fully PCI compliant, you can also receive the full updated card number in the payment response.

Receive updated card numbers

If you are fully PCI compliant, you can receive the full updated card number in the payment response. The card number is provided as a JSON Web Encryption (JWE) encrypted value, that you need to decrypt using your private key.

To enable this functionality:

1. Contact our Support Team.
2. Provide them with an RSA public key with a length of 2048 bits. We use this key to encrypt card numbers that are provided in the payments response.

If the card number has changed, you additionally receive the following as additionalData in the payment response:

• realtimeAccountUpdaterSecureData: encrypted value representing the updated card number (or PAN).

Decrypt the card number

The realtimeAccountUpdaterSecureData value is encrypted using JWE, represented in JWE JSON Compact Serialization format. You need to decrypt this using your private key.

To decrypt the card number:

1. Parse the value.

2. Load your private key.

   You can identify which key should be used to decrypt the value using the kid (Key ID) header parameter.

3. Decrypt the value using a combination of:

   • Your private key.
   • Key algorithm: RSA_OAEP_256
   • Content encryption algorithm: AES_256_GCM

   The resulting plaintext is the shopper's updated card number (for example 45454547699084950).

Get account update statuses

When we perform the real time account update, we return a status, additionalData.realtimeAccountUpdaterStatus, indicating if and how the card details were updated. 

The realtime account updater status can be one of the following values:

Get a report on card updates

The Account Updater results report shows a summary of Account Updater results from a particular period of time. Use this report to check the outcomes and statuses of account updates, and get a summary of both Real Time Account Updater and Batch Account Updater results. You can also analyze the fees charged for the Account Updater.

For an overview of card updates on transaction level, you can add the Real Time Account Updater status column to the Received Payment Details report.

Testing

To test how different Real Time Account Updater scenarios work for your integration, use the following test card numbers and expiry dates in your payment request. The response will contain the corresponding status in the additionalData.realtimeAccountUpdaterStatus field.

The example below shows how to send a /payments request to test a scenario where the card has changed.

See also