# Finix API Reference    Copy      - Copy for LLM          Copy page as Markdown for LLMs    - [View as Markdown\ \ Open this page as Markdown](https://docs.finix.com/api.md) - [Open in ChatGPT\ \ Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi.md+and+answer+questions+based+on+the+content.) - [Open in Claude\ \ Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi.md+and+answer+questions+based+on+the+content.) - 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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#section/Environments) Environments

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

1. A Sandbox environment for developing and testing your integration.
2. 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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](https://docs.finix.com/additional-resources/developers/implementation-and-testing/error-codes/). Also, you can [test for specific errors and responses](https://docs.finix.com/additional-resources/developers/implementation-and-testing/testing-your-integration/).

| 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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/versioning/).

* * *

## [link  to section/Postman-Collection](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#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](/content/site-root.html)

Finix
[support@finix.com](mailto:support@finix.com)

Languages

cURL

Servers

Sandbox server

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

## [link to Authorizations](https://docs.finix.com/api/authorizations) Authorizations

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/authorizations.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fauthorizations.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fauthorizations.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Auth and Captures](https://docs.finix.com/guides/online-payments/payment-features/auth-and-captures)
- [Level 2 and 3 Processing](https://docs.finix.com/guides/online-payments/payment-features/level-2-level-3-processing/)
- [POS Integration](https://docs.finix.com/guides/in-person-payments/building-your-integration/pos-integration)
- [Buyer Charges](https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/)

Operations

post

/authorizations

get

/authorizations

get

/authorizations/{authorization\_id}

put

/authorizations/{authorization\_id}

put

/authorizations/{authorization\_id\_void\_to}

\+ Show

## [link to Compliance Forms](https://docs.finix.com/api/compliance-forms) Compliance Forms

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/compliance-forms.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fcompliance-forms.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fcompliance-forms.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Managing PCI Compliance](https://docs.finix.com/guides/managing-operations/security-compliance/managing-pci-compliance)
- [PCI DSS Compliance](https://docs.finix.com/guides/managing-operations/security-compliance/pci-dss-compliance)

Operations

get

/compliance\_forms/{compliance\_form\_id}

put

/compliance\_forms/{compliance\_form\_id}

get

/compliance\_forms

\+ Show

## [link to Devices](https://docs.finix.com/api/devices) Devices

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/devices.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fdevices.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fdevices.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/in-person-payments).

**Related Guides:**

- [In-Person Payments](https://docs.finix.com/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](https://docs.finix.com/api/disputes) Disputes

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/disputes.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fdisputes.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fdisputes.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/after-the-payment/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](https://docs.finix.com/api/fees) Fees

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/fees.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ffees.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ffees.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/api/fee-profiles) Fee Profiles

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/fee-profiles.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ffee-profiles.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ffee-profiles.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/platform-payments/monetizing-payments/merchant-fee-profiles)

Operations

post

/fee\_profiles

get

/fee\_profiles

get

/fee\_profiles/{fee\_profile\_id}

\+ Show

## [link to Files](https://docs.finix.com/api/files) Files

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/files.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ffiles.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ffiles.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [File Uploads](https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-uploading-files)
- [Update Requests](https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests)

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](https://docs.finix.com/api/identities) Identities

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/identities.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fidentities.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fidentities.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Getting Started](https://docs.finix.com/guides/getting-started)
- [Onboarding Sellers](https://docs.finix.com/guides/platform-payments/onboarding-sellers)
- [Push to Card](https://docs.finix.com/guides/payouts/card-payouts/)

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](https://docs.finix.com/api/merchants) Merchants

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/merchants.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fmerchants.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fmerchants.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Getting Started](https://docs.finix.com/guides/getting-started)
- [Onboarding Sellers](https://docs.finix.com/guides/platform-payments/onboarding-sellers)

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](https://docs.finix.com/api/onboarding-forms) Onboarding Forms

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/onboarding-forms.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fonboarding-forms.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fonboarding-forms.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api)

Operations

post

/onboarding\_forms

get

/onboarding\_forms/{onboarding\_form\_id}

post

/onboarding\_forms/{onboarding\_form\_id}/links

\+ Show

## [link to Payment Instruments](https://docs.finix.com/api/payment-instruments) Payment Instruments

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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`](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument#Identities). 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:**

- [Using Hosted Fields](https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms)
- [Getting Started](https://docs.finix.com/guides/getting-started)

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](https://docs.finix.com/api/payment-instruments/createpaymentinstrument) Create a Payment Instrument

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/createpaymentinstrument.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreatepaymentinstrument.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreatepaymentinstrument.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/createpaymentinstrument\#payment-instruments/createpaymentinstrument/request](https://docs.finix.com/api/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](https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms) or the javascript client to remain out of PCI scope.

SecurityView security details

BasicAuth

[link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/request/header](https://docs.finix.com/api/payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/request/header) Headers

[link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&in=header&path=finix-version](https://docs.finix.com/api/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](https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/versioning).

Default 2022-02-01

Example: 2022-02-01

[link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=request&in=header&path=content-type](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createpaymentinstrument\#payment-instruments/createpaymentinstrument/response&c=201) Responses

1. 201
2. 400
3. 401
4. 403
5. 406
6. 422

Expand all

A single Payment Instrument

[link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/response&c=201/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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.

Default false

[link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/address](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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`.

Default false

[link to /payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/network_token_state](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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

1. 201
2. 400
3. 401
4. 403
5. 406
6. 422

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](https://docs.finix.com/api/payment-instruments/listpaymentinstruments) List Payment Instruments

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/listpaymentinstruments.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Flistpaymentinstruments.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Flistpaymentinstruments.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/listpaymentinstruments\#payment-instruments/listpaymentinstruments/request](https://docs.finix.com/api/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.](https://docs.finix.com/api/section/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](https://docs.finix.com/api/payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/request/query) Query

[link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=after_cursor](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/section/tags).

Example: tags.key=card\_type

[link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=tags.value](https://docs.finix.com/api/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](https://docs.finix.com/api/section/tags).

Example: tags.value=business\_card

[link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=query&path=updated_at.gte](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/request/header) Headers

[link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=header&path=finix-version](https://docs.finix.com/api/payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=request&in=header&path=finix-version) Finix-Version _string_

Default 2022-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](https://docs.finix.com/api/payment-instruments/listpaymentinstruments\#payment-instruments/listpaymentinstruments/response&c=200) Responses

1. 200
2. 401
3. 403
4. 406
5. 422

Expand all

List of `Payment Instrument` resources

[link to /payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/response&c=200/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/listpaymentinstruments#payment-instruments/listpaymentinstruments/t=response&c=200&path=_links)\_links _object_

+Show 2 properties

Response

1. 200
2. 401
3. 403
4. 406
5. 422

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](https://docs.finix.com/api/payment-instruments/getpaymentinstrument) Fetch a Payment Instrument

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/getpaymentinstrument.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fgetpaymentinstrument.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fgetpaymentinstrument.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/getpaymentinstrument\#payment-instruments/getpaymentinstrument/request](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/request/header) Headers

[link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=request&in=header&path=finix-version](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/getpaymentinstrument\#payment-instruments/getpaymentinstrument/response&c=200) Responses

1. 200
2. 401
3. 403
4. 404
5. 406

Expand all

A single `Payment Instrument`

[link to /payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/response&c=200/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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.

- 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/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/third_party](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/getpaymentinstrument#payment-instruments/getpaymentinstrument/t=response&c=200&path=&oneof=0/_links)\_links _object_

+Show 7 properties

Response

1. 200
2. 401
3. 403
4. 404
5. 406

application/json

#### Was this helpful?

## [link to Update a Payment Instrument](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument) Update a Payment Instrument

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fupdatepaymentinstrument.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fupdatepaymentinstrument.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/updatepaymentinstrument\#payment-instruments/updatepaymentinstrument/request](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument\#payment-instruments/updatepaymentinstrument/response&c=200) Responses

1. 200
2. 400
3. 401
4. 403
5. 404
6. 406

Expand all

A single `Payment Instrument`

[link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/response&c=200/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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.

+Show property

[link to /payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/third_party](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://plaid.com/docs/auth/partnerships/finix/) and [Finix's Plaid guide](https://docs.finix.com/guides/online-payments/bank-payments/plaid-integration).

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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument#payment-instruments/updatepaymentinstrument/t=response&c=200&path=&oneof=0&oneof=0/_links)\_links _object_

+Show 6 properties

Response

1. 200
2. 400
3. 401
4. 403
5. 404
6. 406

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](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries) List Instrument History Entries

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Flistinstrumenthistoryentries.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Flistinstrumenthistoryentries.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/listinstrumenthistoryentries\#payment-instruments/listinstrumenthistoryentries/request](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/request/query) Query

[link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=query&path=after_cursor](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/request/header) Headers

[link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=header&path=finix-version](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=request&in=header&path=finix-version) Finix-Version _string_

Default2022-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](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries\#payment-instruments/listinstrumenthistoryentries/response&c=200) Responses

1. 200
2. 401
3. 403
4. 404
5. 406
6. 422

Expand all

List of `Instrument History Entry` objects.

[link to /payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/response&c=200/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries#payment-instruments/listinstrumenthistoryentries/t=response&c=200&path=_links)\_links _object_

+Show 2 properties

Response

1. 200
2. 401
3. 403
4. 404
5. 406
6. 422

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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverification) Verify CVV, AVS, and Name

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverification.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreatepaymentinstrumentverification.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreatepaymentinstrumentverification.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/createpaymentinstrumentverification\#payment-instruments/createpaymentinstrumentverification/request](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverification\#payment-instruments/createpaymentinstrumentverification/response&c=200) Responses

1. 200
2. 400
3. 401
4. 403
5. 404
6. 406

Expand all

A single Payment Instrument.

[link to /payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/response&c=200/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverification#payment-instruments/createpaymentinstrumentverification/t=response&c=200&path=_links)\_links _object_

+Show 7 properties

Response

1. 200
2. 400
3. 401
4. 403
5. 404
6. 406

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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard) Verify Push-to-Card Eligibility

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreatepaymentinstrumentverificationpushtocard.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreatepaymentinstrumentverificationpushtocard.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/createpaymentinstrumentverificationpushtocard\#payment-instruments/createpaymentinstrumentverificationpushtocard/request](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard\#payment-instruments/createpaymentinstrumentverificationpushtocard/request) Request

Determine Push To Card eligibility for [Push To Card](https://docs.finix.com/guides/payouts/card-payouts) 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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/request/body) Bodyapplication/jsonrequired

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=request&path=processor](https://docs.finix.com/api/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](https://docs.finix.com/guides/getting-started/support-at-finix/).

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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard\#payment-instruments/createpaymentinstrumentverificationpushtocard/response&c=200) Responses

1. 200
2. 400
3. 401
4. 403
5. 404
6. 406

Expand all

A single `Verification`.

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/response&c=200/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=id) id _string_ _non-empty_

The ID of the resource.

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=created_at](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=created_at) created\_at _string_ _(date-time)_

Timestamp of when the object was created.

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=updated_at](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=updated_at) updated\_at _string_ _(date-time)_

Timestamp of when the object was last updated.

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=application](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=application) application _string_ _non-empty_

ID of the `Application` the resource was created under.

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=identity](https://docs.finix.com/api/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](https://docs.finix.com/api/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

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=merchant_identity](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=merchant_identity) merchant\_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=messages](https://docs.finix.com/api/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 \[\]

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=outcome_summary](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=outcome_summary) outcome\_summary _string or null_

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

Default null

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=outcomes](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=outcomes) outcomes _Array of objects or null_

A codified list of reasons the verification request failed.

Default null

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=payment_instrument](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=payment_instrument) payment\_instrument _string_

The `Payment Instrument` sent for verification.

Default null

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=payment_instrument_verification_details](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=payment_instrument_verification_details) payment\_instrument\_verification\_details _object_

The payment instruction verification results.

+Show 8 properties

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=processor](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=processor) processor _string_

Name of the verification processor.

Enum"FINIX\_V1""DUMMY\_V1"

[link to /payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=raw](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=raw) raw _(object or null) or (string or null)_

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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverificationpushtocard#payment-instruments/createpaymentinstrumentverificationpushtocard/t=response&c=200&path=_links)\_links _object_

+Show 3 properties

Response

1. 200
2. 400
3. 401
4. 403
5. 404
6. 406

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](https://docs.finix.com/api/payment-instruments/createapplepaysession) Create an Apple Pay Session

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instruments/createapplepaysession.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreateapplepaysession.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instruments%2Fcreateapplepaysession.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

#### [link to /payment-instruments/createapplepaysession\#payment-instruments/createapplepaysession/request](https://docs.finix.com/api/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](https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay).

SecurityView security details

BasicAuth

[link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/request/header](https://docs.finix.com/api/payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/request/header) Headers

[link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&in=header&path=finix-version](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/request/body) Bodyapplication/jsonrequired

[link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=request&path=display_name](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createapplepaysession\#payment-instruments/createapplepaysession/response&c=201) Responses

1. 201
2. 400
3. 401
4. 403
5. 404
6. 406
7. 422

Expand all

Apple Pay Session

[link to /payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/response&c=201/headers](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/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](https://docs.finix.com/api/payment-instruments/createapplepaysession#payment-instruments/createapplepaysession/t=response&c=201&path=_links)\_links _object_

+Show property

Response

1. 201
2. 400
3. 401
4. 403
5. 404
6. 406
7. 422

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](https://docs.finix.com/api/payment-instrument-associations) Payment Instrument Associations

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/payment-instrument-associations.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instrument-associations.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fpayment-instrument-associations.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/api/settlements) Settlements

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/settlements.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsettlements.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsettlements.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/api/merchants). A `Settlement Entry` can represent a [Transfer](https://docs.finix.com/api/transfers), custom [Fee](https://docs.finix.com/api/fees), or [Split Transfer](https://docs.finix.com/api/split-transfers).

**Related Guides:**

- [Payouts](https://docs.finix.com/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](https://docs.finix.com/api/settlement-queue-entries) Settlement Queue Entries

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/settlement-queue-entries.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsettlement-queue-entries.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsettlement-queue-entries.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/api/settlement-queue-entries/updatesettlementqueueentries).

**Related Guides:**

- [Account Structures and Settlements](https://docs.finix.com/additional-resources/developers/resources-and-payment-flows/key-resources#settlements)

Operations

get

/settlement\_queue\_entries

put

/settlement\_queue\_entries

get

/settlement\_queue\_entries/{settlement\_queue\_entry\_id}

\+ Show

## [link to Split Transfers](https://docs.finix.com/api/split-transfers) Split Transfers

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/split-transfers.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsplit-transfers.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsplit-transfers.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/online-payments/payment-features/split-transactions)

Operations

get

/fees

get

/split\_transfers

get

/split\_transfers/{split\_transfer\_id}

\+ Show

## [link to Transfers](https://docs.finix.com/api/transfers) Transfers

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/transfers.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ftransfers.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ftransfers.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Online Payments Quickstart](https://docs.finix.com/guides/online-payments/online-payments-quickstart)
- [Level 2 and 3 Processing](https://docs.finix.com/guides/online-payments/payment-features/level-2-level-3-processing/)
- [POS Integration](https://docs.finix.com/guides/in-person-payments/building-your-integration/pos-integration)
- [Buyer Charges](https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/),
- [ACH (eCheck) Direct Debit](https://docs.finix.com/guides/online-payments/bank-payments/ach-direct-debits)

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](https://docs.finix.com/api/users) Users

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/users.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fusers.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fusers.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/additional-resources/developers/resources-and-payment-flows/key-resources#account-structure)

Operations

get

/users

get

/users/{user\_id}

put

/users/{user\_id}

\+ Show

## [link to Verifications](https://docs.finix.com/api/verifications) Verifications

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/verifications.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fverifications.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fverifications.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

`Verifications` are used to verify [Merchants](https://docs.finix.com/api/merchants) and [Payment Instruments](https://docs.finix.com/api/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:**

- [Onboarding with the API](https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api)
- [Push to Card](https://docs.finix.com/guides/payouts/card-payouts)

Operations

get

/merchants/{merchant\_id}/verifications

get

/verifications

get

/verifications/{verification\_id}

\+ Show

## [link to Webhooks](https://docs.finix.com/api/webhooks) Webhooks

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/webhooks.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fwebhooks.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fwebhooks.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Webhooks](https://docs.finix.com/additional-resources/developers/webhooks)
- [Integrating Webhooks](https://docs.finix.com/additional-resources/developers/webhooks/integrating-into-webhooks)
- [Webhook Events](https://docs.finix.com/additional-resources/developers/webhooks/webhook-events)

Operations

post

/webhooks

get

/webhooks

get

/webhooks/{webhook\_id}

put

/webhooks/{webhook\_id}

\+ Show

## [link to Gateway Integrations](https://docs.finix.com/api/gateway-integrations) Gateway Integrations

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/gateway-integrations.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fgateway-integrations.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fgateway-integrations.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/api/receipts) Receipts

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/receipts.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Freceipts.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Freceipts.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

Install MCP server on Cursor

- Connect to VS Code

Install MCP server on VS Code

The `Receipt` resource generates a receipt for [Transfers](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument#Transfers) or [Authorizations](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument#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](https://docs.finix.com/guides/online-payments/payment-features/sending-receipts)

Operations

post

/receipts

get

/receipts/{receipt\_id}

post

/receipts/{receipt\_id}/delivery\_attempts

get

/receipts/{receipt\_id}/delivery\_attempts

\+ Show

## [link to Subscriptions](https://docs.finix.com/api/subscriptions) Subscriptions

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/subscriptions.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsubscriptions.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsubscriptions.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/online-payments/bank-payments/ach-direct-debits) 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:**

- [Creating Subscriptions](https://docs.finix.com/guides/subscriptions)
- [Creating Subscription Plans](https://docs.finix.com/guides/subscriptions/subscription-plans)
- [Recurring Payments Guidelines](https://docs.finix.com/guides/subscriptions/recurring-payment-guidelines)

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](https://docs.finix.com/api/subscription-plans) Subscription Plans

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/subscription-plans.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsubscription-plans.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fsubscription-plans.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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

- [Creating Subscriptions Plans](https://docs.finix.com/guides/subscriptions/subscription-plans)
- [Creating Subscriptions](https://docs.finix.com/guides/subscriptions)
- [Recurring Payments Guidelines](https://docs.finix.com/guides/subscriptions/recurring-payment-guidelines)

Operations

post

/subscription\_plans

get

/subscription\_plans

get

/subscription\_plans/{subscription\_plan\_id}

put

/subscription\_plans/{subscription\_plan\_id}

\+ Show

## [link to Transfer Attempts](https://docs.finix.com/api/transfer-attempts) Transfer Attempts

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/transfer-attempts.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ftransfer-attempts.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Ftransfer-attempts.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/low-code-no-code/payment-links), or a recipient submitting details with a [Payout Link](https://docs.finix.com/guides/payouts/payout-links)—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](https://docs.finix.com/low-code-no-code/manage-low-code-no-code/transfer-attempts)

Operations

get

/transfer\_attempts

get

/transfer\_attempts/{transfer\_attempt\_id}

\+ Show

## [link to Balances](https://docs.finix.com/api/balances) Balances

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/balances.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fbalances.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fbalances.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/api/balance-adjustments) Balance Adjustments

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/balance-adjustments.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fbalance-adjustments.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fbalance-adjustments.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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](https://docs.finix.com/guides/payouts/adding-funds)

Operations

post

/balance\_adjustments

get

/balance\_adjustments

\+ Show

## [link to Disbursement Rules](https://docs.finix.com/api/disbursement-rules) Disbursement Rules

Copy

- Copy for LLM

Copy page as Markdown for LLMs

- [View as Markdown\\
\\
Open this page as Markdown](https://docs.finix.com/api/disbursement-rules.md)
- [Open in ChatGPT\\
\\
Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fdisbursement-rules.md+and+answer+questions+based+on+the+content.)
- [Open in Claude\\
\\
Get insights from Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fdisbursement-rules.md+and+answer+questions+based+on+the+content.)
- Connect to Cursor

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