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

Response Schema: application/hal+json
id
string

The ID of the instrument_updates resource.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

idempotency_id
string

A randomly generated value that will be associated with this instrument_update resource.

merchant
string

The Merchant ID associated with the instrument_updates.

state
string

The status of the instrument_updates resource and update request.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/instrument_updates
Request samples
Response samples
application/hal+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=/download?format=json
Responses
200

The updated Payment Instruments will be returned in the following comma seperated 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
Response Schema: application/json
string <binary>
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/IUp9oSWhWUF31DPrJ8CojQeQ/download \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
"string"

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.

Responses
200

Single instrument_update object

Response Schema: application/hal+json
id
string

The ID of the instrument_updates resource.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

idempotency_id
string

A randomly generated value that will be associated with this instrument_update resource.

merchant
string

The Merchant ID associated with the instrument_updates.

state
string

The status of the instrument_updates resource and update request.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

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 "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}