Real-Time Account Updater
Last updated: July 9, 2025
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.
If your level of Payment Card Industry (PCI) compliance 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 or full card details. |
Visa | Account Updater |
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) or a card-on-file cardholder-initiated transaction (CIT)
- Requested using a payment instrument or 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
When you call the Request a payment or Get payment details 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 detailscard_expiry_updated– The card expiry date was updatedcard_updated– The card number was updatedcontact_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 detailsupdate_failed– The card update failed – For more details, see theaccount_update_failure_codefield
If the update is successful, the response also returns the updated card details in the following source fields:
binexpiry_monthexpiry_yearfingerprintlast4
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.
If you've configured your webhook receiver, you'll also receive the updated card details and outcome via the payment approved or payment declined webhooks.
Information
You can generate a Real Time Account Updater Report to see a comprehensive history of all card updates made by the Real-Time Account Updater service during the selected timeframe.
Subscribe to the card updated webhook to receive the original and updated card details when an update triggers. 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 detailscard_expiry_updated– The card expiry date changedcard_updated– The card number changedcontact_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 detailsupdate_failed– The card update failed – For more details, see theaccount_update_failure_codefield
Information
To enable FPANs for card updates, contact your account manager or request support.
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 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.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.Send the public key to your account manager or request support.
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.
When you call the Request a payment 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.
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:
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 endpoint and set source.allow_update field to false.
post
https://api.checkout.com/payments