# 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/section/authentication\#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/section/authentication\#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/section/authentication\#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/section/authentication\#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/section/authentication\#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/section/authentication\#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/section/authentication\#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/section/authentication\#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/section/authentication#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 \+ Show ## [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/section/authentication#Transfers) or [Authorizations](https://docs.finix.com/api/section/authentication#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 ## [link to Create a Balance Adjustment](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment) Create a Balance Adjustment 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/createbalanceadjustment.md) - [Open in ChatGPT\\ \\ Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fbalance-adjustments%2Fcreatebalanceadjustment.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%2Fcreatebalanceadjustment.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 /balance-adjustments/createbalanceadjustment\#balance-adjustments/createbalanceadjustment/request](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment\#balance-adjustments/createbalanceadjustment/request) RequestExpand all Create a `Balance Adjustment` to increase (i.e., 'Top-up') or decrease your account balance for Payouts. SecurityView security details BasicAuth [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/request/header](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/request/header) Headers [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&in=header&path=finix-version](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/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). Default2022-02-01 Example:2022-02-01 [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&in=header&path=content-type](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/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 /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/request/body](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/request/body) Bodyapplication/jsonrequired [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=amount](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=amount) amount _integer_ _(int64)_ required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). Example:5000 [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=currency](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=currency) currency _string_ required ISO 4217 3 letter currency code. Value"USD" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=description](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=description) description _string_ required A description of the `Balance Adjustment`. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=instrument_id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=instrument_id) instrument\_id _string_ required The account, card, or bank account that is credited or debited as part of the adjustment. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=processor](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=processor) processor _string_ required The payment processing entity responsible for handling transactions, fund movements, etc., between different financial accounts. Value"DUMMY\_V1" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=rail](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=rail) rail _string_ required The method of adjustment. Value"ACH" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=tags](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=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 /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=top_up_config_id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=top_up_config_id) top\_up\_config\_id _string or null_ The ID of the top-up configuration that created the adjustment. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=type](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=request&path=type) type _string_ Specifies whether the `Balance Adjustment` increases or decreases the account balance. Acceptable values: - `TOP_UP` \- Adds funds to the balance (e.g., a deposit or manual funding). Value"TOP\_UP" post /balance\_adjustments - Sandbox server https://finix.sandbox-payments-api.com/balance\_adjustments cURL ``` curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/balance_adjustments \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 19, "currency": "USD", "description": "Sample balance adjustment", "instrument_id": "PI4Ppf8rxWYapuEqQr3u6efi", "processor": "DUMMY_V1", "rail": "ACH", "tags": { "name": "Sample balance adjustment" }, "type": "TOP_UP" }' ``` #### [link to /balance-adjustments/createbalanceadjustment\#balance-adjustments/createbalanceadjustment/response&c=201](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment\#balance-adjustments/createbalanceadjustment/response&c=201) Responses 1. 201 2. 400 3. 401 4. 403 5. 404 6. 406 7. 422 Expand all A single Balance Adjustment [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/response&c=201/headers](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/response&c=201/headers) Headers [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=date](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/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 /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=finix-apiuser-role](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/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 /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=x-request-id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/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 /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/response&c=201/body](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/response&c=201/body) Bodyapplication/json [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=id) id _string_ _non-empty_ The ID of the resource. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=created_at](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=created_at) created\_at _string_ _(date-time)_ Timestamp of when the object was created. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=updated_at](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=updated_at) updated\_at _string_ _(date-time)_ Timestamp of when the object was last updated. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=amount](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=amount) amount _integer_ _(int64)_ The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). Example:5000 [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=balance_entry_id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=balance_entry_id) balance\_entry\_id _string_ A ledger record that tracks individual financial movements within a `Balance Adjustment`. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=currency](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=currency) currency _string_ ISO 4217 3 letter currency code. Value"USD" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=description](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=description) description _string_ A description of the `Balance Adjustment`. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=failure_code](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=failure_code) failure\_code _string or null_ The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](https://docs.finix.com/guides/payouts/handling-payout-failures). [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=failure_message](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=failure_message) failure\_message _string or null_ [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=instrument_id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=instrument_id) instrument\_id _string_ The account, card, or bank account that is credited or debited as part of the adjustment. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=processor](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=processor) processor _string_ The payment processing entity responsible for handling transactions, fund movements, etc., between different financial accounts. Enum"DUMMY\_V1""FINIX\_V1" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=rail](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=rail) rail _string_ The method of adjustment. Value"ACH" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=state](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=state) state _string_ The status of the `Balance Adjustment`, indicating whether the adjustment was successful or failed. - `SUBMITTED` \- The balance adjustment has been initiated but is not yet confirmed. - `SUCCEEDED` \- The adjustment was successful, and the funds are available. This typically occurs 1-3 business days after `SUBMITTED`. - `FAILED` \- Finix was unable to process the adjustment, and the balance was not updated. - `RETURN` \- The adjustment was initially successful, but a subsequent return resulted in a reversal of the balance increase. Enum"FAILED""RETURNED""SUBMITTED""SUCCEEDED" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=trace_id](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=trace_id) trace\_id _string_ A unique identifier for tracking the `Balance Adjustment` across its lifecycle. [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=type](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=type) type _string_ Specifies whether the `Balance Adjustment` increases or decreases the account balance. Acceptable values: - `TOP_UP` \- Adds funds to the balance (e.g., a deposit or manual funding). Value"TOP\_UP" [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=tags](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=tags) tags _object or null_ Include up to 50 `key: value` pairs to annotate requests with custom metadata. +Show property [link to /balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=_links](https://docs.finix.com/api/balance-adjustments/createbalanceadjustment#balance-adjustments/createbalanceadjustment/t=response&c=201&path=_links)\_links _object_ An object containing link(s) relevant to the request. You can store these links for follow-up requests. +Show property Response 1. 201 2. 400 3. 401 4. 403 5. 404 6. 406 7. 422 application/json ``` { "id": "balance_adjustment_kkYD8Hen6Ri8bkPErceifY", "created_at": "2025-11-14T17:30:28.172363Z", "updated_at": "2025-11-14T17:30:28.545956Z", "amount": 19, "balance_entry_id": "balance_entry_kno3XJ9vbymJCw15eCdSpJ", "currency": "USD", "description": "Sample balance adjustment", "failure_code": null, "failure_message": null, "instrument_id": "PI4Ppf8rxWYapuEqQr3u6efi", "rail": "ACH", "state": "SUCCEEDED", "tags": { "name": "Sample balance adjustment" }, "top_up_config_id": null, "trace_id": "9ce69925-8dfa-431a-8c7f-f846d4d33340", "type": "TOP_UP", "_links": { "self": { … } } } ``` #### Was this helpful? ## [link to List Balance Adjustments](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments) List 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/listbalanceadjustments.md) - [Open in ChatGPT\\ \\ Get insights from ChatGPT](https://chat.openai.com/?q=Read+https%3A%2F%2Fdocs.finix.com%2Fapi%2Fbalance-adjustments%2Flistbalanceadjustments.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%2Flistbalanceadjustments.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 /balance-adjustments/listbalanceadjustments\#balance-adjustments/listbalanceadjustments/request](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments\#balance-adjustments/listbalanceadjustments/request) Request Retrieve a list of `Balance Adjustment` resources for an `Application`. Only `ROLE_PARTNER` or `ROLE_PLATFORM` credentials can be used to retrieve `Balance Adjustment` objects. SecurityView security details BasicAuth [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/request/query](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/request/query) Query [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=after_cursor](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=after_cursor) after\_cursor _string_ Return every resource created after the cursor value. [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=before_cursor](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=before_cursor) before\_cursor _string_ Return every resource created before the cursor value. [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=created_at.gte](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=created_at.lte](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=limit](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=limit) limit _integer_ _<= 100_ The numbers of items to return. Example:limit=10 [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=tags.key](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=tags.value](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=updated_at.gte](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=query&path=updated_at.lte](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/request/header](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/request/header) Headers [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=header&path=finix-version](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=request&in=header&path=finix-version) Finix-Version _string_ Default2022-02-01 Example:2022-02-01 get /balance\_adjustments - Sandbox server https://finix.sandbox-payments-api.com/balance\_adjustments curl ``` curl "https://finix.sandbox-payments-api.com/balance_adjustments" \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda ``` #### [link to /balance-adjustments/listbalanceadjustments\#balance-adjustments/listbalanceadjustments/response&c=200](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments\#balance-adjustments/listbalanceadjustments/response&c=200) Responses 1. 200 2. 401 3. 403 4. 406 5. 422 Expand all List of `Balance Adjustment` resources [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/response&c=200/headers](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/response&c=200/headers) Headers [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=date](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=finix-apiuser-role](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=x-request-id](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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 /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/response&c=200/body](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/response&c=200/body) Bodyapplication/json [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=page](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=page) page _object_ Details the page that's returned. +Show 2 properties [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=_embedded](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=_embedded)\_embedded _object_ +Show property [link to /balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/t=response&c=200&path=_links](https://docs.finix.com/api/balance-adjustments/listbalanceadjustments#balance-adjustments/listbalanceadjustments/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": { "balance_adjustments": [ … ] }, "_links": { "self": { … } }, "page": { "limit": 100, "next_cursor": "balance_adjustment_nvc873btpDtA7KbPySdCny" } } ``` #### Was this helpful? ## [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