Finix API Reference
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 |
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 |
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. Response latency for card-present devices can also 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 checks against previous requests made on the same endpoint.
Every Finix resource (e.g., Authorizations, Transfers) can be listed and reviewed using GET requests. Every endpoint also 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.
curl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30eMany 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": {
"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
keysis 40. - Maximum character length for individual
valuesis 500.
Finix does not allow special characters on tags (e.g., \, ,, ", ')
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.
