A single Payment Instrument Association
Finix API Reference (2022-02-01)
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.
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-a62908e5b30eFinix provides two environments with distinct base URLs to make API requests.
- A Sandbox environment for developing and testing your integration.
- A Live environment for processing payments.
These environments are entirely separate and do not share API Credentials.
| Environment | Endpoint URL |
|---|---|
| Sandbox | https://finix.sandbox-payments-api.com |
| Live | https://finix.live-payments-api.com |
Live Access
To get access to the Live environment, please reach out to your Finix point-of-contact.
Finix uses HTTP codes to communicate whether requests succeeded or failed. Requests to Finix's API return responses within less than one second.
However, communications between card networks and processors can increase response latency. Additionally, response latency for card-present devices can be higher depending on how quickly buyers complete the transaction on payment terminals.
Due of this, requests to the Finix API have a maximum timeout of 5 minutes.
For more details, see Error Codes. Also, you can test for specific errors and responses.
| Code | Definition | Explanation |
|---|---|---|
400 | Bad Request | We could not parse your request. Verify you are providing valid JSON. |
401 | Unauthorized | We could not authenticate your request. Verify your username and password are correct. |
402 | Upstream Processor Error | Errors caused by 3rd-party service(s). |
403 | Forbidden | Your credentials do not have the correct permissions to perform the request. |
404 | Not Found | We could not find the specified resource. |
405 | Method Not Allowed | The specified resource does not support the HTTP Method used to submit the request. |
406 | Not Acceptable | The server could accept the submitted request. Confirm how the request was formatted and submitted. |
409 | Conflict | The submitted request conflicts with the current state of the server. |
422 | Unprocessable Entity | The parameters were valid, but the request failed. Usually, the error involves misunderstanding of how to perform the request (e.g., creating a transfer with a seller that is not-yet-approved). |
500 | Internal Server Error | We had a problem with our server. Try again later. |
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.
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-a62908e5b30eAs 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.
Overview
URL
Finix
Languages
Servers
Sandbox server
https://finix.sandbox-payments-api.com/
Production server
https://finix.live-payments-api.com/
Devices
A Device resource represents a Point-of-Sale terminal. Devices are used for In-Person transactions.
Related Guides:
Operations
Payment Instruments
A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.
A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.
Including an address when creating a Payment Instrument can lower interchange on credit card transactions.
Related Guides:
Operations
Payment Instrument Associations
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
Headers
Bodyapplication/jsonrequiredSpecify the API version of your request. For more details, see Versioning.
Default 2022-02-01
Example: 2022-02-01
The ID of the Merchant that fees will be applied to.
Example: "MUcgYZswyRfqSSbvMsxuaHxZ"
The ID of the Payment Instrument whose events will be charged to the specified merchant.
Example: "PIcgYZswyRfqSSbvMsxuaHxZ"
- Sandbox serverhttps://finix.sandbox-payments-api.com/payment_instrument_associations
- Production serverhttps://finix.live-payments-api.com/payment_instrument_associations
curl -i -X POST \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
https://finix.sandbox-payments-api.com/payment_instrument_associations \
-H 'Content-Type: application/json' \
-H 'Finix-Version: 2022-02-01' \
-d '{
"merchant_id": "MUcgYZswyRfqSSbvMsxuaHxZ",
"payment_instrument_id": "PIcgYZswyRfqSSbvMsxuaHxZ"
}'A response header indicating the date and time of the API request.
Example: "Tue, 08 Jul 2025 17:38:01 GMT"
This response header indicating the role of the user who sent the API request.
Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
Example: "ROLE_PARTNER"
The ID of the Payment Instrument Association.
Example: "instrument_association_9xZ6pUo5fXb7aAB4o3TqkK"
The ID of the Payment Instrument whose events will be charged to the specified merchant.
Example: "PIcgYZswyRfqSSbvMsxuaHxZ"
The ID of the Merchant that fees will be applied to.
Example: "MUcgYZswyRfqSSbvMsxuaHxZ"
Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual
keysis 40. - Maximum character length for individual
valuesis 500. (For example,order_number: 25,item_type: produce,department: sales)
Response
application/json
{ "id": "payment_instrument_association_iCfFgdmmVF3koH1gqxmgdV", "created_at": "2026-03-26T01:31:42.33Z", "updated_at": "2026-03-26T01:31:42.33Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "enabled": true, "merchant_id": "MUcgYZswyRfqSSbvMsxuaHxZ", "payment_instrument_id": "PIdw4YZhGVryETJXjiXVXCWH", "tags": {}, "_links": { "self": { … } } }
Headers
Specify the API version of your request. For more details, see Versioning.
Default 2022-02-01
Example: 2022-02-01
- Sandbox serverhttps://finix.sandbox-payments-api.com/payment_instrument_associations
- Production serverhttps://finix.live-payments-api.com/payment_instrument_associations
curl "https://finix.sandbox-payments-api.com/payment_instrument_associations" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bdaList of Instrument Association resources
A response header indicating the date and time of the API request.
Example: "Tue, 08 Jul 2025 17:38:01 GMT"
This response header indicating the role of the user who sent the API request.
Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
Example: "ROLE_PARTNER"
Response
application/json
{ "_embedded": { "payment_instrument_associations": [ … ] }, "_links": { "self": { … }, "next": { … } }, "page": { "limit": 100, "next_cursor": "payment_instrument_association_iCfFgdmmVF3koH1gqxmgdV" } }
Headers
Specify the API version of your request. For more details, see Versioning.
Default 2022-02-01
Example: 2022-02-01
- Sandbox serverhttps://finix.sandbox-payments-api.com/payment_instrument_associations/{payment_instrument_association_id}
- Production serverhttps://finix.live-payments-api.com/payment_instrument_associations/{payment_instrument_association_id}
curl "https://finix.sandbox-payments-api.com/payment_instrument_associations/payment_instrument_association_iCfFgdmmVF3koH1gqxmgdV" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bdaA single Payment Instrument Association
A response header indicating the date and time of the API request.
Example: "Tue, 08 Jul 2025 17:38:01 GMT"
This response header indicating the role of the user who sent the API request.
Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
Example: "ROLE_PARTNER"
The ID of the Payment Instrument Association.
Example: "instrument_association_9xZ6pUo5fXb7aAB4o3TqkK"
The ID of the Payment Instrument whose events will be charged to the specified merchant.
Example: "PIcgYZswyRfqSSbvMsxuaHxZ"
The ID of the Merchant that fees will be applied to.
Example: "MUcgYZswyRfqSSbvMsxuaHxZ"
Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual
keysis 40. - Maximum character length for individual
valuesis 500. (For example,order_number: 25,item_type: produce,department: sales)
Response
application/json
{ "id": "payment_instrument_association_iCfFgdmmVF3koH1gqxmgdV", "created_at": "2026-03-26T01:31:42.33Z", "updated_at": "2026-03-26T01:31:42.33Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "enabled": true, "merchant_id": "MUcgYZswyRfqSSbvMsxuaHxZ", "payment_instrument_id": "PIdw4YZhGVryETJXjiXVXCWH", "tags": {}, "_links": { "self": { … } } }
Settlements
A Settlement represents a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent a Transfer, custom Fee, or Split Transfer.
Related Guides:
Operations
Settlement Queue Entries
A Settlement Queue Entry resource represents an entry in the settlement queue used to track when and how a transfer is queued to be processed.
If a merchant's settlement_queue_mode is set to MANUAL, all transfers will have a Settlement Queue Entry created and will not be placed into settlement until the Settlement Queue Entry is explicitly released.
Related Guides:
Operations
Users
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:
Operations
Checkout Forms
Checkout Forms are a low-code solution that enables you to create a customizable payment page where buyers can easily enter their payment details and submit a payment on both desktop and mobile devices.
With Checkout Forms, you can quickly create checkout pages and accept payments from buyers with minimal development work.
Related Guides:
Operations
Gateway Integrations
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
Payout Links
A Payout Link is a unique, one-time link you can send via email or text to a recipient for fast and secure payouts. For card-based payouts, funds are typically available within minutes.
Payout Links can be used for various purposes, including insurance payments, sales commissions, and more. Each link can be customized to display your brand name and logo, providing a seamless experience for recipients.
Related Guides:
Operations
Receipts
The Receipt resource generates a receipt for Transfers or Authorizations. You can then send the Receipt via Email, SMS, or use the information from the Receipt to send it yourself.
Related Guides:
Operations
Subscriptions
A Subscription resource represents a recurring charge to a Payment Instrument at regular intervals. Subscribers can be buyers, customers, or merchants.
Subscriptions are supported for USA and Canadian merchants.
When creating a Subscription, you have the option to use a Subscription Plan.
Limitations:
- Supported countries: Subscriptions are available in the United States and Canada.
- Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments (ACH in the USA).
- Approved merchants: At this time, only approved merchants with one of the following processors can create subscriptions:
DUMMY_V1andFINIX_V1.
Related Guides:
Operations
Transfer Attempts
When a user attempts to make a payment using a Checkout Form or Payment Link, or a recipient submitting details with a Payout Link—a Transfer Attempt is created.
Using transfer attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link.
Checkout Forms and Payment Links support authorizations. If a payment made with them is an authorization, the Transfer Attempt result shows is_authorization: true and references the authorization (authorization_id).
Each Transfer Attempt has as reference to a transfer_id to allow you to query it for additional data.
Related Guides:
Operations
Balances
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_amountfor immediate use or disbursement.pending_amountdue to processing times, holds, or other constraints.posted_amount, which reflects the total sum (including both available and pending funds).
Operations
Disbursement Rules
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_CARDorPULL_FROM_ACHtransaction, 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_CARDorPUSH_FROM_ACHtransaction, 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
Applications
The Application resource represents your app. For example, an iOS app, website, online marketplace, SaaS platform, etc. – any web service that connects buyers (i.e. customers) and sellers (i.e. merchants). In other words, an Application is a resource that represents the program you're integrating with Finix and using to connect with customers (i.e. buyers).
Related Guides:
Operations
Balance Transfers
Our Balance Transfers API provides platforms the option to create a money movement between their FBO (For the Benefit Of) Settlement account and their operating account. This is only available for Finix Core customers with LITLE_V1 credentials.
If you have any questions, please reach out to your Finix point of contact or contact the Finix Support team.
Operations
Merchant Profiles
A Merchant Profile connects a Merchant to its profiles, including a Fee Profile, a Payout Profile, and a Risk Profile.
Every Merchant has exactly one Merchant Profile. When a Merchant is created, a Merchant Profile is automatically generated and seeded with the profiles defined on the Application Profile. You can then update the Merchant Profile to assign a different Fee Profile or Risk Profile, overriding the application-level defaults for that specific Merchant.
Related Guides:
Operations
Verifications
Verifications are used to verify Identities and Payment Instruments.
For Identities, a verification represents an attempt to onboard and underwrite an identity.
For Payment Instruments, a verification represents getting additional information from the card brands to verify a card is eligible for push to card.
Related Guides:
Operations