Feature icon

Real Time Account Updater

When you submit a payment that is refused, our Real Time Account Updater instantly checks with Visa, Mastercard, or Cartes Bancaires 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.

You can only use our Real Time Account Updater services if all of the following conditions are met:

  • The amount specified in the payment is not zero.
  • The shopperInteraction parameter is set to ContAuth.
  • The payment does not contain a security code (CVC/CVV/CID).

Set up Real Time Account Updater

  1. Contact our Support Team to enable Real Time Account Updater.
    If you are fully PCI compliant, also let them know if you want to receive updated card numbers in your payment responses.

  2. Optionally enable receiving card updates in payment responses.
    You can use those new details to update your other systems, such as a CRM tool.

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.

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).

Real Time Account Updater 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:

Status Card Updated Description
CardChanged Yes The card number has changed.
CardExpiryChanged Yes The card expiration date has changed.
CloseAccount No The card has been closed by the issuer and is no longer valid. We will not automatically remove the card details. Disable the card details and ask the shopper to provide new card details.
ContactCardAccountHolder No (Visa only) The card was updated but the updated details are not in the Account updater service. Contact the cardholder to get their updated card information.
Unknown No (MasterCard only) We received an unknown value. In most cases, this means that Mastercard temporarily couldn't find the card in their system.

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.

Test and go live

You can only use our Real Time Account Updater services if all of the following conditions are met:

  • The amount specified in the payment is not zero.
  • The shopperInteraction parameter is set to ContAuth.
  • The payment does not contain a security code (CVC/CVV/CID).

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.

Card number Expiry month/year Status
5454 5476 9908 4950 03/2030 CardChanged
5454 5418 5840 6567 Any date except 03/2030 CardExpiryChanged
5454 5415 8031 1093 03/2030 CloseAccount
4111 1131 5971 2925 03/2030 ContactCardAccountHolder

If you are not fully PCI compliant and thus unable to process raw card data, add a prefix of test_ to the credentials. For example, use "encryptedCardNumber": "test_5454547699084950". This allows you to test using encrypted card details.

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

See also