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.

Authentication

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:

  • 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

Sandbox URL
https://finix.sandbox-payments-api.com

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.

Errors

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.

Idempotency Requests

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

{
  ...
  "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 an unlimited number of tags. The information in the tags can also be updated as many times as needed.

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.

Versioning

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.