Instrument Updates

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

Related Guides: Account Updater

Create Instrument Updates

To update the card details of your customers, create an instrument_updates resource. Include the Payment Instrument IDs you want to update in a CSV.

Request
header Parameters
Accept
string
Default: application/hal+json
Request Body schema: multipart/form-data
file
string <binary>

The binary contents of the file.

request
string

A JSON string of your request. The JSON object needs to contain the following two fields:

  • merchant: 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.
  • idemopotency_id: A randomly generated value that will be associated with this instrument_update resource.
Responses
200

Single instrument_update object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/instrument_updates
Request samples 
curl "https://finix.sandbox-payments-api.com/instrument_updates" \
  -H "Content-Type: multipart/form-data" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -F 'request={"merchant": "MUucec6fHeaWo3VHYoSkUySM","idempotency_id": "123xyz testing"}'
Response samples
application/json
{}

Download Instrument Updates

Fetch a previously created instrument_updates resource as a CSV.

To fetch the instrument_updates resource in JSON, add ?format=json to the request endpoint.

Request
path Parameters
instrument_updates_id
required
string

The ID of the instrument_updates resource. This ID was returned when initially creating the instrument_updates object.

query Parameters
format
string

Specify the format you'd like to download the response in (JSON is the only other format available for download).

Example: format=json
header Parameters
Accept
string
Default: application/hal+json
Responses
200

The updated Payment Instruments will be returned in the following comma-separated 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
401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/instrument_updates/{instrument_updates_id}/download
Request samples 
curl "https://finix.sandbox-payments-api.com/instrument_updates/IUd2Wzs6jxPJjteva3n19Amu/download" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
"payment_instrument_original,payment_instrument_new,result PIlkNdfZibF8a7Prd2teGB1,PI3aQGaCM5nDMjqyTXcbUJzR,CARD_EXPIRATION_UPDATED PIJPXW0HZ9lpO1nb6sog5DiX,PIdBHpy7BBSxd2z81VdKpVbT,CARD_NOT_FOUND PIiRLbbG4i5daypWNzIrq2xD,,NO_CHANGE_FOUND PIy5llZGt6VxlDqbcTgATqeH,,UNKNOWN"

Fetch an Instrument Update

Fetch a specific instrument_update from an instrument_updates resource.

Request
path Parameters
instrument_updates_id
required
string

The ID of the instrument_update.

header Parameters
Accept
string
Default: application/hal+json
Responses
200

Single instrument_update object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/instrument_updates/{instrument_updates_id}
Request samples 
curl "https://finix.sandbox-payments-api.com/instrument_updates/IUp9oSWhWUF31DPrJ8CojQeQ/" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{}