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.json+api" \
    -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 envrioment 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 merchant 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 hanging request while on a checkout page and feared that 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. Now you can rest assured that when you create an Authorization or debit a bank account that the user will be protected from potential network issues by simply passing an idempotency_id in the body of the request.

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.

Identities

An Identity resource represents either a person or business in Finix. You'll create an Identity to onboard your merchants, and verify the different owners.

  • Identities can also represent buyers and are used to store their Payment Instruments.

  • Push to Card transactions also requires creating Identities for your users.

Related Guides: Getting Started, Onboarding, Push to Card

Create an Identity

Create an Identity for your merchant or buyer.

Creating Identities for merchants requires they provide KYC details.

Related Guides: Getting Started, Onboarding

SecurityBasicAuth
Request
Request Body schema: application/hal+json
object or null

Additional underwriting data that's required to verify the identity of the merchant.

object

Key value pair for annotating custom meta data (e.g. order numbers).

required
object

The underwriting details required to verify the Identity of the Merchant.

Responses
201

Single Identity object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/identities
Request samples
application/hal+json
{
  • "tags": {
    },
  • "entity": {
    }
}
Response samples
application/hal+json
{}

List Identities

Retrieves a list of Identities.

SecurityBasicAuth
Request
query Parameters
sort
string

Specify key to be used for sorting the collection

after_cursor
string

Return every resource created after the cursor value.

limit
integer

The numbers of items to return

Example: limit=10
id
string

Filter by id

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=created_at.gte=2019-06-15
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=created_at.lte=2019-06-15
default_statement_descriptor
string

Filter by the default_statement_descriptor

business_name
string

Filter by the full business name. Partial business names are not supported.

business_type
string

Filter by the business type. Partial business types are not supported

email
string

Filter by the email address or email domain. Partial emails are not supported.

Example: email=user@example.org
first_name
string

Filter by the first name of the person associated to the Identity.

Example: first_name=first_name=Daphne
last_name
string

Filter by the last name of the person associated to the identity.

Example: last_name=kline
title
string

Filter by the title if available.

Example: title=ceo
before_cursor
string

Return every resource created before the cursor value.

Responses
200

List of Identity objects

Response Schema: application/hal+json
object
object

List of Identity resources.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/identities
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://finix.sandbox-payments-api.com/identities?sort=string&after_cursor=string&limit=0&id=string&created_at.gte=created_at.gte%3D2019-06-15&created_at.lte=created_at.lte%3D2019-06-15&default_statement_descriptor=string&business_name=string&business_type=string&email=user%40example.org&first_name=first_name%3DDaphne&last_name=kline&title=ceo&before_cursor=string'
Response samples
application/hal+json
{}

Fetch an Identity

Retrieve the details of a previously created Identity.

SecurityBasicAuth
Request
path Parameters
identity_id
required
string

ID of the identity to fetch

Responses
200

Single Identity object

Response Schema: application/hal+json
id
string non-empty

The ID of the Identity resource.

application
string non-empty

ID of the Application associated with the Identity.

object

The underwriting details required to verify the Identity of the Merchant.

object

Key value pair for annotating custom meta data (e.g. order numbers).

created_at
string non-empty

Timestamp of when the Identity was created

updated_at
string non-empty

Timestamp of when the Identity was last updated.

object or null

Additional underwriting data that's required to verify the Identity of the Merchant.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/identities/{identity_id}
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://finix.sandbox-payments-api.com/identities/{identity_id}'
Response samples
application/hal+json
{}

Update an Identity

Update an existing Identity.

If you are updating the Identity of a Merchant that’s already been onboarded, you need to verify the merchant again.

SecurityBasicAuth
Request
path Parameters
identity_id
required
string

ID of the identity to fetch

Request Body schema: application/hal+json
object

Additional underwriting data that's required to verify the identity of the merchant.

object

Key value pair for annotating custom meta data (e.g. order numbers).

object

Underwriting data that's required to verify the identity of the merchant.

Responses
200

Single Identity object

Response Schema: application/hal+json
id
string non-empty

The ID of the Identity resource.

application
string non-empty

ID of the Application associated with the Identity.

object

The underwriting details required to verify the Identity of the Merchant.

object

Key value pair for annotating custom meta data (e.g. order numbers).

created_at
string non-empty

Timestamp of when the Identity was created

updated_at
string non-empty

Timestamp of when the Identity was last updated.

object or null

Additional underwriting data that's required to verify the Identity of the Merchant.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/identities/{identity_id}
Request samples
application/hal+json
{
  • "entity": {
    }
}
Response samples
application/hal+json
{}

Create an Associated Identity

Create an associated Identity for every owner with 25% or more ownership over the merchant.

SecurityBasicAuth
Request
path Parameters
identity_id
required
string

ID of Identity to associate object with.

Request Body schema: application/hal+json
object or null

Additional underwriting data that's required to verify the identity of the merchant.

object

Key value pair for annotating custom meta data (e.g. order numbers).

required
object

The underwriting details required to verify the Identity of the Merchant.

Responses
201

Single Identity object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/identities/{identity_id}/associated_identities
Request samples
application/hal+json
{
  • "tags": {
    },
  • "entity": {
    }
}
Response samples
application/hal+json
{}

List Associated Identities

Retrieve a list of Associated Identities for an Identity.

SecurityBasicAuth
Request
path Parameters
identity_id
required
string

ID of Identity to associate object with.

query Parameters
limit
integer <int64>

The number of entries to return.

after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

Responses
200

List of Identity objects

Response Schema: application/hal+json
object
object

List of Identity resources.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/identities/{identity_id}/associated_identities
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://finix.sandbox-payments-api.com/identities/{identity_id}/associated_identities?limit=0&after_cursor=string&before_cursor=string'
Response samples
application/hal+json
{}

Verify an Identity

Verify an Identity.

SecurityBasicAuth
Request
path Parameters
identity_id
required
string

ID of identity to fetch

Request Body schema: application/hal+json
object

Key value pair for annotating custom meta data (e.g. order numbers).

identity
string

ID of the Identity resource associated with the Merchant.

instrument
string

The Payment Instrument that'll be used to settle the Merchant's funds.

merchant
string

The ID of the Merchant.

processor
string

Name of the Verification processor.

Responses
201

Single Verification object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/identities/{identity_id}/verifications
Request samples
application/hal+json
{
  • "merchant": "MUgWbPVvtKbzjKNNGKqdQYV7",
  • "instrument": "PI3tfx1Uw3SzHfqwPFGX9o1Y",
  • "processor": "DUMMY_V1",
  • "identity": "ID2CGJmjqyYaQAu6qyuvGeWK",
  • "tags": {
    }
}
Response samples
application/hal+json
{}

Create a Merchant

Create a Merchant to start the underwriting process for your merchant. Merchants must be created under an Identity.

A bank account must be associated with the previously created Identity before a Merchant can be succefully onboarded and verified.

Merchant resources can have three possible onboarding_states:

  1. PROVISIONING: The request is pending (the state may change after two minutes).

    • processing_enabled: False
    • settlement_enabled: False

  2. APPROVED: The Merchant has been approved and can begin processing payments.

    • processing_enabled: True
    • settlement_enabled: True

  3. REJECTED: The Merchant was rejected by the processor because of invalid information or it failed a regulatory and/or compliance check (e.g. KYC, OFAC, or MATCH). Make any changes that are needed, and try verifying the Merchant again.

    • processing_enabled: False
    • settlement_enabled: False

Provisioning a Merchant account is an asynchronous request. We recommend creating a Webhook to listen for the state change.

SecurityBasicAuth
Request
path Parameters
identity_id
required
string

ID of Identity to fetch.

Request Body schema: application/hal+json
object

Key value pair for annotating custom meta data (e.g. order numbers).

gateway
string

Name of the gateway that processes the Merchant's transaction.

Enum: "TRIPOS_CLOUD_V1" "TRIPOS_MOBILE_V1"
processor
string

Name of acquiring processor that settles the Merchant's transactions.

processor_specific_parameters
object

Additional information required by the processor being used.

Responses
201

Single Merchant object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Error

post/identities/{identity_id}/merchants
Request samples
application/hal+json
{
  • "tags": {
    },
  • "processor": "DUMMY_V1"
}
Response samples
application/hal+json
{}

List Merchants

Retrieve a list of Merchants.

SecurityBasicAuth
Request
query Parameters
id
string

Filter by id

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=created_at.gte=2019-06-15
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=created_at.lte=2019-06-15
sort
string

Specify key to be used for sorting the collection

after_cursor
string

Return every resource created after the cursor value.

limit
integer

The numbers of items to return

Example: limit=10
before_cursor
string

Return every resource created before the cursor value.

Responses
200

List of Merchants objects

Response Schema: application/hal+json
object
object

List of Merchant objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/merchants
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://finix.sandbox-payments-api.com/merchants?id=string&created_at.gte=created_at.gte%3D2019-06-15&created_at.lte=created_at.lte%3D2019-06-15&sort=string&after_cursor=string&limit=0&before_cursor=string'
Response samples
application/hal+json
{}

Get a Merchant

Retrieve the details of a Merchant.

SecurityBasicAuth
Request
path Parameters
merchant_id
required
string

ID of Merchant.

Responses
200

Single Merchant object

Response Schema: application/hal+json
id
string

The ID of the resource.

application
string

ID of the Application the Merchant was created under.

identity
string

The ID of the Identity resource associated with the Merchant.

verification
string

ID of the Verification that was submitted to verify the Merchant.

merchant_profile
string

Details if a merchant's info was submitted to third-party processors for provisioning.

processor
string

Name of the transaction processor.

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

creating_transfer_from_report_enabled
boolean

Set to true to automatically create Transfers once settlement reports get generated.

card_expiration_date_required
boolean

Set to true to require the card's expiration date.

card_cvv_required
boolean

Set to true to require the card's CVV code.

object

Key value pair for annotating custom meta data (e.g. order numbers).

mcc
string or null

The Merchant Category Code (MCC) that this merchant will be classified under.

mid
string or null

MID of the Merchant.

merchant_name
string

The legal name saved in the Merchant resource.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

level_two_level_three_data_enabled
boolean

Set to true to enable the Merchant for Level 2 and Level 3 processing. Default value is false.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

onboarding_state
string

Details the state of the Merchant's onboarding.

Enum: "PROVISIONING" "APPROVED" "REJECTED"
object

Additional details specific to the processor.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/merchants/{merchant_id}
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://finix.sandbox-payments-api.com/merchants/{merchant_id}'
Response samples
application/hal+json
{}

Update a Merchant

Update a Merchant to change the Identity information saved with the underlying processor, or enable Level 2/3 processing.

SecurityBasicAuth
Request
path Parameters
merchant_id
required
string

ID of Merchant.

Request Body schema: application/hal+json
object

Key value pair for annotating custom meta data (e.g. order numbers).

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

creating_transfer_from_report_enabled
boolean

Set to true to automatically create Transfers once settlement reports get generated.

card_expiration_date_required
boolean

Set to true to require the card's expiration date.

card_cvv_required
boolean

Set to true to require the card's CVV code.

merchant_name
string

The legal name saved in the Merchant resource.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

level_two_level_three_data_enabled
boolean

Set to true to enable the Merchant for Level 2 and Level 3 processing. Default value is false.

Responses
200

Single Merchant object

Response Schema: application/hal+json
id
string

The ID of the resource.

application
string

ID of the Application the Merchant was created under.

identity
string

The ID of the Identity resource associated with the Merchant.

verification
string

ID of the Verification that was submitted to verify the Merchant.

merchant_profile
string

Details if a merchant's info was submitted to third-party processors for provisioning.

processor
string

Name of the transaction processor.

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

creating_transfer_from_report_enabled
boolean

Set to true to automatically create Transfers once settlement reports get generated.

card_expiration_date_required
boolean

Set to true to require the card's expiration date.

card_cvv_required
boolean

Set to true to require the card's CVV code.

object

Key value pair for annotating custom meta data (e.g. order numbers).

mcc
string or null

The Merchant Category Code (MCC) that this merchant will be classified under.

mid
string or null

MID of the Merchant.

merchant_name
string

The legal name saved in the Merchant resource.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

level_two_level_three_data_enabled
boolean

Set to true to enable the Merchant for Level 2 and Level 3 processing. Default value is false.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

onboarding_state
string

Details the state of the Merchant's onboarding.

Enum: "PROVISIONING" "APPROVED" "REJECTED"