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 "https://finix.sandbox-payments-api.com/" \
-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:
USsRhsHYZGBPnQw8CByJyEQW8a14c2f9-d94b-4c72-8f5c-a62908e5b30eAPgPDQrLD52TYvqazjHJJchMAn Application is a resource that represents your web app, like a web service that connects buyers (i.e. customers) and sellers (i.e. merchants).
| Environment | Endpoint URL |
|---|---|
| Sandbox | https://finix.sandbox-payments-api.com |
| Live | https://finix.live-payments-api.com |
Finix provides two environments with distinct base URLs to make API requests.
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.
HTTP Code |
Meaning |
|---|---|
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.
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}/reversalsPlease note, idempotency_id is only checked against previous requests made on the same endpoint.
{
...
"tags":{Query
"card-type":"business card",
"order_number":"H-1257",
"customer_order_reference":"order1234",
"item_type":"hardware",
"vendor":"finix"
}
}
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.
keys is 40.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:
AuthorizationsIdentitiesPayment InstrumentsTransferscurl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
-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.