Finix API Reference

Finix API Reference

The Finix API is resource oriented, relying heavily on common REST principles. Our API uses JSON encoded requests and responses.

Authentication

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

Request Format

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

Environments

Finix provides two environments with distinct base URLs to make API requests.

  1. A Sandbox environment for developing and testing your integration.
  2. 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

Live Access To get access to the Live environment, please reach out to your Finix point-of-contact.

HTTP Codes and Errors

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. Additionally, response latency for card-present devices can be higher depending on how quickly buyers complete the transaction on payment terminals.

Due to 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.

Idempotent Requests

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:

idempotency_id scope

idempotency_id checks against previous requests made on the same endpoint.

Query Parameters

Every Finix resource (e.g., Authorizations, Transfers) can be listed and reviewed using GET requests. Additionally, every endpoint 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.

Query Parameter Example

curl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Tags

Many 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 Example

{
   ...,
   "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.

Special Characters Finix does not allow special characters on tags (e.g., \, ,, ", ')

Versioning

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.

Postman Collection

Finix has a Postman collection to help in your development.

Overview

URL https://finix.com

Authorizations

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within seven days. When an Authorization is captured it produces a Transfer resource.

Operations

Compliance Forms

To process payments, your Merchants must validate their compliance with PCI DSS requirements annually. To do this, your Merchants must attest to PCI Self-Assessment Questionnaire (SAQ) compliance forms.

Operations

Devices

A Device resource represents a Point-of-Sale terminal. Devices are used for In-Person transactions.

Operations

Disputes

Disputes, also known as chargebacks, are customer-disputed charges. A core part of the dispute lifecycle is the ability for a Merchant to upload evidence supporting their side.

Operations

Fees

A Fee is a charge levied against a Merchant. It represents how a platform charges its sellers for all various types of Fees.

Operations

Fee Profiles

A fee_profiles represents a pricing scheme that automatically applies fees to each transaction. Changes to fee_profiles go into effect immediately.

Operations

Files

Use Finix's File API to upload and manage files for your merchants.

Operations

Identities

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

Operations

Merchants

A Merchant resource represents the entity's merchant account on a processor. Your Merchant must be APPROVED to process payments.

Operations

Onboarding Forms

Finix offers and hosts pre-built onboarding forms that you can use to collect onboarding and identity verification information from your users.

Operations

Payment Instruments

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.

Operations

Payment Instrument Associations

In Finix, Payment Instruments are tied to the owner of that account. For example, Payment Instruments tied to buyers will be the cards used for purchases while Payment Instruments tied to a Merchant are the bank accounts where they receive settlements.

Operations

Settlements

A Settlement represents a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent a Transfer, custom Fee, or Split Transfer.

Operations

Settlement Queue Entries

A Settlement Queue Entry resource represents an entry in the settlement queue used to track when and how a transfer is queued to be processed.

Operations

Split Transfers

Transactions can be split among different merchants. A Split Transfer shows how funds from a split Transfer were distributed into a merchant's Settlement.

Operations

Transfers

A Transfer represents any flow of funds either to or from a Payment Instrument. All payments in Finix are represented by a Transfer.

Operations

Users

A User resource represents a pair of API keys which are used to perform authenticated requests against the Finix API. When making authenticated requests via HTTP basic access authentication the ID of a User resource maps to the username, while the password corresponds to the password (i.e. secret key).

Operations

Verifications

Verifications are used to verify Merchants and Payment Instruments.

Operations

Webhooks

Webhooks let you set up integrations that subscribe to automated notifications (events) on the Finix API. When an enabled event occurs, Finix sends an HTTP POST payload to the Webhook's configured URL.

Operations

Gateway Integrations

A Gateway Integration represents a connection to a third-party payment gateway. At this time, the only supported gateway is Cybersource.

Operations

Receipts

The Receipt resource generates a receipt for Transfers or Authorizations. You can then send the Receipt via Email, SMS, or use the information from the Receipt to send it yourself.

Operations

Subscriptions

A Subscription resource represents a recurring charge to a Payment Instrument at regular intervals. Subscribers can be buyers, customers, or merchants.

Operations

Subscription Plans

A Subscription Plan resource is a template with set recurring costs and frequencies that can be reused across multiple Subscription resources.

Operations

Transfer Attempts

When a user attempts to make a payment using a Checkout Form or Payment Link, or a recipient submitting details with a Payout Link—a Transfer Attempt is created.

Operations

Balances

A Balance resource represents the current financial state of an Application identified by the linked_to query parameter.

Operations

Balance Adjustments

A Balance Adjustment modifies the account Balance by adding funds (a 'top-up') or reducing funds for Payouts. Each adjustment is linked to a specific payment rail (e.g., ACH, card, wire).

Operations

Disbursement Rules

For the Payouts product, when a payout is executed, such as a Push-To-Card or ACH transaction, Finix checks the transaction against velocity rules and balance rules.

Operations