Update stored credentials

Last updated: April 2, 2025

The Real-Time Account Updater service automatically updates payment card details when they change, resulting in an increased payment acceptance rate.

You can enable the following services individually with the Real-Time Account Updater:

Update type	Description	Service	Card scheme
Batch	Updates details of cards stored in the Vault independently of the payment flow. All stored cards are eligible for updates, regardless of usage.	Store & Update	Mastercard
Batch via SFTP	Requests updated details from schemes for the cards you provide in a batch file. Cards do not need to be stored in the Vault. Updated card details are returned securely so that you can store them independently. For Visa and Mastercard, your PCI compliance level must be SAQ D or higher to use this update mechanism.	Batch Account Updater	American Express
			Mastercard
			Visa
Real-time	Updates details of cards during the payment authorization process. Only active cards experiencing specific decline codes are eligible for updates. Available for payments requested using a payment instrument or full card details.	Update & Retry	Mastercard
Real-time		Real-Time Account Updater	Visa

Information

Mastercard Update & Retry immediately retries payment authorization with the updated card details.

Card information updates can result from:

Account closures
Expiry date changes
Cards being replaced that are reported as lost, stolen, or expired

Note

Issuer portfolio conversions are only supported by Mastercard Store & Update. A portfolio conversion from Mastercard to Visa will be reported as card_closed. Portfolio conversions from Visa to Mastercard are not supported. Issuer portfolio conversions are not supported by Visa Real-Time Account Updater or Mastercard Update & Retry.

During card information updates, one of the following combinations is possible:

The card number changes, and the expiry date stays the same.
The card number stays the same, and the expiry date changes.
Both the card number and the expiry date change.

Alternatively, the account may be closed, meaning the account number and expiry date are no longer valid.

To receive card updates from the Real-Time Account Updater, you must meet these criteria:

You have reached out to your account manager or [email protected] to enable Real-Time Account Updater for your account.
The payment is requested using a payment instrument or full card details.
The amount specified in the payment is greater than zero (not a card verification).
The source of payment is not a network token.
The transaction types are either merchant-initiated transaction (MIT) or card-on-file cardholder-initiated transaction (CIT).

Information

To learn more, reach out to your account manager or [email protected].

Card updates are provided in the:

Card updates are provided in the webhook payment_approved and payment_declined event types within the following fields:

bin
expiry_month
expiry_year
fingerprint
last4

To receive information with both old card details and new card details, you need to do one of the following:

In the webhook, reason_type will indicate the reason for the update.

Possible values are:

card_updated – The card number has changed.
card_expiry_updated – The card expiry date has changed.
card_closed – The card account has been closed by the issuer, and the new account is not opened (contact the cardholder to get new card details).
contact_cardholder – The card was updated, but the cardholder has opted out of the Account Updater service via the issuer (contact the cardholder to get new card details).


1{
2 "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3 "type": "card_updated",
4 "version": "1.0.0",
5 "created_on": "2022-10-11T17:21:45.7502303Z",
6 "data": {
7   "client_id": "cli_vjmdzvijizs7o26kiuiakywvyi",
8   "reason_type": "card_updated",
9   "source_scheme": "visa",
10   "original_card": {
11     "scheme": "visa",
12     "bin": "42424242",
13     "last4": "2345",
14     "expiry_month": 10,
15     "expiry_year": 2022,
16     "fingerprint": "71580b426f1d190d29087ff265d8f48df1ad34ede41c27cbff9d23c1a14d1776"
17   },
18   "replacement_card": {
19     "scheme": "visa",
20     "bin": "42424242",
21     "last4": "3456",
22     "expiry_month": 12,
23     "expiry_year": 2025,
24     "fingerprint": "47586b424h5i190d29087ff265d8f48df1ad34nfj41c27cbff9d23c1a14d5649"
25   },
26   "sources": [
27     {
28       "id": "src_nwd3m4in3hkuddfpjsaevunhdy"
29     },
30     {
31       "id": "src_wmlfc3zyhqzehihu7giusaaawu"
32     },
33     {
34       "id": "src_zxlfc4rdsqze56cde5iusrltou"
35     }
36   ]
37 }
38}

Once your account is enabled for the Real-Time Account Updater, card updates will be reflected in the following payment response fields:

bin
expiry_month
expiry_year
fingerprint
last4

Note

To help increase authorization success rates, as of December 2022, Checkout.com no longer blocks payments with lapsed expiry dates.

Information

The following example does not display a full response, only the part of a response that relates to the Real-Time Account Updater.


1{
2  "source": {
3    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
4    "last4": "4242",
5    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
6    "bin": "424242",
7    "expiry_month": 10,
8    "expiry_year": 2027
9  }
10}

Note

PCI SAQ D compliance is required to receive the updated full PAN (FPAN) in the payment response.

The encrypted updated card number is returned in the source.encrypted_card_number field as part of the payment response when a card is updated by our Real-Time Account Updater.


1{
2    "source": {
3        "type": "card",
4        "Fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B814…",
5        "expiry_month": 10,
6        "expiry_year": 2027,
7        "encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz…"
8    }
9}

Information

The bin and last4 digits of the PAN will not be returned in the response when a encrypted_card_number is provided.

Generate an RSA public/private key pair. This RSA key pair must use a key size of at least 2048 bits. You, as a PCI-compliant merchant, are responsible for the lifecycle of any encryption keys used for the Real-Time Account Updater including their creation, protection, and rotation, and must appoint a key custodian and formally acknowledge this responsibility in writing or electronically in accordance with PCI DSS Requirement 3.6.8.

Information

Checkout.com recommends that RSA keys should be generated using an appropriate HSM and stored 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 no existing system is 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 contact [email protected], and include written confirmation of your responsibilities as a key custodian.

Note

Checkout.com will use the same public key for a maximum of one year. If you do not replace the key when the previous one expires, the payload will no longer contain the encrypted_card_number field. Your key custodian will need to provide Checkout.com with a new key at least once per year.

Once the public key has been set up by Checkout.com, an encrypted card number will be returned in the encrypted_card_number field under the source object when a real-time account update has taken place. This is the card number encrypted using the RSA public key you previously provided. The encryption uses JWE with a 256 GCM-encrypted payload and its key encrypted using RSA OAEP 256.

Many language frameworks include support for JOSE (JavaScript Object Signing and Encryption).

The following Node.js sample demonstrates how to decrypt the card number programmatically and verify the fingerprint of the RSA public key:


1import fs from "fs/promises";
2import jose from "node-jose";
3import sshpk from "sshpk";
4
5async function decrypt(privateKeyFile: string, payload: string) {
6  try {
7    // Read private key file
8    const keyBytes = await fs.readFile(privateKeyFile);
9
10    // Parse private key
11    const privateKey = sshpk.parsePrivateKey(keyBytes, "pem");
12
13    // Convert private key to JWK format
14    const key = jose.JWK.asKey(privateKey.toBuffer("pkcs8"), "pem");
15
16    // Decrypt payload
17    const decrypted = await jose.JWE.createDecrypt(key).decrypt(payload);
18    const header = decrypted.header as Record<string, string>;
19
20    // Calculate expected fingerprint
21    const fingerprintBuffer = privateKey.fingerprint("sha256", "spki");
22    const expectedFingerprint = fingerprintBuffer.toString("base64");
23
24    // Log decrypted information
25    console.log({
26      card_id: header["kid"],
27      card_fingerprint: header["x5t#S256"],
28      card_number: decrypted.plaintext.toString(),
29      expected_fingerprint: expectedFingerprint,
30    });
31  } catch (error) {
32    console.error("Error during decryption:", error);
33  }
34}

Network tokens

Use network tokens alongside the Real-Time Account Updater to automatically update stored payment credentials.

Update stored credentials

Information

Card information updates

Note

Before you start

Information

Retrieve card updates

payment_approved and payment_declined webhook notifications

card_updated webhook notification

Webhook card_updated example

Retrieve card updates in the payment response

Note

Response example

Information

Receive encrypted updated full card in the payment response

Note

Response example

Information

Create a public and private key pair

Information

Note

How to decrypt the updated PAN

Sample code

Next steps

Network tokens