# Real-Time Account Updater The Real-Time Account Updater service automatically updates payment card details when they change, resulting in an increased payment acceptance rate. > **Information** > > To enable Real-Time Account Updater, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). > > > If your level of [Payment Card Industry (PCI) compliance](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/pci-compliance.md) is SAQ D, you can also request to receive encrypted full primary account numbers (FPANs). You can enable the following services individually with the Real-Time Account Updater: | Card scheme | Service | Description | | --- | --- | --- | | Mastercard | Store & Update | Updates details of cards stored in the Vault independently of the payment flow.

All stored cards are eligible for updates, regardless of usage. | | Mastercard | Update & Retry | Updates details of cards during the payment authorization stage.

Only active cards experiencing specific decline codes are eligible for updates.

Available for payments requested using a [payment instrument](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_a_payment_instrument) or [full card details](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_full_card_details). | | Visa | Account Updater | Updates details of cards during the payment authorization stage.

Only active cards experiencing specific decline codes are eligible for updates.

Available for payments requested using a [payment instrument](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_a_payment_instrument) or [full card details](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_full_card_details). | > **Information** > > Mastercard Update & Retry immediately retries payment authorization with the updated card details. To be eligible to receive a card update, payments that trigger the Real-Time Account Updater during the authorization stage must be: - Either a [merchant-initiated transaction (MIT)](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/recurring-payments-with-stored-card-details.md#Request_a_payment_in_a_subsequent_MIT) or a [card-on-file cardholder-initiated transaction (CIT)](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details.md) - Requested using a [payment instrument](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials/payment-instruments.md) or [full card details](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-api.md#Using_full_card_details) – Payments with network tokens do not trigger an update - For an amount greater than zero – Card verifications do not trigger an update --- ## Merchant eligibility To use the Real-Time Account Updater, your business must: - Have a valid business need to receive updated account information, such as a credential-on-file business model, installment payments, or recurring payment services - Meet the following risk management criteria: - Not operate in a business category with merchant category code (MCC) 5962, 5966, or 5967 - Not process sales transactions that are predominantly quasi-cash, which are sales of items directly convertible to cash, such as casino gaming chips, money orders, and wire transfers --- ## Retrieve updated card details When you call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) or [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) endpoints, the response returns an `account_update_status` field which specifies the outcome of the update: - `card_closed` – The issuer closed the account and has not opened a new one – Contact the cardholder and request alternative card details - `card_expiry_updated` – The card expiry date was updated - `card_updated` – The card number was updated - `contact_cardholder` – The card details changed but the cardholder opted out of the Account Updater service via the issuer – Contact the cardholder and request alternative card details - `update_failed` – The card update failed – For more details, see the `account_update_failure_code` field If the update is successful, the response also returns the updated card details in the following `source` fields: - `bin` - `expiry_month` - `expiry_year` - `fingerprint` - `last4` > **Information** > > If a Visa card update fails, you receive an `account_update_failure_code` which provides the failure reason as a [Real-Time Account Updater response code](https://www.checkout.com/docs/developer-resources/codes/real-time-account-updater-response-codes.md). ### Response example ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "action_id": "act_mbabizu24mvu3mela5njyhpit4", "amount": 6540, "currency": "USD", "approved": true, "status": "Authorized", "response_code": "10000", "source": { "id": "src_nwd3m4in3hkuddfpjsaevunhdy", "last4": "4242", "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832", "bin": "424242", "expiry_month": 10, "expiry_year": 2027, "account_update_status": "card_updated" }, "processed_on": "2019-09-10T10:11:12Z", "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "action": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions" } } } ``` If you've [configured your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), you receive the updated card details and outcome via [Payment approved](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_approved.md) or [Payment declined](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_declined.md) webhooks. > **Information** > > You can generate a [Real Time Account Updater Report](https://www.checkout.com/docs/payments/store-and-manage-credentials/retrieve-stored-credentials-reports/real-time-account-updater-report.md) to see a comprehensive history of all card updates made by the Real-Time Account Updater service during the selected timeframe. --- ## Compare updated card details Subscribe to the [Card updated](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/card_updated.md) webhook to receive the original and updated card details when an update occurs. The webhook provides the card details in the `original_card` and `replacement_card` objects. You also receive a `reason_type` field, which specifies the outcome of the update: - `card_closed` – The issuer closed the account and has not opened a new one – Contact the cardholder and request alternative card details - `card_expiry_updated` – The card expiry date changed - `card_updated` – The card number changed - `contact_cardholder` – The card details changed but the cardholder opted out of the Account Updater service via the issuer – Contact the cardholder and request alternative card details - `update_failed` – The card update failed – For more details, see the `account_update_failure_code` field --- ## Retrieve FPAN in card updates > **Information** > > To enable FPANs for card updates, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). If your PCI compliance level is SAQ D, you receive the card's FPAN when an update triggers. You must securely provide Checkout.com with a public key that we will use to encrypt the FPAN. ### Generate keys 1. Generate an RSA public/private key pair. The RSA key pair must use a key size of at least 2048 bits.
We recommend that you generate the RSA keys using an appropriate hardware security module (HSM) and store them using strong encryption with appropriate access control and auditing. Cloud service providers such as AWS KMS, Azure Key Vault, and Google Cloud KMS provide the ability to generate or store key pairs if you do not have an existing system in place. 2. Record the key fingerprint.
This will be the base64-encoded SHA-256 digest of the DER-encoded X.509 format of the certificate (generated based on RFC 7515: JSON Web Signature (JWS)) and supplied as a header in the JWE response to indicate which key has been used. 3. Send the public key to your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).
We will only use a public key for a maximum of one year. You must provide Checkout.com with a new key at least once per year. > **Information** > > You are responsible for the creation, protection, and rotation of any encryption keys you use for the Real-Time Account Updater. You must appoint a key custodian and formally acknowledge this responsibility in writing or electronically in accordance with PCI DSS Requirement 3.6.8. ### Retrieve the FPAN from the response When you call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint, you receive the encrypted updated FPAN in the `source.encrypted_card_number` field. If you receive the `encrypted_card_number`, the response does not return the `bin` or `last4`. #### Response example ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "action_id": "act_mbabizu24mvu3mela5njyhpit4", "amount": 6540, "currency": "USD", "approved": true, "status": "Authorized", "response_code": "10000", "source": { "type": "card", "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B814…", "expiry_month": 10, "expiry_year": 2027, "encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz…", "account_update_status": "card_updated" }, "processed_on": "2019-09-10T10:11:12Z", "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "action": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions" } } } ``` ### Decrypt the FPAN The value returned in the `source.encrypted_card_number` field is the card number, encrypted using the RSA public key you provided. The encryption uses JWE with a 256 GCM-encrypted payload and is key-encrypted using RSA OAEP 256. Many language frameworks include support for JOSE (JavaScript Object Signing and Encryption). The following Node.js example demonstrates how to programmatically decrypt the card number and verify the fingerprint of the RSA public key: #### Example ```javascript import fs from "fs/promises"; import jose from "node-jose"; import sshpk from "sshpk"; async function decrypt(privateKeyFile: string, payload: string) { try { // Read private key file const keyBytes = await fs.readFile(privateKeyFile); // Parse private key const privateKey = sshpk.parsePrivateKey(keyBytes, "pem"); // Convert private key to JWK format const key = jose.JWK.asKey(privateKey.toBuffer("pkcs8"), "pem"); // Decrypt payload const decrypted = await jose.JWE.createDecrypt(key).decrypt(payload); const header = decrypted.header as Record; // Calculate expected fingerprint const fingerprintBuffer = privateKey.fingerprint("sha256", "spki"); const expectedFingerprint = fingerprintBuffer.toString("base64"); // Log decrypted information console.log({ card_id: header["kid"], card_fingerprint: header["x5t#S256"], card_number: decrypted.plaintext.toString(), expected_fingerprint: expectedFingerprint, }); } catch (error) { console.error("Error during decryption:", error); } } ``` --- ## Decline updates for a payment By default, the Real-Time Account Updater triggers automatically on all eligible payments. If you do not want a payment to trigger the Real-Time Account Updater, call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint and set `source.allow_update` field to `false`. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "source": { "type": "id", "id": "src_wmlfc3zyhqzehihu7giusaaawu", "allow_update": false }, "amount": 6500, "currency": "USD", "reference": "ORD-5023-4E89" } ``` ### Response example ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "amount": 6500, "currency": "USD", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "source": { "type": "id", "id": "src_wmlfc3zyhqzehihu7giusaaawu" } } ```