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/vnd.api+json" \
-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).
| Sandbox URL |
|---|
https://finix.sandbox-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. |
We use HTTP errors to communicate overall success and include error messages on non 200 responses. You can also test for specific error responses.
You'll notice the Authorization and Transfer objects have a field named idempotency_id which ensures 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.
With Finix, we remove this ambiguity by having the user generate a unique idempotency_id and sending it with the normal payload. If the user 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.
{
...
"tags":{
"card-type":"business card",
"customer_order_reference":"order1234"
}
}
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 such, as card-type: business card. Other examples can include: order number: 25, item_type: produce, department: sales, etc.
Use the tags.key and tags.value filters to sort through lists for resources with specific tags.
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.