--- title: "Real Time Account Updater" url: "https://docs.adyen.com/online-payments/account-updater/real-time-account-updater" source_url: "https://docs.adyen.com/online-payments/account-updater/real-time-account-updater.md" canonical: "https://docs.adyen.com/online-payments/account-updater/real-time-account-updater" last_modified: "2026-05-13T13:16:00+02:00" language: "en" --- # Real Time Account Updater [View source](/online-payments/account-updater/real-time-account-updater.md) 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](/online-payments/tokenization), the token storing the card details is updated automatically and the `storedPaymentMethodId` stays the same. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [online payments integration using the Advanced flow](/online-payments/build-your-integration#advanced-flow-three-api-requests). | | **Limitations** | 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). | | **Setup steps** | Before you begin:- Ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable Real Time Account Updater. If you are fully PCI compliant, also let them know if you want to receive [updated card numbers](#updated-card-number) in your payment responses. - Optionally, enable [receiving card updates in payment responses](#receive-card-updates-in-payment-response). | ## 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](#receive-card-updates-in-payment-response).\ 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](#realtime-account-updater-statuses). 5. Optionally, you can [include card updates](#get-a-report-on-card-updates) in the [Received Payment Details report](/reporting/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](https://ca-live.adyen.com/). 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. **Changed card details in payment response** ```json { additionalData: { expiryDate: "3/2030", realtimeAccountUpdaterStatus: "CardChanged", cardSummary: "1111", cardSchemeCommercial: "true", cardPaymentMethod: "visa", cardIssuingBank: "Bank of America", cardIssuingCountry: "US", cardIssuingCurrency: "USD", cardBin: "411111", fundingSource: "CREDIT" } } ``` If you are [fully PCI compliant](/development-resources/pci-dss-compliance-guide), you can also receive the full [updated card number](#updated-card-number) in the payment response. ## Receive updated card numbers If you are [fully PCI compliant](/development-resources/pci-dss-compliance-guide), you can receive the full updated card number in the payment response. The card number is provided as a [JSON Web Encryption](https://tools.ietf.org/html/rfc7516#section-3) (JWE) encrypted value, that you need to [decrypt](#decrypt-the-card-number) using your private key. To enable this functionality: 1. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). 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](/get-started-with-adyen/adyen-glossary/#card-number-pan)). **Encrypted changed card number in payment response** ```json { additionalData: { realtimeAccountUpdaterStatus: "CardChanged", realtimeAccountUpdaterSecureData: "eyJhbGciOiJSU0EtT0FF...", expiryDate: "3/2030", cardSummary: "1111", cardSchemeCommercial: "true", cardPaymentMethod: "visa", cardIssuingBank: "Bank of America", cardIssuingCountry: "US", cardIssuingCurrency: "USD", fundingSource: "CREDIT" } } ``` #### Decrypt the card number The `realtimeAccountUpdaterSecureData` value is encrypted using JWE, represented in JWE [JSON Compact Serialization format](https://tools.ietf.org/html/rfc7516#section-7.1). 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](https://tools.ietf.org/html/rfc7516#appendix-A.4.4). 3. [Decrypt the value](https://tools.ietf.org/html/rfc7516#section-5.2) 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: | 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. | | **NoChange** | No | The card details have not changed. | ## Get a report on card updates The [Account Updater results report](/reporting/account-updater-results) 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](/reporting/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. | 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](/development-resources/test-cards-and-credentials/test-card-numbers#test-encrypted-card-details). The example below shows how to send a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to test a scenario where the card has changed. **Test card change scenario** #### curl ```bash curl https://checkout-test.adyen.com/v68/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "reference":"YOUR_ORDER_NUMBER", "shopperInteraction": "ContAuth", "amount":{ "currency":"EUR", "value":1000 }, "paymentMethod": { "type": "scheme", "encryptedCardNumber": "test_5454547699084950", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030" } }' ``` #### Java ```java // Adyen Java API Library v25.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the live environment, additionally include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) Amount amount = new Amount() .currency("EUR") .value(1000L); CardDetails cardDetails = new CardDetails() .encryptedCardNumber("test_5454547699084950") .encryptedExpiryYear("test_2030") .encryptedExpiryMonth("test_03") .type(CardDetails.TypeEnum.SCHEME); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .shopperInteraction(PaymentRequest.ShopperInteractionEnum.CONTAUTH) .paymentMethod(new CheckoutPaymentMethod(cardDetails)); // Make the API call PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php // Adyen PHP API Library v17.4.0 use Adyen\Client; use Adyen\Environment; use Adyen\Model\Checkout\Amount; use Adyen\Model\Checkout\CheckoutPaymentMethod; use Adyen\Model\Checkout\PaymentRequest; use Adyen\Service\Checkout\PaymentsApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); // For the live environment, additionally include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $checkoutPaymentMethod = new CheckoutPaymentMethod(); $checkoutPaymentMethod ->setEncryptedCardNumber("test_5454547699084950") ->setEncryptedExpiryYear("test_2030") ->setEncryptedExpiryMonth("test_03") ->setType("scheme"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setShopperInteraction("ContAuth") ->setPaymentMethod($checkoutPaymentMethod); $requestOptions['idempotencyKey'] = 'UUID'; // Make the API call $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v14.4.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the live environment, additionally include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Amount amount = new Amount { Currency = "EUR", Value = 1000 }; CardDetails cardDetails = new CardDetails { EncryptedCardNumber = "test_5454547699084950", EncryptedExpiryYear = "test_2030", EncryptedExpiryMonth = "test_03", Type = CardDetails.TypeEnum.Scheme }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", ShopperInteraction = PaymentRequest.ShopperInteractionEnum.ContAuth, PaymentMethod = new CheckoutPaymentMethod(cardDetails) }; // Make the API call var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use const { Client, CheckoutAPI } = require('@adyen/api-library'); // Initialize the client object // For the live environment, additionally include your liveEndpointUrlPrefix. const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const paymentRequest = { merchantAccount: "YOUR_MERCHANT_ACCOUNT", reference: "YOUR_ORDER_NUMBER", shopperInteraction: "ContAuth", amount: { currency: "EUR", value: 1000 }, paymentMethod: { type: "scheme", encryptedCardNumber: "test_5454547699084950", encryptedExpiryMonth: "test_03", encryptedExpiryYear: "test_2030" } } // Make the API call const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v9.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/checkout" ) // For the live environment, additionally include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) amount := checkout.Amount{ Currency: "EUR", Value: 1000, } cardDetails := checkout.CardDetails{ EncryptedCardNumber: common.PtrString("test_5454547699084950"), EncryptedExpiryYear: common.PtrString("test_2030"), EncryptedExpiryMonth: common.PtrString("test_03"), Type: common.PtrString("scheme"), } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", ShopperInteraction: common.PtrString("ContAuth"), PaymentMethod: checkout.CardDetailsAsCheckoutPaymentMethod(&cardDetails), } // Make the API call service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the live environment, additionally include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "reference": "YOUR_ORDER_NUMBER", "shopperInteraction": "ContAuth", "amount": { "currency": "EUR", "value": 1000 }, "paymentMethod": { "type": "scheme", "encryptedCardNumber": "test_5454547699084950", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030" } } # Make the API call result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v9.3.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the live environment, additionally include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :reference => 'YOUR_ORDER_NUMBER', :shopperInteraction => 'ContAuth', :amount => { :currency => 'EUR', :value => 1000 }, :paymentMethod => { :type => 'scheme', :encryptedCardNumber => 'test_5454547699084950', :encryptedExpiryMonth => 'test_03', :encryptedExpiryYear => 'test_2030' } } # Make the API call result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // Initialize the client object // For the live environment, additionally include your liveEndpointUrlPrefix. const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const cardDetails: Types.checkout.CardDetails = { encryptedCardNumber: "test_5454547699084950", encryptedExpiryYear: "test_2030", encryptedExpiryMonth: "test_03", type: Types.checkout.CardDetails.TypeEnum.Scheme }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", shopperInteraction: Types.checkout.PaymentRequest.ShopperInteractionEnum.ContAuth, paymentMethod: cardDetails }; // Make the API call const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` ## See also * [Tokenization](/online-payments/tokenization) * [Account Updater](/online-payments/account-updater) * [Account Updater results report](/reporting/account-updater-results) * [IETF: JSON Web Encryption (JWE) standard](https://tools.ietf.org/html/rfc7516)