Are you looking for test card numbers?

Would you like to contact support?

Feature icon

Real Time Account Updater

When you submit a payment that is refused, our Real Time Account Updater instantly checks with Visa and Mastercard for updated card details. If there's an update, we'll immediately retry the payment with the updated card details. This all happens as the payment is being processed, and appears as a single transaction.

Real Time Account Updater is available globally for participating Mastercard issuers, and for Visa cards issued in Canada and the United States.

You can only use 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 CVC.

Set up Real Time Account Updater

To set up Real Time Account Updater, contact our Support Team.

No additional integration steps are required if you're using tokenization.

If you're storing card on file details, you can collect updated card details in an encrypted batch result file. These are generated automatically each day, and available to you in an SFTP directory. To set up an SFTP directory, contact our Support Team. You'll need to provide your IP address, and SSH and PGP keys. For more information, see Advanced SFTP batch files.

Receive card updates in payment response

For a description of the included fields for a card detail, click on the detail in your Customer Area.

You can optionally receive updated card details in the payment response, which you can use to update your other systems (such as a CRM tool).

To receive the updated card details:

  1. Log in to your Customer Area.
  2. Navigate to Account > API URLs.
  3. Go to the Additional data in API response section.
  4. Under Card, turn on the card details that you want to receive. We recommend at least the following: 

    • Card bin details
    • Card summary
    • Expiry date
  5. Under Payment, turn on Realtime Account Updater Status.

If a card's details have been updated, you'll receive this information as additionalData in the payment response.

   additionalData: {
      expiryDate: "3/2030",
      realtimeAccountUpdaterStatus: "CardChanged",
      cardSummary: "1111",
      cardSchemeCommercial: "true",
      cardPaymentMethod: "visa",
      cardIssuingBank: "Bank of America",
      cardIssuingCountry: "US",
      cardIssuingCurrency: "USD",
      cardBin: "411111",
      fundingSource: "CREDIT"

Optional: Receive the updated card number

If you are fully PCI compliant, you can receive the full updated card number in the payment response. This is provided as a JSON Web Encryption (JWE) encrypted value, that you will need to decrypt using your private key.

Contact our Support Team to enable this functionality. You will need to provide them with a RSA public key with a length of 2048 bits. We will use this key to encrypt card numbers that are provided in the payments response.

If a card's details have been updated, you'll additionally receive the following as additionalData in the payment response:

  • realtimeAccountUpdaterSecureData: Encrypted value representing the updated card number (or PAN).

       additionalData: {
          realtimeAccountUpdaterStatus: "CardChanged",
          realtimeAccountUpdaterSecureData: "eyJhbGciOiJSU0EtT0FF...",
          expiryDate: "3/2030",
          cardSummary: "1111",
          cardSchemeCommercial: "true",
          cardPaymentMethod: "visa",
          cardIssuingBank: "Bank of America",
          cardIssuingCountry: "US",
          cardIssuingCurrency: "USD",
          fundingSource: "CREDIT"

Decrypting the card number

The value you receive in the realtimeAccountUpdaterSecureData is encrypted using JWE, represented in JWE JSON Compact Serialization format. You will 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.

  3. Decrypt the value 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).

Real Time Account Updater 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 request 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. Reach out to the card holder to get their updated card information.
Unknown No (MasterCard Only) We received an unknown value, in most cases, this means Mastercard, temporarily, couldn't find the card in their system.

If you are using tokenized details, the tokenized details will be updated and the recurringDetailReference will stay the same.

Get a report on card updates

The Account Updater results report shows a summary of Account Updater results from a particular period of time. Use this report to check the outcomes and statuses of account update requests, 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.

Test and go live

To test how different Real Time Account Updater scenarios work for your integration, use the following test card numbers in your payments request.
You will receive the corresponding status in the additionalData.realtimeAccountUpdaterStatus field of your response.

Status Card number Expiry Date
CardChanged 5454 5476 9908 4950 03/2030
CardExpiryChanged 5454 5418 5840 6567 Any date except 03/2030
CloseAccount 5454 5415 8031 1093 03/2030
ContactCardAccountHolder 4111 1131 5971 2925 03/2030

See also