Finix API Reference

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

You'll get separate accounts for sandbox and production as well as corresponding API credentials to access the Finix API.


With CURL, just include your credentials as basic auth (-u) in the header of each request as follows:

curl "" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

To communicate with the Finix API, you need to authenticate your requests via HTTP basic access authentication with a username and password, which you can find in your Finix Dashboard. If you don't have a Dashboard, you can test our APIs with the following credentials:

  • Username: USsRhsHYZGBPnQw8CByJyEQW
  • Password: 8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
  • Application ID: APgPDQrLD52TYvqazjHJJchM

An Application is a resource that represents your web app, like a web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

Sandbox and Live Endpoints

Environment Endpoint URL

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

  • A sandbox environment for testing.
  • A live environment where payments are processed.

Both environments are entirely separate and do not share information like API credentials.

With these environments, you can test your connection with Finix's APIs. For testing purposes, use the Finix Sandbox API. Reach out to your Finix point of contact for the live environment URL.


400 Bad Request -- You provided a request that can't be successfully parsed. Verify you are providing valid JSON
401 Unauthorized -- We could not authenticate your request. You used an incorrect API Key
402 Upstream Processor Error -- Errors caused by 3rd party service
403 Forbidden -- Your credentials don't have the right permissions to submit the request
404 Not Found -- The specified resource could not be found
405 Method not allowed -- The HTTP request method used to submit the request is not supported by the specified resource
406 Not Acceptable -- The server can't accept the submitted request. Double-check 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. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a seller that has not yet been approved)
500 Internal Server Error -- We had a problem with our server. Try again later.

Finix uses HTTP errors to communicate overall success and include error messages on non 200 responses. Requests to Finix's API return a response within less than a second.

However, communications between card networks and processors can increase the time it takes to return a response. Additionally, response times for card-present devices can take longer depending on how quickly buyers complete the transaction on the payment terminal.

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

Idempotency Requests

You'll notice the Authorization and Transfer objects have a field named idempotency_id. This field helps you ensure the API request is only performed once.

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

Finix removes this ambiguity with the idempotency_id field. 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 rest assured that when you create an Authorization or debit a bank account the user will be protected from potential network issues.

idempotency_id is available on the following three endpoints:

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

Please note, idempotency_id is only checked against previous requests made on the same endpoint.


    "card-type":"business card",

All Finix resources (i.e. Authorization, Application, Identity, Merchant, Payment Instrument, Settlement, Transfer, etc.) include a tags attribute that allows you to include key-value metadata with resources. A resource's tags object, can have 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.

The information in the tags can also be updated as many times as needed (tags must exclude special characters).

For example, when creating a Payment Instrument, you can include additional data about the card by passing a custom key and value. See the example on the right for several instances of how you can use tags.

Use the tags.key and tags.value filters to sort through lists for resources with specific tags. Resources that can be filtered with tags include:

  • Authorizations
  • Identities
  • Payment Instruments
  • Transfers

Query Parameters

curl "" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Every resource created under every Finix endpoint (i.e. Authorizations, Applications, Identities, Merchants, Payment Instruments, Settlements, Transfers, etc.) can be listed and reviewed using a GET request.

Additionally, every endpoint has query parameters available to help you filter through the resources that are returned. See the following for an example of how to query the Transfers endpoint using the DEBIT parameter.


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

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