Account Updater

With Finix's Account Updater API, you can update the credit card information you have saved for customers without needing to contact each individual cardholder.

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

• New account number and or new expiration date.
• Card conversion (e.g., Costco transitioning its credit card from American Express to Visa would require an update).
• Account closed.

This guide details how to use Finix's Account Updater API to update card information.

Create an Account Updater Batch

To create an Account Updater Batch, we'll first create an Instrument Update, with all of the cards you want to submit to the processor for updates. The CSV file used in the request should contain one column with the Payment Instrument IDs that you want to submit.

Here's an example of what the CSV should look like:

PIe2YvpcjvoVJ6PzoRPBK137
PI77BEnaiYZDya1U6T38n72F
PIfufmJXaxF2T2em1hpmeoGh

When Finix receives the results from the Card Networks, we'll update the state of Instrument Updates from PENDING to SUCCEEDED and send a webhook event.

We'll also return a download link in the response that you can use to update the information of your cardholders. We'll usually have the results within three business days; however, the Card Networks can take up to eight business days to return results.

curl --request POST 'https://finix.sandbox-payments-api.com/instrument_updates' \
-H 'Finix-Version: 2022-02-01' \
-u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-F 'file=@"/Path/to/Local/File.csv"' \
-F 'request="{\"merchant\":\"MUucec6fHeaWo3VHYoSkUySM\",
\"idempotency_id\":\"123xyz testing\"
}"'

Example Response

{
  "id": "IUd2Wzs6jxPJjteva3n19Amu",
  "created_at": "2022-04-11T22:47:35.50Z",
  "updated_at": "2022-04-11T22:47:35.50Z",
  "idempotency_id": "123xyz",
  "merchant": "MUucec6fHeaWo3VHYoSkUySM",
  "state": "PENDING",
  "_links": {
    "self": {
      "href": "http://finix.sandbox-payments-api.com/instrument_updates/IUd2Wzs6jxPJjteva3n19Amu"
    }
  }
}

Fetch an Account Updater Batch

When state moves to SUCCEEDED and the Card Networks have returned the results to us, Finix will return a response with a download link.

The download link has a CSV indicating which Payment Instruments were updated and which were not. The Card Networks only charge for updates which is when the result returns:

• CARD_EXPIRATION_UPDATED
• CARD_NUMBER_UPDATED
• CARD_NUMBER_AND_EXPIRATION_UPDATED
• CONTACT_CARDHOLDER
• CLOSED_ACCOUNT

Submitting an old card in an Account Updater batch that has been updated will, unfortunately, incur a charge from the processor. We recommended making the old Payment Instrument invalid in your system to avoid resubmitting the Payment Instrument ID.

curl https://finix.sandbox-payments-api.com/instrument_updates/IUd2Wzs6jxPJjteva3n19Amu/download \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

CSV Response File Format

The CSV that's available to download will return Payment Instrument IDs in the following format:

For details on how to download an Account Updater Batch in JSON formatting, see Fetch Instrument Updates - JSON.

Account Updater Results and Recommended Action

When an Account Updater Batch is complete, the results the Card Networks return in the Instrument Updates resource includes:

Testing for Specific Responses

You can use the card numbers below to trigger specific responses on the DUMMY_V1 processor.

Account Updater States

The different states the Instrument Updates resource can go through include: