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.

You can only use our standard 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

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 Developers > Additional data.

3. 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

4. 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.

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:

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.

If you want an overview of card updates on a transaction level, you can add the Real Time Account Updater status column to the Received Payment Details report.

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 can only use our standard 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.

You will receive the corresponding status in the additionalData.realtimeAccountUpdaterStatus field of your response.

The example below shows how to send a /payments request to test a scenario where the card has changed.

See also