Skip to content

Finix API Reference (2022-02-01)

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.

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.

ParameterValue
Sandbox UsernameUSsRhsHYZGBPnQw8CByJyEQW
Sandbox Password8a14c2f9-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.

EnvironmentEndpoint URL
Sandboxhttps://finix.sandbox-payments-api.com
Livehttps://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 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
400Bad RequestWe could not parse your request. Verify you are providing valid JSON.
401UnauthorizedWe could not authenticate your request. Verify your username and password are correct.
402Upstream Processor ErrorErrors caused by 3rd-party service(s).
403ForbiddenYour credentials do not have the correct permissions to perform the request.
404Not FoundWe could not find the specified resource.
405Method Not AllowedThe specified resource does not support the HTTP Method used to submit the request.
406Not AcceptableThe server could accept the submitted request. Confirm how the request was formatted and submitted.
409ConflictThe submitted request conflicts with the current state of the server.
422Unprocessable EntityThe 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).
500Internal Server ErrorWe 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:

  • /transfers
  • /authorizations
  • /transfers/{id}/reversals
`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

All 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.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.
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. You can fork it using the button below.

Run In Postman

Overview
URL

https://finix.com

Finix

support@finix.com

Languages
Servers
Sandbox server

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

Production server

https://finix.live-payments-api.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.

Related Guides: Auth and Captures, Level 2 and 3 Processing, POS Integration, Buyer Charges

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.

Related Guides: Managing PCI Compliance, PCI DSS Compliance

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, represent any customer-disputed charges. A core part of the dispute lifecycle is the ability for a Merchant to upload Dispute evidence that supports their side of the Dispute.

Related Guides: Managing Disputes

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. Payment transactions generate Fee resources.

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.

Related Guides:

Operations

Files

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

Related Guides: File Uploads, Update Requests

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.

Related Guides: Getting Started, Onboarding Sellers, Push to Card

Operations

Merchants

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

Related Guides: Getting Started, Onboarding Sellers

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.

Related Guides: Onboarding, Onboarding Forms.

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.

A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

Including an address when creating a Payment Instrument can lower interchange on credit card transactions.

Related Guides: Using Hosted Fields, Getting Started

Operations

Fetch a Payment Instrument

Request

Retrieve the details of an existing Payment Instrument.

Security
BasicAuth
Path
payment_instrument_idstringrequired

The Payment Instrument ID.

Example: PInVUXZLswZi6pdcK1T41MuE
Headers
Finix-Versionstring

Specify the API version of your request. For more details, see Versioning.

Default 2022-02-01
Example: 2022-02-01
curl -i -X GET \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments/PInVUXZLswZi6pdcK1T41MuE \
  -H 'Finix-Version: 2022-02-01'

Responses

A single Payment Instrument

Headers
datestring

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"
finix-apiuser-rolestring

This response header indicating the role of the user who sent the API request.

Enum"ROLE_ADMIN""ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
Example: "ROLE_PARTNER"
x-request-idstring

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"
Bodyapplication/json
One of:
idstringnon-empty

The ID of the resource.

created_atstring(date-time)

Timestamp of when the object was created.

updated_atstring(date-time)

Timestamp of when the object was last updated.

created_viastring

The method by which the resource was created.

Value"API"
account_updater_enabledboolean

When enabled at the Payment Instrument-level, Finix automatically checks for updates with card networks. This Account Updater functionality:

  • Automatically updates card details (e.g., number or expiration date) to maintain continuity of charges, increasing authorization rates.
  • Saves the cardholder the hassle of updating card details across Merchants for each of their Subscriptions.

If set at the Application level, this Payment Instrument-level setting will override the Application-level configuration. If not configured at the Application-level, the card defaults to false, requiring explicit opt-in.

Note: Cards created before the feature is enabled are unaffected by default. To include these cards, you can manually enable the Account Updater functionality for each card individually using a PUT request. Once enabled, you can link the card to this API call to trigger updates with card networks.

Default false
addressobject

The address of the card owner. Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

address_verificationstring
  • Details the results of verifying address with the issuing bank.
  • Set to UNKNOWN when address gets updated.
Enum"POSTAL_CODE_AND_STREET_MATCH""STREET_MATCH""POSTAL_CODE_MATCH""NO_ADDRESS""NO_MATCH""NOT_SUPPORTED""UNKNOWN"
applicationstringnon-empty

ID of the Application the resource was created under.

binstring

Bank Identification number for the Payment Instrument.

brandstring

The brand of the card saved in the Payment Instrument.

Enum"UNKNOWN""DINERS_CLUB_INTERNATIONAL""DANKORT""MIR""TROY""UATP""CHINA_T_UNION""CHINA_UNION_PAY""AMERICAN_EXPRESS""VERVE"
card_typestring

The type of payment card saved in the Payment Instrument.

Enum"CREDIT""DEBIT""HSA_FSA""NON_RELOADABLE_PREPAID""RELOADABLE_PREPAID""UNKNOWN"
countrystring or null
Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"
currencystring

ISO 4217 3-letter currency code.

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
disabled_codestring or null
disabled_messagestring or null
enabledboolean

Indicates whether the Payment Instrument resource is enabled. The default value is true; set it to false to disable the Payment Instrument.

expiration_monthinteger[ 1 .. 12 ]

Expiration month (e.g. 12 for December).

expiration_yearinteger>= 1

4-digit expiration year.

fast_funds_indicatorstring

Details if Fast Funds is enabled for the card.

fingerprintstring

Unique ID that represents the tokenized card data.

Example: "FPRxxxxxxxxxxxxxxxxx"
identitystring

The ID of the Identity used to create the resource.

instrument_typestring

The type of Payment Instrument.

Enum"PAYMENT_CARD""TOKEN"
issuer_countrystring

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

  • NON_USA - The card was issued outside of the United States.
  • UNKNOWN - The processor did not return an issuer country for this particular BIN.
Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"
last_fourstring

Last four digits of the card.

namestring or null

The name of the card owner.

network_token_enabledboolean

When enabled at the Payment Instrument level, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

  • The token offers increased authorization rates, even for lost or stolen cards, as it remains valid while the physical card is replaced.
  • Visa reduces interchange fees when using network tokens.
  • Tokens enhance security by replacing card details with a non-sensitive string that is usable only within the Finix system.

If set at the Application level, this Payment Instrument level setting will override the application level configuration. If not configured at the application level, the card defaults to false, requiring explicit opt-in.

Note: Cards created before the feature is enabled are unaffected. To include them, update an individual Payment Instrument. Then, you can insert the hyperlink on the "update".

Default false
network_token_statestring

The state of the network token. The possible enum values are as follows:

  • NOT_ENABLED: The network_token_state is NOT_ENABLED when the value of network_token_enabled on the Payment Instrument is false.
  • PENDING: Immediately after Finix enables network tokens for a specific card, network_token_state is initially set to PENDING.
  • ACTIVE: After Finix receives the network token successfully from the card network, network_token_state updates to ACTIVE.
  • FAILED: In the event that there is an issue with the card network such as service becomes unavailable, FAILED is returned.
  • SUSPENDED: When the issuing bank does not allow the network token to be used in transactions, SUSPENDED is returned.
  • CLOSED: In the event that the issuing bank has closed the card permanently, CLOSED is returned.
Enum"ACTIVE""CLOSED""FAILED""NOT_ENABLED""SUSPENDED""PENDING"
online_gambling_block_indicatorstring

Details if the card is enabled to receive push-payments for online gambling payouts.

payload_typestring
Enum"SOURCE""DESTINATION"
push_funds_block_indicatorstring

Details if the card is enabled to receive push-to-card disbursements.

security_code_verificationstring

Details the results of the Card Verification Code check.

Enum"MATCHED""UNKNOWN""UNMATCHED"
third-partystring or null

This field is not applicable to payment cards.

third_party_tokenstring or null

This field is not applicable to payment cards.

typestring

Type of Payment Instrument.

Enum"PAYMENT_CARD""TOKEN""GOOGLE_PAY""APPLE_PAY"
tagsobject or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
_linksobject

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.

Response
application/json
{
  "id": "PI6F5kkcCB3dtGhFy1t8Aua5",
  "created_at": "2024-11-15T09:42:33.42Z",
  "updated_at": "2024-11-15T09:42:33.42Z",
  "account_updater_enabled": false,
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "instrument_type": "PAYMENT_CARD",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "UNKNOWN",
  "bin": "520082",
  "brand": "MASTERCARD",
  "card_type": "DEBIT",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "NON_USA",
  "last_four": "8210",
  "name": "John Smith",
  "network_token_enabled": false,
  "network_token_state": "NOT_ENABLED",
  "security_code_verification": "UNKNOWN",
  "tags": {},
  "third_party": null,
  "third_party_token": null,
  "type": "PAYMENT_CARD",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … },
    "updates": { … }
  }
}

Update a Payment Instrument

Request

Update a Payment Instrument to:

  • Change the billing address in case the account holder moved (instrument_type:PAYMENT_CARD only).
  • Disable the Payment Instrument resource so it can't be used in requests.
  • Update the name on the Payment Instrument.
  • Change the tags.
  • Enable or disable Account Updater.
  • Enable or disable Network Tokens.
Security
BasicAuth
Path
payment_instrument_idstringrequired

The Payment Instrument ID.

Example: PInVUXZLswZi6pdcK1T41MuE
Bodyapplication/jsonrequired
One of:
attempt_bank_account_validation_checkbooleanrequired

Verify and validate the Payment Instrument to confirm it can be used for ACH Direct Debits.

  • Set to True to verify the Payment Instrument can be used for ACH payments.
  • Only Payment Instruments created from bank accounts can be used for ACH payments.
Default false
tagsobject or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments/PInVUXZLswZi6pdcK1T41MuE \
  -H 'Content-Type: application/json' \
  -d '{
    "attempt_bank_account_validation_check": "true"
  }'

Responses

A single Payment Instrument

Headers
datestring

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"
finix-apiuser-rolestring

This response header indicating the role of the user who sent the API request.

Enum"ROLE_ADMIN""ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
Example: "ROLE_PARTNER"
x-request-idstring

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"
Bodyapplication/json
One of:
idstringnon-empty

The ID of the resource.

created_atstring(date-time)

Timestamp of when the object was created.

updated_atstring(date-time)

Timestamp of when the object was last updated.

created_viastring

The method by which the resource was created.

Value"API"
addressobject

The address of the bank account owner.

account_typestring

The bank account type.

Enum"CHECKING""SAVINGS"
applicationstringnon-empty

ID of the Application the resource was created under.

bank_account_validation_checkstring

Possible values returned when attempt_bank_account_validation_check is true or the Payment Instrument is used for a Transfer:

  • INCONCLUSIVE: A verification check was conducted, but the bank account could not be found or verified with the issuing bank. Please contact the buyer to confirm the details collected or request an alternate method of payment.

  • INVALID: The Payment Instrument was involved in transactions that returned one or more of the following ACH errors:

    • Account Does Not Allow ACH Transactions
    • Account is Closed
    • Account Funds are Frozen
    • Deceased Account Holder
    • Invalid Account Number
    • Invalid Routing Number
    • No Account on File

    For further details about the different ACH failure codes, please refer to ACH Direct Debit documentation.

  • NOT_ATTEMPTED: A verification check was not performed, and the Payment Instrument has not been used to create a Transfer or Authorization.

  • VALID: The bank account was successfully verified. The Payment Instrument is eligible for use in creating ACH Direct Debits.

Default "NOT_ATTEMPTED"
Enum"INCONCLUSIVE""INVALID""NOT_ATTEMPTED""VALID"
bank_codestring

The routing number of the bank account.

countrystring or null
Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"
currencystring

ISO 4217 3-letter currency code.

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
disabled_codestring or null
disabled_messagestring or null
enabledboolean

Indicates whether the Payment Instrument resource is enabled. The default value is true; set it to false to disable the Payment Instrument.

identitystring

The ID of the Identity used to create the resource.

institution_numberstring or null= 3 characters

Canadian bank identifier (EFT). Exactly 3 digits that identify the financial institution (e.g., 004 = TD, 002 = Scotiabank). Stored as a string to preserve leading zeros.

Example: "004"
instrument_typestring

The type of Payment Instrument.

Value"BANK_ACCOUNT"
masked_account_numberstring or null

The last 4 digits of the account number used to create the Payment Instrument.

namestring or null

The name of the bank account.

third-partystring or null

This field is not applicable to bank accounts.

third_party_tokenstring or null

This field is not applicanle to bank accounts.

transit_numberstring or null= 5 characters

Canadian branch/branch-transit identifier (EFT). Exactly 5 digits that identify the branch where the account is held. Stored as a string to preserve leading zeros.

Example: "12345"
typestring

Type of Payment Instrument.

Value"BANK_ACCOUNT"
tagsobject or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
_linksobject

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.

Response
application/json
{
  "id": "PIpU66orYpdrPSs91fqRJd66",
  "created_at": "2023-03-13T23:28:34.10Z",
  "updated_at": "2023-03-13T23:28:34.10Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
  "identity": "IDpYDM7J9n57q849o9E9yNrG",
  "instrument_type": "BANK_ACCOUNT",
  "account_type": "SAVINGS",
  "bank_account_validation_check": "VALID",
  "bank_code": "123123123",
  "country": "USA",
  "masked_account_number": "XXXXX3123",
  "name": null,
  "tags": {},
  "type": "BANK_ACCOUNT",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … }
  }
}

List Instrument History Entries

Request

Whenever a stored payment card's details are updated, an Instrument History Entry is created. Use this endpoint to retrieve a list of Instrument History Entries for a specific Payment Instrument.

Security
BasicAuth
Path
payment_instrument_idstringrequired

The Payment Instrument that triggered the creation of this Instrument History Entry.

Example: PInVUXZLswZi6pdcK1T41MuE
Query
after_cursorstring

Return every resource created after the cursor value.

before_cursorstring

Return every resource created before the cursor value.

limitinteger

The numbers of items to return.

Example: limit=10
Headers
Finix-Versionstring

Specify the API version of your request. For more details, see Versioning.

Default 2022-02-01
Example: 2022-02-01
curl -i -X GET \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  'https://finix.sandbox-payments-api.com/payment_instruments/PInVUXZLswZi6pdcK1T41MuE/instrument_history' \
  -H 'Finix-Version: 2022-02-01'

Responses

List of Instrument History Entry objects.

Headers
datestring

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"
finix-apiuser-rolestring

This response header indicating the role of the user who sent the API request.

Enum"ROLE_ADMIN""ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
Example: "ROLE_PARTNER"
x-request-idstring

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"
Bodyapplication/json
pageobject

Details the page that's returned.

_embeddedobject
_linksobject
Response
application/json
{
  "_embedded": {
    "instrument_history_entries": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … }
  },
  "page": {
    "limit": 10,
    "next_cursor": "instrument_history_nAzun1LYhSAJ6rvLeyVAfj"
  }
}

Settlements

A Settlement is a logical construct representing a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent Transfers or Split Transfers

Related Guides: Payouts

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.

If a merchant's settlement_queue_mode is set to MANUAL, all transfers will have a Settlement Queue Entry created and will not be placed into settlement until the Settlement Queue Entry is explicitly released using a PUT Update Settlement Queue Entries request.

Related Guides: Account Structures and Settlements

Operations

Split Transfers

Transfers can be split among several different Merchants. A split_transfer represents how the funds from a split Transfer were distributed into a Merchants Settlement.

Related Guides: Online Payments Quickstart, Split a Transaction

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.

Related Guides: Online Payments Quickstart, Level 2 and 3 Processing, POS Integration, Buyer Charges, ACH (eCheck) Direct Debit

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).

The password field for a User resource is only returned during the initial creation. Any following GET requests to the resource returns the password field as null for security purposes.

Related Guides: Account Structure

Operations

Webhooks

Webhooks lets you build or set up integrations which subscribe to certain automated notifications (i.e. events) on the Finix API. When one of those events is triggered, a HTTP POST payload is sent to the webhook's configured URL.

Related Guides: Webhooks

Operations

Checkout Forms

Checkout Forms are a low-code solution that enables you to create a customizable payment page where buyers can easily enter their payment details and submit a payment on both desktop and mobile devices.

With Checkout Forms, you can quickly create checkout pages and accept payments from buyers with minimal development work.

Related Guides: Checkout Pages

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.

Related Guides: Receipts for Online Payments

Operations

Subscriptions

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

When creating a Subscription, you have the option to use a Subscription Plan.

Limitations:
- Supported countries: At this time, subscriptions are available in the United States.
- Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments (ACH in the USA).
- Approved merchants: At this time, only approved merchants with one of the following processors can create subscriptions: DUMMY_V1 and FINIX_V1.

Related Guides: Creating Subscriptions, Creating Subscription Plans, Recurring Payments Guidelines

Operations

Subscription Plans

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

Related Guides: Creating Subscriptions Plans, Creating Subscriptions, Recurring Payments Guidelines

Operations

Transfer Attempts

A transfer_attempt is created when a buyer attempts to pay for a payment using a Payment Link or Checkout Form. Using Transfer Attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link.

Each transfer_attempt has as reference to a transfer_id to allow you to query it for additional data.

Operations

Balances

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

It tracks the state of funds processed through the system, including amounts that are:

  • available_amount for immediate use or disbursement.
  • pending_amount due to processing times, holds, or other constraints.
  • posted_amount, which reflects the total sum (including both available and pending funds).
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.

Rules establish limits on transactions. For example, there may be a daily transaction limit of 100 transactions (count_limit) or a monthly volume limit of $100,000 (volume_limit). If a transaction exceeds any defined limit, the transaction is rejected.

Rules are set for entities involved in transactions, including the application, senders, and recipients.

The "Application" represents the customer to whom Finix is applying the rules. Application rules are set solely by Finix and are applied to every single transaction.

You can establish rules for "senders" and "recipients," referring to the parties involved in transactions:

  • In the case of a PULL_FROM_CARD or PULL_FROM_ACH transaction, sender rules are applied (either card or ACH rules). The "target" of the pull is referred to as the "sender," specifically the customer of Finix's client.
  • Conversely, in the case of a PUSH_FROM_CARD or PUSH_FROM_ACH transaction, the recipient rules are applied (either card or ACH rules). The "target" of the push is referred to as the "recipient," which is, in turn, the customer of Finix's client.
Operations

Application Profiles

The application_profile resource is used to configure the Application's Fee Profile. The Application's Fee Profile configures what Fee gets applied to transactions processed by the application_profile.

Related Guides:

Operations

Applications

The Application resource represents your app. For example, an iOS app, website, online marketplace, SaaS platform, etc. – any web service that connects buyers (i.e. customers) and sellers (i.e. merchants). In other words, an Application is a resource that represents the program you're integrating with Finix and using to connect with customers (i.e. buyers).

Related Guides: Getting Started

Operations

Balance Transfers

Our Balance Transfers API provides platforms the option to create a money movement between their FBO (For the Benefit Of) Settlement account and their operating account. This is only available for Finix Core customers with Litle V12 credentials.

If you have any questions, please reach out to your Finix point of contact or contact the Finix Support team.

Operations

Merchant Profiles

A merchant_profile links a merchant to it's risk_profile and fee_profile. Each merchant has a merchant_profile.

When a merchant gets created, a merchant_profile also gets created. This new merchant_profile automatically receives a new risk_profile and fee_profile that are copies of the risk and fee profiles on the application_profile.

Related Guides:

Operations

Payout Profiles

A Payout Profile configures how fees and payouts get calculated and processed.

Related Guides: Configuring Payouts

Operations

Review Queue Items

Funds are released to sub-merchants when a Settlement's corresponding Review Queue Item is marked as ACCEPTED by a user with the appropriate role permissions.

Related Guides: Roles & Permissions

Operations

Verifications

Verifications are used to verify Identities and Payment Instruments.

For Identities, a verification represents an attempt to onboard and underwrite an identity.

For Payment Instruments, a verification represents getting additional information from the card brands to verify a card is eligible for push to card.

Related Guides: Onboarding with the API, Push to Card

Operations