Skip to content

Account Updater

Account Updater is a feature that automatically refreshes expired or updated card details for enabled Payment Instruments, eliminating the need for manual updates and ensuring uninterrupted payment processing.

There are three main reasons why a card may need to be updated:

  1. New account number
  2. New expiration date
  3. Account closed

There are two ways to enable Account Updater:

  1. Enabling Account Updater for All New Payment Instruments of Type PAYMENT_CARD: You can choose to enable Account Updater for all new cards. This ensures that all of your cards will always be up-to-date.
  2. Enabling Account Updater for an Individual Payment Instrument of Type PAYMENT_CARD: You can enable Account Updater at an individual card level. This can be particularly useful if you just want a subset of your payment instruments to be enabled for Account Updater.

When you enable a card for Account Updater, Finix will check the card networks daily to see if there is an update.

Option 1: Enabling account updater for all new Payment Instruments

This is a setting that will make it so all new Payment Instruments of type PAYMENT_CARD are enabled for Account Updater.

To enable all new Payment Instruments for Account Updater:

  1. Navigate to the Company Page on the Dashboard.
  2. Clicking on Company Settings tab > Payment Methods tab.
  3. Enable via the Value Added Services section
Company Payment Instrument Settings

Option 2: Enabling account updater for an individual Payment Instrument

Finix Dashboard

To enable a Payment Instrument for Account Updater:

  1. Navigate to a Payment Instrument detail page
  2. Find the Settings section
  3. Click on the Edit Button and enable
Payment Instrument Details - Edit Settings

Using the Finix API

You can use the Finix API to specify Payment Instruments to be enabled for Account Updater. You can pass in account_updater_enabled field. By default, we'll return false unless you enable account_updater_enabled at an Application level.

Create Payment Instrument
curl -X POST \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/payment_instruments \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        "account_updater_enabled": true,
        "address": {
            "city": "San Francisco",
            "country": "USA",
            "line1": "900 Metro Center Blv",
            "postal_code": "94404",
            "region": "CA"
        },
        "expiration_month": 12,
        "expiration_year": 2029,
        "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
        "name": "John Smith",
        "number": "5200828282828210",
        "security_code": "022",
        "type": "PAYMENT_CARD"
    }'

Account updater logs

Viewing Instrument history updates

When a Card is updated, we generate a Instrument History resource. You can see this instrument history resource on the Dashboard and via API.

Company Payment Instrument Settings

Available card updates

If Finix generates a card update, we'll create an Instrument History resource with one of the following enumerators. You can expect card update results within two to seven days, depending on how quickly the Issuing bank delivers the new card information to Finix.

EnumeratorDescription
CLOSED_CARDThe cardholder's card has been closed.
CONTACT_CARDHOLDERThe cardholder has opted out of Account Updater service with their bank.
EXPIRATION_UPDATEDThe expiration date has been updated.
FRAUD_REPORTEDThe cardholder has reported fraud with the Merchant who is requesting an update. This only applies to American Express.
INACTIVE_MERCHANTThe Merchant has not been onboarded successfully. This only applies to American Express.
NO_TRANSACTIONAL_ACTIVITYRequires the card to have at least one transaction associated to the Application before returning updates. This only applies to American Express.
NOT_FOUNDCard’s Issuing Bank does not participate in Account Updater. This enumerator will only be returned once.
NUMBER_AND_EXPIRATION_UPDATEDBoth the expiration date and card number have been updated.
NUMBER_UPDATEDThe card number has been updated.

How Account Updater works

Enrollment happens automatically when account_updater_enabled is set to true on a Payment Instrument. There is no additional opt-in step per individual token. Once enrolled, Finix checks for updates before the next transaction attempt rather than on a fixed schedule.

Keep these limitations in mind when enrolling cards:

  • Processor eligibility: Account Updater does not run on FINIX_V1 processor tokens. Only Payment Instruments on newer processor configurations are eligible for enrollment.
  • First update lag: After a card is first enrolled, several days may pass before the initial update cycle runs. Do not assume a card is current immediately after enabling account_updater_enabled.
  • Already-expired cards: Tokens created from cards that are already expired at the time of enrollment may not enroll successfully. Finix recommends enrolling cards while they are still active.

Card brand specific rules

American Express requires that a successful transfer be performed at least once with the payment instrument before it can be subscribed for updates. If a payment instrument is enabled and no successful transfers were done previously or occur within six months the payment instrument will automatically have its account_updater_enabled flag set to false.