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 resource, with all of the cards we 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:

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 https://finix.sandbox-payments-api.com/instrument_updates \
    -H "Content-Type: text/csv" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -F 'file=@path/to/local/file' \
    -F 'request = "{
        \"merchant_id\": \"MUucec6fHeaWo3VHYoSkUySM\",
        \"idempotency_id\": \"123xyz\"
}"'

Example response

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

HTTP Request

POST https://finix.sandbox-payments-api.com/instrument_updates

Request Arguments

Field Type Description
merchant string, optional ID of the Merchant object that you want to associate with the Account Updater batch for your own accounting purposes. You can only associate one Merchant to each instrument_updates object.
idempotency_id string, optional A randomly generated value that will be associated with this instrument_updates resource.

Response

Field Type Description
id string The ID of the instrument_updates resource.
created_at string Timestamp of when the instrument_updates resource was created.
updated_at string Timestamp of when the instrument_updates resource was last updated.
merchant string The Merchant ID associated with the instrument_updates.
state string The status of the instrument_updates resource and update request.

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

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" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

HTTP Request

GET https://finix.sandbox-payments-api.com/instrument_updates/:INSTRUMENT_UPDATE_ID:/download

URL Parameters

Field Description
:INSTRUMENT_UPDATE_ID: The ID of the instrument_updates resource. This ID was returned when initially creating the instrument_updates object.

Response

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_NOT_FOUND
PI0ovZAS9yfEtgDrZnMaiLvi PIhXS0jXNTmklyVk91EsohuZ CONTACT_CARDHOLDER
PInOrrKY3G1U33hGYTQJ8cIY CLOSED_ACCOUNT
PIlkAOt5kTVhuuxxbmOi9qn INVALID_CARD
PIiRLbbG4i5daypWNzIrq2xD NO_CHANGE_FOUND
PIy5llZGt6VxlDqbcTgATqeH UNKNOWN

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.
CARD_NOT_FOUND The processor did not find the card number. Contact cardholder if desired.
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.