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