Payment Instruments

Finix API Reference Copy - Copy for LLM Copy page as Markdown for LLMs - View as Markdown\ \ Open this page as Markdown - Open in ChatGPT\ \ Get insights from ChatGPT - Open in Claude\ \ Get insights from Claude - Connect to Cursor Install MCP server on Cursor - Connect to VS Code Install MCP server on VS Code

The Finix API is resource oriented, relying heavily on common REST principles. Our API uses JSON encoded requests and responses.

You will receive separate Sandbox and Live accounts, as well as corresponding API credentials to access the Finix API.

link to section/Authentication Authentication

To communicate with the Finix API, you must authenticate your requests via HTTP Basic Authentication with a username:password combination, which you can get from your Finix Dashboard. If you do not have a Dashboard yet, you can test our APIs with the Sandbox credentials below.

Parameter	Value
Sandbox Username	`USsRhsHYZGBPnQw8CByJyEQW`
Sandbox Password	`8a14c2f9-d94b-4c72-8f5c-a62908e5b30e`

Request Format

curl "https://finix.sandbox-payments-api.com/" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

link to section/Environments Environments

Finix provides two environments with distinct base URLs to make API requests.

A Sandbox environment for developing and testing your integration.
A Live environment for processing payments.

These environments are entirely separate and do not share API Credentials.

Environment	Endpoint URL
Sandbox	`https://finix.sandbox-payments-api.com`
Live	`https://finix.live-payments-api.com`

Live Access

To get access to the Live environment, please reach out to your Finix point-of-contact.

link to section/HTTP-Codes-and-Errors HTTP Codes and Errors

Finix uses HTTP codes to communicate whether requests succeeded or failed. Requests to Finix's API return responses within less than one second.

However, communications between card networks and processors can increase response latency. Additionally, response latency for card-present devices can be higher depending on how quickly buyers complete the transaction on payment terminals.

Due of this, requests to the Finix API have a maximum timeout of 5 minutes.

For more details, see Error Codes. Also, you can test for specific errors and responses.

Code	Definition	Explanation
`400`	Bad Request	We could not parse your request. Verify you are providing valid JSON.
`401`	Unauthorized	We could not authenticate your request. Verify your `username` and `password` are correct.
`402`	Upstream Processor Error	Errors caused by 3rd-party service(s).
`403`	Forbidden	Your credentials do not have the correct permissions to perform the request.
`404`	Not Found	We could not find the specified resource.
`405`	Method Not Allowed	The specified resource does not support the HTTP Method used to submit the request.
`406`	Not Acceptable	The server could accept the submitted request. Confirm how the request was formatted and submitted.
`409`	Conflict	The submitted request conflicts with the current state of the server.
`422`	Unprocessable Entity	The parameters were valid, but the request failed. Usually, the error involves misunderstanding of how to perform the request (e.g., creating a transfer with a seller that is not-yet-approved).
`500`	Internal Server Error	We had a problem with our server. Try again later.

link to section/Idempotent-Requests Idempotent Requests

The Authorization and Transfer resources both have an idempotency_id field. Use this field to ensure the API Request is performed only once.

Why is this important? We've all experienced a checkout page that hangs on a request or payment, and feared that if we refresh or submit the payment again, we'd be charged twice.

Finix removes this ambiguity with the idempotency_id. You or the user can generate a unique ID that can be included as an idempotency_id with the usual request payload. If anyone attempts a request with the same idempotency_id, the response will raise an exception.

By passing an idempotency_id in the body of your requests, you can be rest assured that when you create an Authorization or Transfer, the user will be protected from potential network issues.

idempotency_id is available on the following three endpoints:

/transfers
/authorizations
/transfers/{id}/reversals

`idempotency_id` scope

idempotency_id checks against previous requests made on the same endpoint.

link to section/Query-Parameters Query Parameters

Every Finix resource (e.g., Authorizations, Transfers) can be listed and reviewed using GET requests. Additionally, every endpoint has query parameters available to help you filter the resources that are returned.

See the following example of how to query the Transfers endpoint for Transfer resources with type: DEBIT.

Query Parameter Example

curl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

link to section/Tags Tags

Many Finix resources (e.g., Authorization, Transfer) let you include tags to add key-value metadata to your Finix API resources. For example, when creating a Transfer, you might include customerId: Customer123 to tag the Transfer with your internal customer ID. You can update tags as many times as needed, as well as filter resources by tags.

Tags Example

{
    ...,
    "tags": {
        "card-type": "business card",
        "order_number": "H-1257",
        "customer_order_reference": "order1234",
        "item_type": "hardware",
        "vendor": "finix"
    }
}

The tags object accepts up to 50 key: value pairs to annotate resources with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500.

Special Characters

Finix does not allow special characters on tags (e.g., \, ,, ", ')

link to section/Versioning Versioning

As Finix improves our products and features, we will make changes to our APIs. When breaking changes are made to Finix's API, we may release a new dated API version.

The API version your requests use controls how API responses and webhooks behave (for example, the values you see in responses and the parameters you can include in requests). For more information, see Versioning.

link to section/Postman-Collection Postman Collection

Finix has a Postman collection to help in your development. You can fork it using the button below.

Overview

URL https://finix.com

Finix support@finix.com

Languages

cURL

Servers

Sandbox server

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

link to Authorizations Authorizations

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within seven days. When an Authorization is captured it produces a Transfer resource.

Related Guides:

Operations

post

/authorizations

get

/authorizations

get

/authorizations/{authorization_id}

put

/authorizations/{authorization_id}

put

/authorizations/{authorization_id_void_to}

+ Show

link to Compliance Forms Compliance Forms

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

To process payments, your Merchants must validate their compliance with PCI DSS requirements annually. To do this, your Merchants must attest to PCI Self-Assessment Questionnaire (SAQ) compliance forms.

Related Guides:

Operations

get

/compliance_forms/{compliance_form_id}

put

/compliance_forms/{compliance_form_id}

get

/compliance_forms

+ Show

link to Devices Devices

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Device resource represents a Point-of-Sale terminal. Devices are used for In-Person transactions.

Related Guides:

In-Person Payments

Operations

get

/devices

get

/devices/{device_id}

put

/devices/{device_id}

get

/devices/{device_id_connection}

get

/devices/{device_id}/device_metrics

post

/merchants/{merchant_id}/devices

+ Show

link to Disputes Disputes

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Disputes, also known as chargebacks, are customer-disputed charges. A core part of the dispute lifecycle is the ability for a Merchant to upload evidence supporting their side.

Related Guides:

Managing Disputes

Operations

get

/disputes

get

/disputes/{dispute_id}

put

/disputes/{dispute_id}

post

/disputes/{dispute_id}/evidence

get

/disputes/{dispute_id}/evidence

get

/disputes/{dispute_id}/evidence/{evidence_id}

put

/disputes/{dispute_id}/evidence/{evidence_id}

delete

/disputes/{dispute_id}/evidence/{evidence_id}

Show4more...

+ Show

link to Fees Fees

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Fee is a charge levied against a Merchant. It represents how a platform charges its sellers for all various types of Fees.

Operations

get

/fees

post

/fees

get

/fees/{fee_id}

put

/fees/{fee_id}

+ Show

link to Fee Profiles Fee Profiles

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A fee_profiles represents a pricing scheme that automatically applies fees to each transaction. Changes to fee_profiles go into effect immediately.

Related Guides:

Merchant Fee Profiles

Operations

post

/fee_profiles

get

/fee_profiles

get

/fee_profiles/{fee_profile_id}

+ Show

link to Files Files

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Use Finix's File API to upload and manage files for your merchants.

Related Guides:

Operations

post

/files

get

/files

get

/files/{file_id}

get

/files/{file_id}/external_links

post

/files/{file_id}/external_links

post

/files/{file_id}/upload

get

/files/{file_id}/download

get

/files/{file_id}/external_links/{external_link_id}

+ Show

link to Identities Identities

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

An Identity resource represents either a person or business in Finix. You'll create an Identity to onboard your sellers, and verify the different owners.

Related Guides:

Operations

post

/identities

get

/identities

get

/identities/{identity_id}

put

/identities/{identity_id}

post

/identities/{identity_id}/associated_identities

get

/identities/{identity_id}/associated_identities

get

/identities/{identity_id}/merchants

+ Show

link to Merchants Merchants

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Merchant resource represents the entity's merchant account on a processor. Your Merchant must be APPROVED to process payments.

Related Guides:

Operations

post

/identities/{identity_id}/merchants

get

/merchants

get

/merchants/{merchant_id}

put

/merchants/{merchant_id}

post

/merchants/{merchant_id}/verifications

+ Show

link to Onboarding Forms Onboarding Forms

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Finix offers and hosts pre-built onboarding forms that you can use to collect onboarding and identity verification information from your users.

Related Guides:

Onboarding via the API

Operations

post

/onboarding_forms

get

/onboarding_forms/{onboarding_form_id}

post

/onboarding_forms/{onboarding_form_id}/links

+ Show

link to Payment Instruments Payment Instruments

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.

A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

Including an address when creating a Payment Instrument can lower interchange on credit card transactions.

Related Guides:

Operations

post

/payment_instruments

get

/payment_instruments

get

/payment_instruments/{payment_instrument_id}

put

/payment_instruments/{payment_instrument_id}

get

/payment_instruments/{payment_instrument_id}/instrument_history

put

/payment_instruments/{payment_instrument_id_verify}

post

/payment_instruments/{payment_instrument_id_verify}/verifications

post

/apple_pay_sessions

link to Create a Payment Instrument Create a Payment Instrument

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/request RequestExpand all

Create a Payment Instrument resource using a card or bank account.

Payment Instruments PCI Scope

The creation of Payment Instruments directly via Finix's API should only be done for testing purposes. You must use our hosted fields or the javascript client to remain out of PCI scope.

SecurityView security details

BasicAuth

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/request/header Headers

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&in=header&path=finix-version Finix-Version string

Specify the API version of your request. For more details, see Versioning.

Default2022-02-01

Example:2022-02-01

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&in=header&path=content-type Content-Type string

The data type being sent in the request body must be application/json.

Example:application/json

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/request/body Bodyapplication/jsonrequired

Any of:

Payment Instrument - Card

Payment Instrument - Card Payment Instrument - Card - Enable Account Updater Payment Instrument - Card - Enable Network Tokens Payment Instrument - Bank Account Payment Instrument - Plaid Bank Account Payment Instrument - Canadian Bank Account Payment Instrument - Token - Card Payment Instrument - Token - Enable Account Updater Payment Instrument - Token - Bank Account Payment Instrument - Token - Enable Network Tokens Payment Instrument - Apple Pay Payment Instrument - Google Pay Payment Instrument - Apple Pay - Passthrough Payment Instrument - Google Pay - Passthrough

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/address address object

The address of the card owner.

Note: Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

+Show 6 properties

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/expiration_month expiration_month integer required

The expiration month of the card (e.g. 12 for December).

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/expiration_year expiration_year integer required

The 4-digit expiration year of the card.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/identity identity string required

The ID of the Identity used to create the Payment Instrument resource.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/name name string required

The name of the card owner. This value can get truncated to comply with processor requirements.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/number number string required

The card or bank account number (no dashes in between numbers).

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/security_code security_code string or null

The 3-or 4-digit security code for the card (i.e., the CVV code). While providing a CVV is optional, it is recommended to include it wherever possible to prevent fraud.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500.(For example, order_number: 25, item_type: produce, department: sales)

+Show property

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/third_party_token third_party_token string

Stringified token provided by Apple or Google. Required if using Apple or Google Pay.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&path=&oneof=0/type type string required

Type of Payment Instrument.

Value"PAYMENT_CARD"

post

/payment_instruments

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments

cURL

Payment Instrument - Card

Payment Instrument - Card Payment Instrument - Card - Enable Account Updater Payment Instrument - Card - Enable Network Tokens Payment Instrument - Bank Account Payment Instrument - Plaid Bank Account Payment Instrument - Canadian Bank Account Payment Instrument - Token - Enable Account Updater Payment Instrument - Token - Bank Account Payment Instrument - Token - Card Payment Instrument - Token - Enable Network Tokens Payment Instrument - Apple Pay Payment Instrument - Google Pay Payment Instrument - Apple Pay - Passthrough Payment Instrument - Google Pay - Passthrough

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "address": {
      "city": "San Francisco",
      "country": "USA",
      "line1": "900 Metro Center Blv",
      "postal_code": "94404",
      "region": "CA"
    },
    "expiration_month": 12,
    "expiration_year": 2029,
    "identity": "IDmj1yA97RS4rMjiQgvK3Vio",
    "name": "John Jeremy",
    "number": "5200828282828210",
    "security_code": "022",
    "type": "PAYMENT_CARD"
  }'

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/response&c=201 Responses

Expand all

A single Payment Instrument

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/response&c=201/headers Headers

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/response&c=201/body Bodyapplication/json

One of:

Payment Instrument - Card

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/id id string non-empty

The ID of the resource.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/created_at created_at string (date-time)

Timestamp of when the object was created.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/created_via created_via string

The method by which the resource was created.

Value"API"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/account_updater_enabled account_updater_enabled boolean

When enabled, Finix automatically checks for updates with card networks. This Account Updater functionality:

Automatically updates card details (e.g., number or expiration date) to maintain continuity of charges, increasing authorization rates.
Saves the cardholder the hassle of updating card details across Merchants for each of their Subscriptions.

Note: Cards created before the feature is enabled are unaffected by default. To include these cards, you can manually enable the Account Updater functionality for each card individually using a PUT request. Once enabled, you can link the card to this API call to trigger updates with card networks.

Defaultfalse

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/address address object

The address of the card owner. Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

+Show 6 properties

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/address_verification address_verification string

Details the results of verifying address with the issuing bank.
Set to UNKNOWN when address gets updated.

Enum"POSTAL_CODE_AND_STREET_MATCH""STREET_MATCH""POSTAL_CODE_MATCH""NO_ADDRESS""NO_MATCH""NOT_SUPPORTED""UNKNOWN"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/application application string non-empty

ID of the Application the resource was created under.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/bin bin string

Bank Identification number for the Payment Instrument.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/brand brand string

The brand of the card saved in the Payment Instrument.

Enum"UNKNOWN""DINERS_CLUB_INTERNATIONAL""DANKORT""MIR""TROY""UATP""CHINA_T_UNION""CHINA_UNION_PAY""AMERICAN_EXPRESS""VERVE"+11 more

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/card_type card_type string

The type of payment card saved in the Payment Instrument.

Enum"CREDIT""DEBIT""HSA_FSA""NON_RELOADABLE_PREPAID""RELOADABLE_PREPAID""UNKNOWN"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/country country string or null

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+239 more

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/disabled_code disabled_code string or null

A code indicating why the Payment Instrument was disabled. This field is set when:

The system automatically disables the Payment Instrument.
A user manually disables it (returns USER_INITIATED).

See disabled_message for all possible codes and their descriptions.

Enum"CARD_ACCOUNT_CLOSED""INVALID_ACCOUNT_NUMBER""LOST_OR_STOLEN_CARD""NON_RELOADABLE_INSUFFICIENT_FUNDS""PICK_UP_CARD""RESTRICTED_CARD""USER_INITIATED"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/disabled_message disabled_message string or null

A human-readable message explaining why the Payment Instrument was disabled. This field provides additional context for the disabled_code.

The possible error codes/messages are:

CARD_ACCOUNT_CLOSED: "The card account has been closed. The card has been disabled to prevent further use."
INVALID_ACCOUNT_NUMBER: "The card number is not valid. The card has been disabled to prevent further use."
LOST_OR_STOLEN_CARD: "The card is reported lost or stolen. The card has been disabled to prevent further use."
NON_RELOADABLE_INSUFFICIENT_FUNDS: "The card has insufficient funds for the transaction and is non-reloadable. The card has been disabled to prevent further use."
PICK_UP_CARD: "The card is reported lost or stolen. The card has been disabled to prevent further use."
RESTRICTED_CARD: "The card has a restriction preventing approval for this transaction. The card has been disabled to prevent further use."
USER_INITIATED: "The card has been disabled by a user."

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/enabled enabled boolean

Indicates whether the Payment Instrument resource is enabled. The default value is true; set it to false to disable the Payment Instrument. The user or the system can update this field to enable or disable the payment instrument.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/expiration_month expiration_month integer [ 1 .. 12 ]

Expiration month (e.g. 12 for December).

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/expiration_year expiration_year integer >= 1

4-digit expiration year.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/fast_funds_indicator fast_funds_indicator string

Details if Fast Funds is enabled for the card.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/fingerprint fingerprint string

Unique ID that represents the tokenized card data.

Example:"FPRxxxxxxxxxxxxxxxxx"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/identity identity string

The ID of the Identity used to create the resource.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/instrument_type instrument_type string

The type of Payment Instrument.

Enum"PAYMENT_CARD""PAYMENT_CARD_PRESENT""TOKEN"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/issuer_country issuer_country string

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

NON_USA - The card was issued outside of the United States.
UNKNOWN - The processor did not return an issuer country for this particular BIN.

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+241 more

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/last_four last_four string

Last four digits of the card.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/name name string or null

The name of the card owner.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/network_token_enabled network_token_enabled boolean

When enabled, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

The token offers increased authorization rates, even for lost or stolen cards, as it remains valid while the physical card is replaced.
Visa reduces interchange fees when using network tokens.
Tokens enhance security by replacing card details with a non-sensitive string that is usable only within the Finix system.

Note: Cards created before the feature is enabled are unaffected. To include them, update the individual Payment Instrument to set network_token_enabled to true.

Defaultfalse

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/network_token_state network_token_state string

The state of the network token. The possible enum values are as follows:

NOT_ENABLED: The network_token_state is NOT_ENABLED when the value of network_token_enabled on the Payment Instrument is false.
PENDING: Immediately after Finix enables network tokens for a specific card, network_token_state is initially set to PENDING.
ACTIVE: After Finix receives the network token successfully from the card network, network_token_state updates to ACTIVE.
FAILED: In the event that there is an issue with the card network such as service becomes unavailable, FAILED is returned.
SUSPENDED: When the issuing bank does not allow the network token to be used in transactions, SUSPENDED is returned.
CLOSED: In the event that the issuing bank has closed the card permanently, CLOSED is returned.

Enum"ACTIVE""CLOSED""FAILED""NOT_ENABLED""SUSPENDED""PENDING"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/payload_type payload_type string

Enum"SOURCE""DESTINATION"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/push_funds_block_indicator push_funds_block_indicator string

Details if the card is enabled to receive push-to-card disbursements.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/name_verification_results name_verification_results object or null

Details the results of verifying the cardholder's name with the issuing bank. Returns null if name_verification_details was not included in the request.

+Show 4 properties

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/security_code_verification security_code_verification string

Details the results of the Card Verification Code check.

Enum"MATCHED""UNKNOWN""UNMATCHED"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/third_party third_party string or null

This field is not applicable to payment cards.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/third_party_token third_party_token string or null

This field is not applicable to payment cards.

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/type type string

Type of Payment Instrument.

Enum"PAYMENT_CARD""TOKEN""GOOGLE_PAY""APPLE_PAY"

link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/_links_links 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.

+Show 7 properties

Response

application/json

Payment Instrument - Card

{
  "id": "PI6F5kkcCB3dtGhFy1t8Aua5",
  "created_at": "2024-11-15T09:42:33.42Z",
  "updated_at": "2024-11-15T09:42:33.42Z",
  "account_updater_enabled": false,
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "instrument_type": "PAYMENT_CARD",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "UNKNOWN",
  "bin": "520082",
  "brand": "MASTERCARD",
  "card_type": "DEBIT",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "NON_USA",
  "last_four": "8210",
  "name": "John Jeremy",
  "network_token_enabled": false,
  "network_token_state": "NOT_ENABLED",
  "security_code_verification": "UNKNOWN",
  "tags": {},
  "third_party": null,
  "third_party_token": null,
  "type": "PAYMENT_CARD",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … },
    "updates": { … }
  }
}

Was this helpful?

link to List Payment Instruments List Payment Instruments

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/request Request

Retrieve a list of Payment Instrument resources.

For details on how to query endpoints using the available parameters, see Query Parameters.

If no query parameters are specified in the request the API automatically limits the response to records from the last 30 days. You can request older data by passing an explicit created_at.lte filter.

SecurityView security details

BasicAuth

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/request/query Query

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=after_cursor after_cursor string

Return every resource created after the cursor value.

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=before_cursor before_cursor string

Return every resource created before the cursor value.

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=account_last4 account_last4 string

Filter by the last 4 digits of the account if available.

Example:account_last4=4242

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=account_routing_number account_routing_number string

Filter by the account routing number if available.

Example:account_routing_number=9444

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=bin bin string

Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.

Example:bin=411111

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=created_at.gte created_at.gte string (date-time)

Filter where created_at is after the given date.

Example:created_at.gte=2022-09-27T11:21:23

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=created_at.lte created_at.lte string (date-time)

Filter where created_at is before the given date.

Example:created_at.lte=2026-09-27T11:21:23

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=expiration_month expiration_month string

Filter by the expiration month associated with the Payment Instrument if applicable. This filter only applies to payment cards.

Example:expiration_month=9

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=expiration_year expiration_year string

Filter by the 4 digit expiration year associated with the Payment Instrument if applicable. This filter only applies to payment cards.

Example:expiration_year=2029

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=id id string

Filter by id.

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=last4 last4 string

Filter by the last 4 digits of the Payment Instrument card. This filter only applies to payment cards.

Example:last4=0454

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=limit limit integer <= 100

The numbers of items to return.

Example:limit=10

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=name name string

Filter by the name.

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=owner_identity_id owner_identity_id string

Filter by the owner id of the associated Identity.

Example:owner_identity_id=IDcWwprrKrD6cSh225JWPri3

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=type type string

Filter by the Payment Instrument type.

Enum"ALL""BANK_ACCOUNT""PAYMENT_CARD"

Example:type=BANK_ACCOUNT

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=tags.key tags.key string

Filter by the tag's key. For more information, see Tags.

Example:tags.key=card_type

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=tags.value tags.value string

Filter by the tag's value. For more information, see Tags.

Example:tags.value=business_card

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=updated_at.gte updated_at.gte string (date-time)

Filter where updated_at is after the given date.

Example:updated_at.gte=2022-09-27T11:21:23

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=updated_at.lte updated_at.lte string (date-time)

Filter where updated_at is before the given date.

Example:updated_at.lte=2026-09-27T11:21:23

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/request/header Headers

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=header&path=finix-version Finix-Version string

Default2022-02-01

Example:2022-02-01

get

/payment_instruments

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments

curl

curl "https://finix.sandbox-payments-api.com/payment_instruments" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/response&c=200 Responses

Expand all

List of Payment Instrument resources

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/response&c=200/headers Headers

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/response&c=200/body Bodyapplication/json

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=page page object

Details the page that's returned.

+Show 2 properties

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=_embedded_embedded object

+Show property

link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=_links_links object

+Show 2 properties

Response

application/json

{
  "_embedded": {
    "payment_instruments": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … },
    "last": { … }
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 14679
  }
}

Was this helpful?

link to Fetch a Payment Instrument Fetch a Payment Instrument

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/request Request

Retrieve the details of an existing Payment Instrument.

SecurityView security details

BasicAuth

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/request/path Path

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=request&in=path&path=payment_instrument_id payment_instrument_id string required

The Payment Instrument ID.

Example:PInVUXZLswZi6pdcK1T41MuE

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/request/header Headers

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=request&in=header&path=finix-version Finix-Version string

Default2022-02-01

Example:2022-02-01

get

/payment_instruments/{payment_instrument_id}

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments/{payment\_instrument\_id}

cURL

curl -i -X GET \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments/PInVUXZLswZi6pdcK1T41MuE \
  -H 'Finix-Version: 2022-02-01'

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/response&c=200 Responses

Expand all

A single Payment Instrument

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/response&c=200/headers Headers

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/response&c=200/body Bodyapplication/json

One of:

Payment Instrument - CardPayment Instrument - Bank

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/id id string non-empty

The ID of the resource.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/created_at created_at string (date-time)

Timestamp of when the object was created.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/created_via created_via string

The method by which the resource was created.

Value"API"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/account_updater_enabled account_updater_enabled boolean

When enabled, Finix automatically checks for updates with card networks. This Account Updater functionality:

Defaultfalse

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/address address object

The address of the card owner. Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

+Show 6 properties

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/address_verification address_verification string

Details the results of verifying address with the issuing bank.
Set to UNKNOWN when address gets updated.

Enum"POSTAL_CODE_AND_STREET_MATCH""STREET_MATCH""POSTAL_CODE_MATCH""NO_ADDRESS""NO_MATCH""NOT_SUPPORTED""UNKNOWN"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/application application string non-empty

ID of the Application the resource was created under.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/bin bin string

Bank Identification number for the Payment Instrument.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/brand brand string

The brand of the card saved in the Payment Instrument.

Enum"UNKNOWN""DINERS_CLUB_INTERNATIONAL""DANKORT""MIR""TROY""UATP""CHINA_T_UNION""CHINA_UNION_PAY""AMERICAN_EXPRESS""VERVE"+11 more

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/card_type card_type string

The type of payment card saved in the Payment Instrument.

Enum"CREDIT""DEBIT""HSA_FSA""NON_RELOADABLE_PREPAID""RELOADABLE_PREPAID""UNKNOWN"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/country country string or null

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+239 more

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/disabled_code disabled_code string or null

A code indicating why the Payment Instrument was disabled. This field is set when:

The system automatically disables the Payment Instrument.
A user manually disables it (returns USER_INITIATED).

See disabled_message for all possible codes and their descriptions.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/disabled_message disabled_message string or null

A human-readable message explaining why the Payment Instrument was disabled. This field provides additional context for the disabled_code.

The possible error codes/messages are:

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/enabled enabled boolean

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/expiration_month expiration_month integer [ 1 .. 12 ]

Expiration month (e.g. 12 for December).

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/expiration_year expiration_year integer >= 1

4-digit expiration year.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/fast_funds_indicator fast_funds_indicator string

Details if Fast Funds is enabled for the card.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/fingerprint fingerprint string

Unique ID that represents the tokenized card data.

Example:"FPRxxxxxxxxxxxxxxxxx"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/identity identity string

The ID of the Identity used to create the resource.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/instrument_type instrument_type string

The type of Payment Instrument.

Enum"PAYMENT_CARD""PAYMENT_CARD_PRESENT""TOKEN"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/issuer_country issuer_country string

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

NON_USA - The card was issued outside of the United States.
UNKNOWN - The processor did not return an issuer country for this particular BIN.

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+241 more

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/last_four last_four string

Last four digits of the card.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/name name string or null

The name of the card owner.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/network_token_enabled network_token_enabled boolean

When enabled, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

Defaultfalse

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/network_token_state network_token_state string

The state of the network token. The possible enum values are as follows:

Enum"ACTIVE""CLOSED""FAILED""NOT_ENABLED""SUSPENDED""PENDING"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/payload_type payload_type string

Enum"SOURCE""DESTINATION"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/push_funds_block_indicator push_funds_block_indicator string

Details if the card is enabled to receive push-to-card disbursements.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/name_verification_results name_verification_results object or null

Details the results of verifying the cardholder's name with the issuing bank. Returns null if name_verification_details was not included in the request.

+Show 4 properties

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/security_code_verification security_code_verification string

Details the results of the Card Verification Code check.

Enum"MATCHED""UNKNOWN""UNMATCHED"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/third_party third_party string or null

This field is not applicable to payment cards.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/third_party_token third_party_token string or null

This field is not applicable to payment cards.

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/type type string

Type of Payment Instrument.

Enum"PAYMENT_CARD""TOKEN""GOOGLE_PAY""APPLE_PAY"

link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/_links_links object

+Show 7 properties

Response

application/json

Was this helpful?

link to Update a Payment Instrument Update a Payment Instrument

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/request RequestExpand all

Update a Payment Instrument to:

Change the billing address in case the account holder moved (instrument_type: PAYMENT_CARD only).
Disable the Payment Instrument resource so it can't be used in requests.
Update the name on the Payment Instrument.
Change the tags.
Enable or disable Account Updater.
Enable or disable Network Tokens.
Update the expiration date (instrument_type: PAYMENT_CARD only).

SecurityView security details

BasicAuth

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/request/path Path

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=request&in=path&path=payment_instrument_id payment_instrument_id string required

The Payment Instrument ID.

Example: PInVUXZLswZi6pdcK1T41MuE

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/request/body Bodyapplication/jsonrequired

Any of:

Payment Instrument - Disable a Payment Instrument

Payment Instrument - Disable a Payment Instrument Payment Instrument - Enable Account Updater Payment Instrument - Enable Network Tokens Payment Instrument - Update Card Address Payment Instrument - Update Name Payment Instrument - Update and Verify Name Payment Instrument - Update Tags Payment Instrument - Add Address for Google or Apple Pay Payment Instrument - Update Expiration Date

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=request&path=&oneof=0/enabled enabled boolean

Details if the Payment Instrument resource is enabled. Default value is true; set to false to disable the Payment Instrument.

put

/payment_instruments/{payment_instrument_id}

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments/{payment\_instrument\_id}

cURL

Payment Instrument - Disable a Payment Instrument

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments/PInVUXZLswZi6pdcK1T41MuE \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": false
  }'

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/response&c=200 Responses

Expand all

A single Payment Instrument

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/response&c=200/headers Headers

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/response&c=200/body Bodyapplication/json

Any of:

Payment Instrument - Disable a Payment Instrument

One of:

Payment Instrument - BankPayment Instrument - Card

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/id id string non-empty

The ID of the resource.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/created_at created_at string (date-time)

Timestamp of when the object was created.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/created_via created_via string

The method by which the resource was created.

Value"API"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/address address object

The address of the bank account owner.

+Show 6 properties

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/account_type account_type string

The bank account type.

Enum"BUSINESS_CHECKING""BUSINESS_SAVINGS""PERSONAL_CHECKING""PERSONAL_SAVINGS"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/application application string non-empty

ID of the Application the resource was created under.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/bank_account_validation_check bank_account_validation_check string

Possible values returned when attempt_bank_account_validation_check is true or the Payment Instrument is used for a Transfer:

INCONCLUSIVE: A verification check was conducted, but the bank account could not be found or verified with the issuing bank. Please contact the buyer to confirm the details collected or request an alternate method of payment.
INVALID: The Payment Instrument was involved in transactions that returned one or more of the following ACH errors:
Account Does Not Allow ACH Transactions
- Account is Closed
- Account Funds are Frozen
- Deceased Account Holder
- Invalid Account Number
- Invalid Routing Number
- No Account on File

For further details about the different ACH failure codes, please refer to ACH Direct Debit documentation.

NOT_ATTEMPTED: A verification check was not performed, and the Payment Instrument has not been used to create a Transfer or Authorization.
VALID: The bank account was successfully verified. The Payment Instrument is eligible for use in creating ACH Direct Debits.

Default "NOT_ATTEMPTED"

Enum"INCONCLUSIVE""INVALID""NOT_ATTEMPTED""VALID"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/bank_code bank_code string

The routing number of the bank account.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/country country string or null

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+239 more

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/disabled_code disabled_code string or null

A code indicating why the Payment Instrument was disabled.

See disabled_message for possible error codes and their messages.

Value"USER_INITIATED"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/disabled_message disabled_message string or null

A human-readable message explaining why the Payment Instrument was disabled. This field provides additional context for the disabled_code.

The possible error codes/messages are:

USER_INITIATED: "The payment instrument has been disabled by a user."

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/enabled enabled boolean

Indicates whether the Payment Instrument resource is enabled. The default value is true; set it to false to disable the Payment Instrument.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/fingerprint fingerprint string

Unique ID that represents the tokenized bank account data.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/identity identity string

The ID of the Identity used to create the resource.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/institution_number institution_number string or null = 3 characters

Canadian bank identifier (EFT). Exactly 3 digits that identify the financial institution (e.g., 004 = TD, 002 = Scotiabank). Stored as a string to preserve leading zeros.

Example: "004"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/instrument_type instrument_type string

The type of Payment Instrument.

Value"BANK_ACCOUNT"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/masked_account_number masked_account_number string or null

The last 4 digits of the account number used to create the Payment Instrument.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/name name string or null

The name of the bank account.

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)

+Show property

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/third_party third_party string or null

This field identifies the external service used to connect the bank account.

PLAID indicates that the account details are being sourced via Plaid.
PLAID_RESELLER indicates that the account details are being sourced via Plaid using Finix's Reseller flow.

Enum"PLAID""PLAID_RESELLER"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/third_party_token third_party_token string or null

A Plaid processor_token created with processor: finix. The token must have access to Plaid's auth and identity products, which can be configured when creating the link_token. For more information, see Plaid's integration guide and Finix's Plaid guide.

Example: "processor-sandbox-1487e3ec-fd86-40e2-b8d3-c8f260b4340c"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/transit_number transit_number string or null = 5 characters

Canadian branch/branch-transit identifier (EFT). Exactly 5 digits that identify the branch where the account is held. Stored as a string to preserve leading zeros.

Example: "12345"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/type type string

Type of Payment Instrument.

Value"BANK_ACCOUNT"

link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/_links_links object

+Show 6 properties

Response

application/json

Payment Instrument - Disable a Payment Instrument

{
  "id": "PIwbvcQGrEP33HShmYM7BR8o",
  "created_at": "2023-02-28T19:05:56.24Z",
  "updated_at": "2023-02-28T21:16:18.80Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": "USER_INITIATED",
  "disabled_message": "The card has been disabled by a user.",
  "enabled": false,
  "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
  "identity": "IDpYDM7J9n57q849o9E9yNrG",
  "instrument_type": "BANK_ACCOUNT",
  "account_type": "PERSONAL_SAVINGS",
  "bank_account_validation_check": "NOT_ATTEMPTED",
  "bank_code": "123123123",
  "country": "USA",
  "masked_account_number": "XXXXX3123",
  "name": null,
  "tags": {
    "card_name": "Personal Card"
  },
  "type": "BANK_ACCOUNT",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … }
  }
}

Was this helpful?

link to List Instrument History Entries List Instrument History Entries

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/request Request

Whenever a stored payment card's details are updated, an Instrument History Entry is created. Use this endpoint to retrieve a list of Instrument History Entries for a specific Payment Instrument.

SecurityView security details

BasicAuth

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/request/path Path

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=path&path=payment_instrument_id payment_instrument_id string required

The Payment Instrument that triggered the creation of this Instrument History Entry.

Example: PInVUXZLswZi6pdcK1T41MuE

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/request/query Query

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=query&path=after_cursor after_cursor string

Return every resource created after the cursor value.

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=query&path=before_cursor before_cursor string

Return every resource created before the cursor value.

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=query&path=limit limit integer <= 100

The numbers of items to return.

Example: limit=10

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/request/header Headers

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=header&path=finix-version Finix-Version string

Default 2022-02-01

Example: 2022-02-01

get

/payment_instruments/{payment_instrument_id}/instrument_history

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments/{payment\_instrument\_id}/instrument\_history

curl

curl -i -X GET \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  'https://finix.sandbox-payments-api.com/payment_instruments/PInVUXZLswZi6pdcK1T41MuE/instrument_history' \
  -H 'Finix-Version: 2022-02-01'

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/response&c=200 Responses

Expand all

List of Instrument History Entry objects.

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/response&c=200/headers Headers

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/response&c=200/body Bodyapplication/json

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=page page object

Details the page that's returned.

+Show 2 properties

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=_embedded_embedded object

+Show property

link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=_links_links object

+Show 2 properties

Response

application/json

{
  "_embedded": {
    "instrument_history_entries": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … }
  },
  "page": {
    "limit": 10,
    "next_cursor": "instrument_history_nAzun1LYhSAJ6rvLeyVAfj"
  }
}

Was this helpful?

link to Verify CVV, AVS, and Name Verify CVV, AVS, and Name

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/request RequestExpand all

Verify a Payment Instrument to determine CVV, AVS, and name verification results.

PCI Scope Restriction

CVV submission is only available to PCI-compliant merchants. Non-PCI customers should not collect and pass CVV in this request.

SecurityView security details

BasicAuth

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/request/path Path

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=request&in=path&path=payment_instrument_id_verify payment_instrument_id_verify string required

The ID of the Payment Instrument you wish to verify.

Example: PIn8as75qLQFqQ7G4NdBUk58

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/request/body Bodyapplication/jsonrequired

One of:

CVV VerificationAddress VerificationName Verification

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=request&path=&oneof=0/merchant merchant string required

The ID of the Merchant.
Must be included when verify_payment_card is set to true.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=request&path=&oneof=0/security_code security_code string or null required

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=request&path=&oneof=0/verify_payment_card verify_payment_card boolean required

Set to true to verify card details with the card issuer.
Must be set to true to update the CVV or security code of a card.
When set to true, merchant must also be included with your request.

put

/payment_instruments/{payment_instrument_id_verify}

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments/{payment\_instrument\_id\_verify}

cURL

CVV Verification

CVV Verification
Address Verification
Name Verification

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments/PIn8as75qLQFqQ7G4NdBUk58 \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MUcgYZswyRfqSSbvMsxuaHxZ",
    "security_code": "123",
    "verify_payment_card": true
  }'

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/response&c=200 Responses

Expand all

A single Payment Instrument.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/response&c=200/headers Headers

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/response&c=200/body Bodyapplication/json

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=id id string non-empty

The ID of the resource.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=created_via created_via string

The method by which the resource was created.

Value"API"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=account_updater_enabled account_updater_enabled boolean

When enabled, Finix automatically checks for updates with card networks. This Account Updater functionality:

Default false

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=address address object

The address of the card owner. Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

+Show 6 properties

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=address_verification address_verification string

Details the results of verifying address with the issuing bank.
Set to UNKNOWN when address gets updated.

Enum"POSTAL_CODE_AND_STREET_MATCH""STREET_MATCH""POSTAL_CODE_MATCH""NO_ADDRESS""NO_MATCH""NOT_SUPPORTED""UNKNOWN"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=application application string non-empty

ID of the Application the resource was created under.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=bin bin string

Bank Identification number for the Payment Instrument.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=brand brand string

The brand of the card saved in the Payment Instrument.

Enum"UNKNOWN""DINERS_CLUB_INTERNATIONAL""DANKORT""MIR""TROY""UATP""CHINA_T_UNION""CHINA_UNION_PAY""AMERICAN_EXPRESS""VERVE"+11 more

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=card_type card_type string

The type of payment card saved in the Payment Instrument.

Enum"CREDIT""DEBIT""HSA_FSA""NON_RELOADABLE_PREPAID""RELOADABLE_PREPAID""UNKNOWN"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=country country string or null

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+239 more

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=disabled_code disabled_code string or null

A code indicating why the Payment Instrument was disabled. This field is set when:

The system automatically disables the Payment Instrument.
A user manually disables it (returns USER_INITIATED).

See disabled_message for all possible codes and their descriptions.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=disabled_message disabled_message string or null

A human-readable message explaining why the Payment Instrument was disabled. This field provides additional context for the disabled_code.

The possible error codes/messages are:

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=enabled enabled boolean

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=expiration_month expiration_month integer [ 1 .. 12 ]

Expiration month (e.g. 12 for December).

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=expiration_year expiration_year integer >= 1

4-digit expiration year.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=fast_funds_indicator fast_funds_indicator string

Details if Fast Funds is enabled for the card.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=fingerprint fingerprint string

Unique ID that represents the tokenized card data.

Example: "FPRxxxxxxxxxxxxxxxxx"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=identity identity string

The ID of the Identity used to create the resource.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=instrument_type instrument_type string

The type of Payment Instrument.

Enum"PAYMENT_CARD""PAYMENT_CARD_PRESENT""TOKEN"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=issuer_country issuer_country string

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

NON_USA - The card was issued outside of the United States.
UNKNOWN - The processor did not return an issuer country for this particular BIN.

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"+241 more

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=last_four last_four string

Last four digits of the card.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=name name string or null

The name of the card owner.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=network_token_enabled network_token_enabled boolean

When enabled, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

Default false

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=network_token_state network_token_state string

The state of the network token. The possible enum values are as follows:

Enum"ACTIVE""CLOSED""FAILED""NOT_ENABLED""SUSPENDED""PENDING"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=payload_type payload_type string

Enum"SOURCE""DESTINATION"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=push_funds_block_indicator push_funds_block_indicator string

Details if the card is enabled to receive push-to-card disbursements.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=name_verification_results name_verification_results object or null

Details the results of verifying the cardholder's name with the issuing bank. Returns null if name_verification_details was not included in the request.

+Show 4 properties

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=security_code_verification security_code_verification string

Details the results of the Card Verification Code check.

Enum"MATCHED""UNKNOWN""UNMATCHED"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=third_party third_party string or null

This field is not applicable to payment cards.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=third_party_token third_party_token string or null

This field is not applicable to payment cards.

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=type type string

Type of Payment Instrument.

Enum"PAYMENT_CARD""TOKEN""GOOGLE_PAY""APPLE_PAY"

link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=_links_links object

+Show 7 properties

Response

application/json

CVV Verification

CVV Verification
Address Verification
Name Verification

{
  "id": "PIn8as75qLQFqQ7G4NdBUk58",
  "created_at": "2024-12-04T07:58:45.34Z",
  "updated_at": "2025-08-12T15:40:13.74Z",
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRogKWsRQks2HGaau5eGR9AF",
  "identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "instrument_type": "PAYMENT_CARD",
  "account_updater_enabled": false,
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "UNKNOWN",
  "bin": "489514",
  "brand": "VISA",
  "card_type": "UNKNOWN",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "UNKNOWN",
  "last_four": "0006",
  "name": "Collen Wade",
  "network_token_enabled": false,
  "network_token_state": "NOT_ENABLED",
  "security_code_verification": "MATCHED",
  "online_gambing_block_indicator": "testValue",
  "tags": {
    "card_name": "Business_Card"
  },
  "third_party": null,
  "third_party_token": null,
  "type": "PAYMENT_CARD",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … },
    "updates": { … }
  }
}

Was this helpful?

link to Verify Push-to-Card Eligibility Verify Push-to-Card Eligibility

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/request Request

Determine Push To Card eligibility for Push To Card customers.

Additionally, the cardholder's name is verified with the issuing bank, and the result is shown in name_verification_results. This applies to Visa and Mastercard.

SecurityView security details

BasicAuth

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/request/path Path

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=request&in=path&path=payment_instrument_id_verify payment_instrument_id_verify string required

The ID of the Payment Instrument you wish to verify.

Example: PIn8as75qLQFqQ7G4NdBUk58

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/request/body Bodyapplication/jsonrequired

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=request&path=processor processor string required

The acquiring processor. Use DUMMY_V1 to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

Default "DUMMY_V1"

Enum"DUMMY_V1""FINIX_V1"

post

/payment_instruments/{payment_instrument_id_verify}/verifications

Sandbox server https://finix.sandbox-payments-api.com/payment\_instruments/{payment\_instrument\_id\_verify}/verifications

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments/PIn8as75qLQFqQ7G4NdBUk58/verifications \
  -H 'Content-Type: application/json' \
  -d '{
    "processor": "DUMMY_V1"
  }'

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/response&c=200 Responses

Expand all

A single Verification.

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/response&c=200/headers Headers

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/response&c=200/body Bodyapplication/json

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=id id string non-empty

The ID of the resource.

Timestamp of when the object was created.

Timestamp of when the object was last updated.

ID of the Application the resource was created under.

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=identity identity string or null

This field is not applicable to payment instrument verification.

Default null

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=merchant merchant string or null

This field is not applicable to payment instrument verification.

Default null

This field is not applicable to payment instrument verification.

Default null

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=messages messages Array of strings

A codified list of reasons the verification request failed.

Default []

A message providing additional context about why the verification request failed.

Default null

A codified list of reasons the verification request failed.

Default null

The Payment Instrument sent for verification.

Default null

The payment instruction verification results.

+Show 8 properties

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=processor processor string

Name of the verification processor.

Enum"FINIX_V1""DUMMY_V1"

Raw response from the processor.

Any of:

RawRaw

Raw response from the processor.

object or null

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=state state string

The state of the payment instrument verification request.

Enum"PENDING""FAILED""SUCCEEDED"

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=trace_id trace_id string

An ID used for tracking the verification request.

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=type type string

Details the type of resource getting verified.

Value"PAYMENT_INSTRUMENT"

link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=_links_links object

+Show 3 properties

Response

application/json

{
  "id": "VI9cSUm3SDaLKtuL92Z34rK9",
  "created_at": "2025-11-07T20:36:16.90Z",
  "updated_at": "2025-11-07T20:36:16.92Z",
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "identity": null,
  "merchant": null,
  "merchant_identity": null,
  "messages": [],
  "outcome_summary": null,
  "outcomes": null,
  "payment_instrument": "PIn8as75qLQFqQ7G4NdBUk58",
  "payment_instrument_verification_details": {
    "pull_from_card_cross_border": null,
    "pull_from_card_domestic": null,
    "push_to_card_domestic": "NON_FAST_FUNDS",
    "push_to_card_cross_border": "NOT_SUPPORTED",
    "card_type": null,
    "billing_currency": null,
    "issuer_country": "UNKNOWN",
    "name_verification_results": { … }
  },
  "processor": "DUMMY_V1",
  "raw": null,
  "state": "PENDING",
  "tags": {
    "card_name": "Business_Card"
  },
  "trace_id": "63eefc66-81a3-4f24-a09d-bb7650e23943",
  "type": "PAYMENT_INSTRUMENT",
  "_links": {
    "self": { … },
    "application": { … },
    "payment_instrument": { … }
  }
}

Was this helpful?

link to Create an Apple Pay Session Create an Apple Pay Session

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/request Request

Create an apple_pay_session to process Apple Pay transactions on the web.

To create an Apple Pay Session, pass the unique validation_url (provided by Apple) while creating an apple_pay_sessions resource. Finix returns a merchantSession object that you can use to create a payment. For more information, see Apple Pay.

SecurityView security details

BasicAuth

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/request/header Headers

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&in=header&path=finix-version Finix-Version string

Default 2022-02-01

Example: 2022-02-01

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&in=header&path=content-type Content-Type string

The data type being sent in the request body must be application/json.

Example: application/json

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/request/body Bodyapplication/jsonrequired

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&path=display_name display_name string

This will be the merchant name shown to users when making a purchase via Apple Pay.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&path=domain domain string

The domain (or website) where the buyer is initiating the payment.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&path=merchant_identity merchant_identity string

The merchant_identity_id used when registering the business with Apple Pay through our registration API.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&path=validation_url validation_url string

A unique validation URL that will be provided by the Apple SDK front-end for every payment.

post

/apple_pay_sessions

Sandbox server https://finix.sandbox-payments-api.com/apple\_pay\_sessions

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/apple_pay_sessions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "display_name": "Finix Test Merchant",
    "domain": "www.finixtestmerchant.com",
    "merchant_identity": "IDmULj61C8ke6Y7qQiKENJ7",
    "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession"
  }'

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/response&c=201 Responses

Expand all

Apple Pay Session

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/response&c=201/headers Headers

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/response&c=201/body Bodyapplication/json

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=id id string non-empty

The ID of the resource.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=session_details session_details string

Details about the apple_pay_session that was created.

link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=_links_links object

+Show property

Response

application/json

{
  "id": "APPLEPAYSESSION_xxx",
  "created_at": "2021-11-22T23:58:19.50Z",
  "updated_at": "2021-11-22T23:58:19.50Z",
  "session_details": "{\"epochTimestamp\":1640213041060,\"expiresAt\":1640216641060,\"merchantSessionIdentifier\":\"SSH1524BA9006A944B8B9B8FB60227D9990_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"a5ee8554\",\"merchantIdentifier\":\"23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"domainName\":\"tj.ngrok.io\",\"displayName\":\"Christmas Shopping\",\"signature\":\"...\",\"operationalAnalyticsIdentifier\":\"Christmas Shopping:23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"retries\":0}",
  "_links": {
    "self": { … }
  }
}

Was this helpful?

link to Payment Instrument Associations Payment Instrument Associations

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

In Finix, Payment Instruments are tied to the owner of that account. For example, Payment Instruments tied to buyer will be the cards used for purchases while Payment Instruments tied to a Merchant are the bank accounts where they receive settlements.

Therefore when billing events occur that are tied to a buyer's Payment Instrument (e.g. enrolling in account updater, using Plaid for tokenization, etc) Finix cannot automatically map those fees to a specific Merchant. By default, these costs are instead charged to your Application (e.g. the Platform, Marketplace, Vertical Saas owner's account) and will be deducted from your residual. If you wish to monetize these offerings or pass the fees on to your Merchant you must explicitly link the buyers Payment Instrument to a Merchant resource using the Payment Instrument Association

Operations

post

/payment_instrument_associations

get

/payment_instrument_associations

get

/payment_instrument_associations/{payment_instrument_association_id}

put

/payment_instrument_associations/{payment_instrument_association_id}

+ Show

link to Settlements Settlements

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Settlement represents a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent a Transfer, custom Fee, or Split Transfer.

Related Guides:

Payouts

Operations

get

/settlements

get

/settlements/{settlement_id}

put

/settlements/{settlement_id}

get

/settlements/{settlement_id}/entries

delete

/settlements/{settlement_id}/entries

get

/settlements/{settlement_id}/fees

get

/settlements/{settlement_id}/funding_transfers

delete

/settlements/{settlement_id}/transfers

Show3more...

+ Show

link to Settlement Queue Entries Settlement Queue Entries

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Settlement Queue Entry resource represents an entry in the settlement queue used to track when and how a transfer is queued to be processed.

If a merchant's settlement_queue_mode is set to MANUAL, all transfers will have a Settlement Queue Entry created and will not be placed into settlement until the Settlement Queue Entry is explicitly released.

Related Guides:

Account Structures and Settlements

Operations

get

/settlement_queue_entries

put

/settlement_queue_entries

get

/settlement_queue_entries/{settlement_queue_entry_id}

+ Show

link to Split Transfers Split Transfers

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Transactions can be split among different merchants. A Split Transfer shows how funds from a split Transfer were distributed into a merchant's Settlement.

Related Guides:

Split Transactions

Operations

get

/fees

get

/split_transfers

get

/split_transfers/{split_transfer_id}

+ Show

link to Transfers Transfers

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Transfer represents any flow of funds either to or from a Payment Instrument. All payments in Finix are represented by a Transfer.

Related Guides:

Operations

post

/transfers

get

/transfers

get

/transfers/{transfer_id}

put

/transfers/{transfer_id}

post

/transfers/{transfer_id}/reversals

get

/transfers/{transfer_id}/reversals

+ Show

link to Users Users

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A User resource represents a pair of API keys which are used to perform authenticated requests against the Finix API. When making authenticated requests via HTTP basic access authentication the ID of a User resource maps to the username, while the password corresponds to the password (i.e. secret key).

The password field for a User resource is only returned during the initial creation. Any following GET requests to the resource returns the password field as null for security purposes.

Related Guides:

Account Structure

Operations

get

/users

get

/users/{user_id}

put

/users/{user_id}

+ Show

link to Verifications Verifications

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Verifications are used to verify Merchants and Payment Instruments.

For Merchants, a verification represents an attempt to onboard and underwrite a Merchant.

For Payment Instruments, a verification represents getting additional information from the card brands to verify a card is eligible for push to card.

Related Guides:

Operations

get

/merchants/{merchant_id}/verifications

get

/verifications

get

/verifications/{verification_id}

+ Show

link to Webhooks Webhooks

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Webhooks let you set up integrations that subscribe to automated notifications (events) on the Finix API. When an enabled event occurs, Finix sends an HTTP POST payload to the Webhook's configured URL.

Related Guides:

Operations

post

/webhooks

get

/webhooks

get

/webhooks/{webhook_id}

put

/webhooks/{webhook_id}

+ Show

link to Gateway Integrations Gateway Integrations

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Gateway Integration represents a connection to a third-party payment gateway. At this time, the only supported gateway is Cybersource.

Cybersource is a Visa-owned payment gateway that integrates with Finix to provide secure payment processing and fraud management. Finix handles merchant onboarding and payouts through a unified API, while Cybersource manages gateway routing and fraud prevention for global card acceptance.

Operations

post

/gateway_integrations

get

/gateway_integrations

get

/gateway_integrations/{gateway_integration_id}

+ Show

link to Receipts Receipts

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

The Receipt resource generates a receipt for Transfers or Authorizations. You can then send the Receipt via Email, SMS, or use the information from the Receipt to send it yourself.

Related Guides:

Receipts for Online Payments

Operations

post

/receipts

get

/receipts/{receipt_id}

post

/receipts/{receipt_id}/delivery_attempts

get

/receipts/{receipt_id}/delivery_attempts

+ Show

link to Subscriptions Subscriptions

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Subscription resource represents a recurring charge to a Payment Instrument at regular intervals. Subscribers can be buyers, customers, or merchants.

Subscriptions are supported for USA and Canadian merchants.

When creating a Subscription, you have the option to use a Subscription Plan.

Limitations:

Supported countries: Subscriptions are available in the United States and Canada.
Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments ( ACH in the USA).
Approved merchants: At this time, only approved merchants with one of the following processors can create subscriptions: DUMMY_V1 and FINIX_V1.

Related Guides:

Operations

post

/subscriptions

get

/subscriptions

get

/subscriptions/{subscription_id}

put

/subscriptions/{subscription_id}

delete

/subscriptions/{subscription_id}

post

/subscriptions/{subscription_id}/subscription_balance_entries

get

/subscriptions/{subscription_id}/subscription_balance_entries

put

/subscriptions/{subscription_id}/subscription_balance_entries/{subscription_balance_entry_id}

+ Show

link to Subscription Plans Subscription Plans

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Subscription Plan resource is a template with set recurring costs and frequencies that can be reused across multiple Subscription resources.

Related Guides:

Operations

post

/subscription_plans

get

/subscription_plans

get

/subscription_plans/{subscription_plan_id}

put

/subscription_plans/{subscription_plan_id}

+ Show

link to Transfer Attempts Transfer Attempts

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

When a user attempts to make a payment using a Checkout Form or Payment Link, or a recipient submitting details with a Payout Link—a Transfer Attempt is created.

Using transfer attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link.

Checkout Forms and Payment Links support authorizations. If a payment made with them is an authorization, the Transfer Attempt result shows is_authorization: true and references the authorization (authorization_id).

Each Transfer Attempt has as reference to a transfer_id to allow you to query it for additional data.

Related Guides:

Transfer Attempts

Operations

get

/transfer_attempts

get

/transfer_attempts/{transfer_attempt_id}

+ Show

link to Balances Balances

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Balance resource represents the current financial state of an Application identified by the linked_to query parameter.

It tracks the state of funds processed through the system, including amounts that are:

available_amount for immediate use or disbursement.
pending_amount due to processing times, holds, or other constraints.
posted_amount, which reflects the total sum (including both available and pending funds).

Operations

get

/balances

get

/balances/{balance_id}

get

/balances/{balance_id}/balance_entries

get

/balance_entries/{balance_entry_id}

+ Show

link to Balance Adjustments Balance Adjustments

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Balance Adjustment modifies the account Balance by adding funds (a 'top-up') or reducing funds for Payouts. Each adjustment is linked to a specific payment rail (e.g., ACH, card, wire).

Related Guides:

Adding Funds to your Finix Balance

Operations

post

/balance_adjustments

get

/balance_adjustments

+ Show

link to Disbursement Rules Disbursement Rules

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

For the Payouts product, when a payout is executed, such as a Push-To-Card or ACH transaction, Finix checks the transaction against velocity rules and balance rules.

Rules establish limits on transactions. For example, there may be a daily transaction limit of 100 transactions (count_limit) or a monthly volume limit of $100,000 (volume_limit). If a transaction exceeds any defined limit, the transaction is rejected.

Rules are set for entities involved in transactions, including the application, senders, and recipients.

The "Application" represents the customer to whom Finix is applying the rules. Application rules are set solely by Finix and are applied to every single transaction.

You can establish rules for "senders" and "recipients," referring to the parties involved in transactions:

In the case of a PULL_FROM_CARD or PULL_FROM_ACH transaction, sender rules are applied (either card or ACH rules). The "target" of the pull is referred to as the "sender," specifically the customer of Finix's client.
Conversely, in the case of a PUSH_FROM_CARD or PUSH_FROM_ACH transaction, the recipient rules are applied (either card or ACH rules). The "target" of the push is referred to as the "recipient," which is, in turn, the customer of Finix's client.

Operations

get

/disbursement_rules

get

/disbursement_rules/current_usages

+ Show