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_updates, with all of the cards you want to submit to the processor for updates. The CSV request file 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:

Copy
Copied
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.

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

Example response

Copy
Copied
{
  "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.

Copy
Copied
curl https://finix.sandbox-payments-api.com/instrument_updates/IUd2Wzs6jxPJjteva3n19Amu/download \
    -H "Content-Type: application/vnd.json+api" \
    -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:

payment_instrument_original payment_instrument_new result
PIlkNdfZibF8a7Prd2teGB1 PI3aQGaCM5nDMjqyTXcbUJzR CARD_EXPIRATION_UPDATED
PIJPXW0HZ9lpO1nb6sog5DiX PIdBHpy7BBSxd2z81VdKpVbT CARD_NUMBER_AND_EXPIRATION_UPDATED
PI0ovZAS9yfEtgDrZnMaiLvi PIhXS0jXNTmklyVk91EsohuZ CARD_NUMBER_UPDATED
PInOrrKY3G1U33hGYTQJ8cIY NO_CHANGE_FOUND
PIlkAOt5kTVhuuxxbmOi9qn CONTACT_CARDHOLDER
PIiRLbbG4i5daypWNzIrq2xD NO_CHANGE_FOUND
PIy5llZGt6VxlDqbcTgATqeH CLOSED_ACCOUNT

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:

Result Description Recommended Action
CARD_EXPIRATION_UPDATED Only the expiration date has changed. Update your records to replace the old Payment Instrument ID with the new one returned in the file, so you always use the updated card information going forward and avoid declines. Finix does not disable the old Payment Instrument in our system.
CARD_NUMBER_AND_EXPIRATION_UPDATED Both the card number and expiration date have changed. Update your records to replace the old Payment Instrument ID with the new one returned in the file, so that you always use the updated card information going forward and avoid declines. Finix does not disable the old Payment Instrument in our system.
CARD_NUMBER_UPDATED Only the card number has changed. Update your records to replace the old Payment Instrument ID with the new one returned in the file, so that you always use the updated card information going forward and avoid declines. Finix does not disable the old Payment Instrument in our system.
CONTACT_CARDHOLDER The card has a new account number, expiration date, or both, but the cardholder has requested the issuer not share updated card details. Contact cardholder if desired.
CLOSED_ACCOUNT Account has been permanently closed by the issuing bank. Stop using the card. The Card Networks can charge fees for submitting a card that has been declined due to CLOSED_ACCOUNT.
INVALID_CARD End-user submitted an invalid card. Stop using the card. The Card Networks can charge fees for submitting a card that has been declined due to INVALID_CARD.
NO_CHANGE_FOUND No changes were found and no updates were made. No changes are needed. Continue using the same card for the Cardholder.
UNKNOWN Processor didn't return a documented value. Finix will work with the processor to resolve the unknown issues.

Testing for Specific Responses

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

Result Card Number
CARD_EXPIRATION_UPDATED 5580163360238912
CARD_NOT_FOUND 4929152520466243
CARD_NUMBER_UPDATED 5158851579792578
CARD_NUMBER_AND_EXPIRATION_UPDATED 347483133407072
CLOSED_ACCOUNT 4000000000009995
CONTACT_CARDHOLDER 379530505133909
INVALID_CARD 4485398438154449
NO_CHANGE_FOUND 4916487232818371
UNKNOWN 4000000000009987

Account Updater States

The different states the instrument_updates resource can go through include:

State Description
PENDING When you first make a POST request to /instrument_updates, the instrument_updates object will be created with a PENDING state and the update request is submitted to the processor.
SUCCEEDED The state of the request will move to SUCCEEDED when we have returned the download link on the instrument_updates resource. The download link will contain a CSV file indicating which Payment Instruments were updated and which ones were not.
FAILED An end-user submitted an unsupported file type (e.g. PDF instead of CSV) and/or the wrong format of data in the file.