Finix Instrument Updates API
{'$ref': 'api-descriptions/tags/instrument-updates.md'}
OpenAPI Specification
openapi: 3.0.2
info:
title: Finix Authorizations Instrument Updates API
description:
$ref: api-descriptions/main.md
contact:
name: Finix
url: https://finix.com
email: support@finixpayments.com
version: '2022-02-01'
servers:
- description: Sandbox server to be used for testing and development
url: https://finix.sandbox-payments-api.com
security:
- BasicAuth: []
tags:
- name: Instrument Updates
description:
$ref: api-descriptions/tags/instrument-updates.md
paths:
/instrument_updates:
post:
summary: Create Instrument Updates
operationId: createPaymentInstrumentUpdate
responses:
'200':
$ref: '#/components/responses/InstrumentUpdate'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: 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.
requestBody:
$ref: '#/components/requestBodies/CreateInstrumentUpdateRequest'
tags:
- Instrument Updates
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/instrument-updates/create-instrument-updates.md
x-python-method-name: create
/instrument_updates/{instrument_updates_id}/download:
parameters:
- schema:
type: string
name: instrument_updates_id
in: path
required: true
description: The ID of the `instrument_updates` resource. This ID was returned when initially creating the `instrument_updates` object.
get:
summary: Download Instrument Updates
tags:
- Instrument Updates
responses:
'200':
description: "The updated `Payment Instruments` will be returned in the following comma seperated format:\n\npayment\\_instrument\\_original,\t| payment\\_instrument_new, |result\n--------------------------- | ---------------------- | -----\nPIlkNdfZibF8a7Prd2teGB1 | PI3aQGaCM5nDMjqyTXcbUJzR| CARD\\_EXPIRATION_UPDATED\nPIJPXW0HZ9lpO1nb6sog5DiX | PIdBHpy7BBSxd2z81VdKpVbT | CARD\\_NOT\\_FOUND\nPI0ovZAS9yfEtgDrZnMaiLvi | PIhXS0jXNTmklyVk91EsohuZ | CONTACT\\_CARDHOLDER\nPInOrrKY3G1U33hGYTQJ8cIY | | CLOSED\\_ACCOUNT\nPIlkAOt5kTVhuuxxbmOi9qn | | INVALID\\_CARD\nPIiRLbbG4i5daypWNzIrq2xD | | NO\\_CHANGE\\_FOUND\nPIy5llZGt6VxlDqbcTgATqeH | \t | UNKNOWN"
content:
application/json:
schema:
type: string
format: binary
examples:
Instrument Update:
value: payment_instrument_original,payment_instrument_new,result PIlkNdfZibF8a7Prd2teGB1,PI3aQGaCM5nDMjqyTXcbUJzR,CARD_EXPIRATION_UPDATED PIJPXW0HZ9lpO1nb6sog5DiX,PIdBHpy7BBSxd2z81VdKpVbT,CARD_NOT_FOUND PIiRLbbG4i5daypWNzIrq2xD,,NO_CHANGE_FOUND PIy5llZGt6VxlDqbcTgATqeH,,UNKNOWN
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
operationId: downloadInstrumentUpdate
description: "Fetch a previously created `instrument_updates` resource as a CSV. \n\nTo fetch the `instrument_updates` resource in JSON, add `?format=json` to the request endpoint."
parameters:
- $ref: '#/components/parameters/QueryFormat'
x-group-parameters: true
x-java-method-name: download
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/instrument_updates/IUd2Wzs6jxPJjteva3n19Amu/download\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: download
/instrument_updates/{instrument_updates_id}:
parameters:
- schema:
type: string
description: The ID of the `instrument_update`.
name: instrument_updates_id
in: path
required: true
get:
summary: Fetch an Instrument Update
tags:
- Instrument Updates
responses:
'200':
$ref: '#/components/responses/InstrumentUpdate'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
operationId: getInstrumentUpdate
description: Fetch a specific `instrument_update` from an `instrument_updates` resource.
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/instrument_updates/IUp9oSWhWUF31DPrJ8CojQeQ/\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: get
components:
headers:
x-request-id:
description: A unique ID for this specific API request attempt.
schema:
type: string
date:
schema:
type: string
finix-apiuser-role:
schema:
type: string
enum:
- ROLE_ADMIN
- ROLE_PLATFORM
- ROLE_PARTNER
- ROLE_MERCHANT
schemas:
ErrorGeneric:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
Error403ForbiddenList:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
description: ''
title: ''
UpdatedAt:
type: string
title: UpdatedAt
format: date-time
description: Timestamp of when the object was last updated.
InstrumentUpdate:
title: InstrumentUpdates
x-stoplight:
id: si3taxhzmp9fu
type: object
properties:
id:
type: string
description: The ID of the `instrument_updates` resource.
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
idempotency_id:
type: string
description: A randomly generated value that will be associated with this `instrument_update` resource.
merchant:
type: string
description: The `Merchant` ID associated with the `instrument_updates`.
state:
type: string
description: The status of the `instrument_updates` resource and update request.
_links:
type: object
description: 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.
properties:
self:
type: object
description: Link to the resource that was used in the request.
properties:
href:
type: string
payment_instrument:
type: object
description: Link to the payment instrument.
properties:
href:
type: string
application:
type: object
description: Link to the application.
properties:
href:
type: string
Error404NotFoundList:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- NOT_FOUND
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
LogRef:
title: LogRef
type: object
properties:
logref:
type: string
CreateInstrumentUpdateRequest:
type: object
x-examples: {}
title: ''
properties:
file:
type: string
description: The binary contents of the file.
format: binary
request:
type: string
description: '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.'
example: '{"merchant":"MUucec6fHeaWo3VHYoSkUySM", "idempotency_id":"123xyz" }'
Error406NotAcceptable:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- NOT_FOUND
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
title: ''
Error401Unauthorized:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- UNKNOWN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
additionalProperties: true
properties:
self:
type: object
properties:
href:
type: string
source:
type: object
properties:
href:
type: string
CreatedAt:
type: string
title: CreatedAt
format: date-time
description: Timestamp of when the object was created.
responses:
InstrumentUpdate:
description: Single instrument_update object
content:
application/json:
schema:
$ref: '#/components/schemas/InstrumentUpdate'
examples:
Instrument Updates:
value:
id: IUp9oSWhWUF31DPrJ8CojQeQ
created_at: '2020-12-02T03:44:42.77Z'
updated_at: '2020-12-02T03:44:42.81Z'
idempotency_id: F2022-08-12 15:05:19.211366
merchant: MUvQQt3RKe7FBZ6j9eMYoo3H
state: PENDING
_links:
self:
href: https://finix.sandbox-payments-api.com/payment_intrument_updates/IUp9oSWhWUF31DPrJ8CojQeQ
headers:
finix-apiuser-role:
$ref: '#/components/headers/finix-apiuser-role'
date:
$ref: '#/components/headers/date'
x-request-id:
$ref: '#/components/headers/x-request-id'
Error406NotAcceptable:
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/Error406NotAcceptable'
examples: {}
ErrorForbidden403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error403ForbiddenList'
ErrorUnprocessableEntity:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorGeneric'
ErrorNotFound:
description: Object does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error404NotFoundList'
ErrorUnauthorized:
description: Authentication information is missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error401Unauthorized'
requestBodies:
CreateInstrumentUpdateRequest:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateInstrumentUpdateRequest'
examples:
Instrument Update Request:
value:
request: '{"merchant": "MUucec6fHeaWo3VHYoSkUySM","idempotency_id": "123xyz testing"}'
description: ''
parameters:
QueryFormat:
name: format
in: query
required: false
schema:
type: string
example: /download?format=json
description: Specify the format you'd like to download the response in (JSON is the only other format available for download).
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: ''
x-stoplight:
id: c6861590dda46
x-ignoredHeaderParameters:
- Accept
- finix-apiuser-role
- date
- x-request-id
x-tagGroups:
- name: MAIN RESOURCES
tags:
- Authorizations
- Compliance Forms
- Devices
- Disputes
- Fee Profiles
- Files
- Identities
- Instrument Updates
- Merchants
- Onboarding Forms
- Payment Instruments
- Settlements
- Split Transfers
- Transfers
- Users
- Webhooks
- name: CORE-PAYFAC RESOURCES
tags:
- Application Profiles
- Applications
- Balance Transfers
- Merchant Profiles
- Payout Profiles
- Verifications
- name: SUBSCRIPTION BILLING
tags:
- Subscription Schedules
- Subscription Amounts
- Subscription Enrollments
x-exclude-tags-from-libraries:
- Applications
- Application Profiles
- Fees
- Payment Instruments P2C
- Processors
- Review Queue
- Subscription Schedules
- Subscription Amounts
- Subscription Enrollments
- Users