Update stored credentials

Last updated: September 25, 2024

Checkout.com's Real-Time Account Updater is a service that enables automatic updating of payment card details when they change, resulting in an increased payment acceptance rate.

Checkout.com provides three Real-Time Account Updater options, each of which can be enabled on an individual basis:

Visa Real-Time Account Updater - receives and applies card updates from Visa within the payment authorization process. As a result, only active cards are eligible for updates. This option supports payments requested using a payment instrument or full card details.
Mastercard Update & Retry - updates card details during the payment authorization process based on the post-decline recommendation code provided by Mastercard. The authorization is then immediately retried with the updated card. As a result, only active cards experiencing a certain type of decline code are eligible for updates. This option works for payments requested using a payment instrument or full card details.
Mastercard Store & Update - updates cards vaulted with Checkout.com asynchronously and unrelated to the payment flow. As a result, all vaulted cards are eligible for updates regardless of usage. This option is recommended when card updates are needed in the absence of payment (pay-in) activity. For example, to support Card Payouts.

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:

Request a payment response
Get payment details response
webhook notifications

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:

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}

Update stored credentials

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