Finix API

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.

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.

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

/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

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.

Overview

URL https://finix.com

Finix support@finixpayments.com

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: Collecting Fees

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

Fetch an Identity

Request

Retrieve the details of a previously created Identity.

Path

identity_idstringrequired

ID of the Identity to fetch.

Example: IDrH4G2VTfNjn1VFkvhcyMYj

curl "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" \
    -H "Finix-Version: 2022-02-01" \
    -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

Responses

Response schema and example when fetching a Payment Instrument.

Bodyapplication/json

Any of:

idstringnon-empty

The ID of the Identity resource.

created_atstring(date-time)(CreatedAt)

Timestamp of when the object was created.

updated_atstring(date-time)(UpdatedAt)

Timestamp of when the object was last updated.

additional_underwriting_dataobject or null

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

applicationstringnon-empty

ID of the Application associated with the Identity.

entityobject

The underwriting details required to verify the Identity.

identity_rolesArray of strings(identity_roles)

The sets of permissions available to the Identity.

Items Enum"APPLICATION_OWNER""BENEFICIAL_OWNER""BUYER""PLATFORM_OWNER""RECIPIENT""SELLER""SENDER"

typestring

The identity type.

Value"BUSINESS"

tagsobject or null(tags)

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": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "created_at": "2022-01-27T07:36:59.91Z",
  "updated_at": "2022-01-27T07:36:59.83Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "entity": {
    "ach_max_transaction_amount": 0,
    "amex_mid": null,
    "annual_card_volume": 0,
    "business_address": null,
    "business_name": null,
    "business_phone": null,
    "business_tax_id_provided": false,
    "business_type": null,
    "default_statement_descriptor": null,
    "discover_mid": null,
    "dob": null,
    "doing_business_as": null,
    "email": "therock@gmail.com",
    "first_name": "Collen",
    "has_accepted_credit_cards_previously": false,
    "incorporation_date": null,
    "last_name": "Wade",
    "max_transaction_amount": 0,
    "mcc": null,
    "ownership_type": null,
    "personal_address": { … },
    "phone": "7145677613",
    "principal_percentage_ownership": null,
    "short_business_name": null,
    "tax_authority": null,
    "tax_id_provided": false,
    "title": null,
    "url": null
  },
  "identity_roles": [
    "BUYER"
  ],
  "tags": {
    "key": "value"
  },
  "type": "PERSONAL",
  "_links": {
    "self": { … },
    "verifications": { … },
    "merchants": { … },
    "settlements": { … },
    "authorizations": { … },
    "transfers": { … },
    "payment_instruments": { … },
    "associated_identities": { … },
    "disputes": { … },
    "application": { … }
  }
}

Update an Identity

Request

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.

Path

identity_idstringrequired

ID of the Identity to fetch.

Example: IDrH4G2VTfNjn1VFkvhcyMYj

Bodyapplication/json

Any of:

additional_underwriting_dataobject

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

entityobject

Underwriting data that's required to verify the Identity.

tagsobject or null(tags)

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 "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
    -X PUT \
    -d '{
        "entity": {
            "email": "user@example.org",
            "first_name": "John",
            "last_name": "Smith",
            "phone": "7145677613"
        }
    }'

Responses

Response schema and example when fetching a Payment Instrument.

Bodyapplication/json

Any of:

idstringnon-empty

The ID of the Identity resource.

created_atstring(date-time)(CreatedAt)

Timestamp of when the object was created.

updated_atstring(date-time)(UpdatedAt)

Timestamp of when the object was last updated.

additional_underwriting_dataobject or null

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

applicationstringnon-empty

ID of the Application associated with the Identity.

entityobject

The underwriting details required to verify the Identity.

identity_rolesArray of strings(identity_roles)

The sets of permissions available to the Identity.

Items Enum"APPLICATION_OWNER""BENEFICIAL_OWNER""BUYER""PLATFORM_OWNER""RECIPIENT""SELLER""SENDER"

typestring

The identity type.

Value"BUSINESS"

tagsobject or null(tags)

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": "IDrH4G2VTfNjn1VFkvhcyMYj",
  "created_at": "2022-08-17T20:27:43.48Z",
  "updated_at": "2024-08-08T10:37:19.30Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "entity": {
    "ach_max_transaction_amount": 9000000,
    "amex_mid": null,
    "annual_card_volume": 0,
    "business_address": { … },
    "business_name": null,
    "business_phone": "1234567890",
    "business_tax_id_provided": false,
    "business_type": null,
    "default_statement_descriptor": "Finixs Flowers",
    "discover_mid": null,
    "dob": null,
    "doing_business_as": null,
    "email": "user@example.org",
    "first_name": "John",
    "has_accepted_credit_cards_previously": false,
    "incorporation_date": null,
    "last_name": "Smith",
    "max_transaction_amount": 22222222222,
    "mcc": null,
    "ownership_type": null,
    "personal_address": { … },
    "phone": "7145677613",
    "principal_percentage_ownership": null,
    "short_business_name": null,
    "tax_authority": null,
    "tax_id_provided": false,
    "title": null,
    "url": null
  },
  "identity_roles": [
    "BUYER"
  ],
  "tags": {},
  "type": "PERSONAL",
  "_links": {
    "self": { … },
    "verifications": { … },
    "merchants": { … },
    "settlements": { … },
    "authorizations": { … },
    "transfers": { … },
    "payment_instruments": { … },
    "associated_identities": { … },
    "disputes": { … },
    "application": { … }
  }
}

Create an Associated Identity

Request

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

Path

identity_idstringrequired

ID of Identity to associate object with.

Example: IDrH4G2VTfNjn1VFkvhcyMYj

Bodyapplication/json

Any of:

additional_underwriting_dataobject or nullrequired

Additional underwriting details required to verify Identities.
Required for any Merchants onboarded by Finix Flex customers. If you have any questions, please contact Finix Support.

additional_underwriting_data.annual_ach_volumeinteger

The approximate annual ACH sales expected to be processed (in cents) by this merchant (max 10 characters).

additional_underwriting_data.average_ach_transfer_amountinteger

The approximate average ACH sale amount (in cents) for this merchant.

additional_underwriting_data.average_card_transfer_amountinteger

The average credit card sale amount (in cents) for this merchant.

additional_underwriting_data.business_descriptionstring

Description of this merchant's business (max 200 characters).

additional_underwriting_data.card_volume_distributionobject

The distribution of the merchant's credit card volume The sum of card_volume_distribution must be 100.

additional_underwriting_data.credit_check_allowedboolean

Sets if this merchant has consented and accepted to a credit check.

additional_underwriting_data.credit_check_ip_addressstringnon-empty

The IP address of the merchant when they consented to a credit check (e.g., 42.1.1.113 ).

additional_underwriting_data.credit_check_timestampstringnon-empty

A timestamp of when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z).

additional_underwriting_data.credit_check_user_agentstringnon-empty

The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).

additional_underwriting_data.merchant_agreement_acceptedboolean

Sets whether this merchant has accepted the terms and conditions of the merchant agreement.

additional_underwriting_data.merchant_agreement_ip_addressstringnon-empty

IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).

additional_underwriting_data.merchant_agreement_timestampstringnon-empty

Sets if this merchant has consented and accepted to a credit check.

additional_underwriting_data.merchant_agreement_user_agentstringnon-empty

The details of the browser that was used when this merchant accepted Finix's Terms of Service (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).

additional_underwriting_data.refund_policystring

The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).

Enum"NO_REFUNDS""MERCHANDISE_EXCHANGE_ONLY""30_DAYS""OTHER"

additional_underwriting_data.volume_distribution_by_business_typeobject

IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).

entityobjectrequired

The underwriting details required to verify Identities.

entity.annual_card_volumeintegerrequired

The annual credit card sales (in cents) expected to be processed (max 19 characters).

entity.business_addressobject or nullrequired

The primary address for the legal entity.

entity.business_address.citystringnon-emptyrequired

City (max 20 characters).

entity.business_address.countrystringnon-emptyrequired

The 3-Letter country code (e.g. USA).

entity.business_address.regionstringnon-emptyrequired

A 2-letter state abbreviation such as CA (California).

entity.business_address.line2string or nullnon-empty

The second line of the address (max 35 characters).

entity.business_address.line1stringnon-emptyrequired

First line of the address (max 35 characters).

entity.business_address.postal_codestringnon-emptyrequired

The 5-digit ZIP code of the business.

entity.business_namestring or nullrequired

The merchant's legal business name (max 120 characters).

For INDIVIDUAL_SOLE_PROPRIETORSHIP, pass the owner's legal first and last name
Special characters are not allowed (e.g., .,_-?+*/)

entity.business_phonestringrequired

A customer service phone number where the merchant can be reached (max 10 characters). This field supports any country code and accepts pluses and hyphens.

entity.business_tax_idstringrequired

9-digit Employer Identification Number (EIN). If the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP, and they do not have an EIN, use the sole proprietor's Social Security Number (SSN) or null.

entity.business_typestringrequired

The business entity type of the Merchant.

Enum"INDIVIDUAL_SOLE_PROPRIETORSHIP""CORPORATION""LIMITED_LIABILITY_COMPANY""PARTNERSHIP""ASSOCIATION_ESTATE_TRUST""TAX_EXEMPT_ORGANIZATION""INTERNATIONAL_ORGANIZATION""GOVERNMENT_AGENCY"

entity.default_statement_descriptorstringrequired

The description of the merchant that appears on the buyer's bank or card statement.

entity.dobobjectrequired

The control owner's date of birth.

entity.dob.dayintegerrequired

Day of birth (between 1 and 31).

entity.dob.monthintegerrequired

Month of birth (between 1 and 12).

entity.dob.yearintegerrequired

Year of birth (4-digit). Year must be greater than 1900

entity.doing_business_asstringrequired

Alternate names of the business. If there are no other names, pass the same value used for business_name (max 60 characters).

entity.emailstringrequired

The email address of the principal control owner where they can be reached (max 100 characters).

entity.first_namestringrequired

The legal first name of the merchant's control owner (max 20 characters).

entity.has_accepted_credit_cards_previouslybooleanrequired

Defaults to false if not passed.

entity.incorporation_dateobject or nullrequired

The date the company was founded and registered.

entity.incorporation_date.dayintegerrequired

Day business was incorporated (between 1 and 31).

entity.incorporation_date.monthintegerrequired

Month business was incorporated (between 1 and 12).

entity.incorporation_date.yearintegerrequired

Year business was incorporated (4-digit).

entity.last_namestringrequired

The legal last name of the control owner (max 20 characters).

entity.max_transaction_amountintegerrequired

The maximum amount (in cents) that can be charged for a single transaction (max 12 characters).

entity.ach_max_transaction_amountintegerrequired

The maximum amount (in cents) that can be charged for a single ACH transaction (max 12 characters).

entity.mccstringrequired

The Merchant Category Code (MCC) that this merchant will be classified under. For a list of approved MCCs, see Approved Merchant Category Codes.

entity.ownership_typestring or nullrequired

Must be either:

PUBLIC for publicly-traded businesses, tax-exempt organizations, and government agencies.
PRIVATE for privately-held businesses, including sole proprietorships.

Enum"PUBLIC""PRIVATE"

entity.personal_addressobjectrequired

The billing address of the Principal Owner. This field is used for identity verification purposes.

entity.personal_address.citystringrequired

City (max 20 characters).

entity.personal_address.countrystringrequired

3-Letter country code (e.g. USA).

entity.personal_address.line1stringrequired

First line of the address (max 35 characters).

entity.personal_address.line2string

Second line of the address (max 35 characters).

entity.personal_address.postal_codestringrequired

The 5-digit ZIP code of the business.

entity.personal_address.regionstringrequired

A 2-letter state abbreviation such as CA (California).

entity.phonestringrequired

The principal control owner's phone number (max 10 characters). This field supports any country code and accepts pluses and hyphens.

entity.principal_percentage_ownershipintegerrequired

Percentage of the company owned by the principal control owner (min 0; max 100).

entity.tax_idstringrequired

Pass one of the following 9-digit values:

Social Security Number (SSN)
Individual Taxpayer Identification Number (ITIN)

entity.titlestringrequired

The corporate title of the control owner (e.g. Chief Executive Officer, CFO, etc. Max 60 characters).

entity.urlstringrequired

The URL of the merchant's public website.

identity_rolesArray of strings(identity_roles)

The sets of permissions available to the Identity.

Items Enum"APPLICATION_OWNER""BENEFICIAL_OWNER""BUYER""PLATFORM_OWNER""RECIPIENT""SELLER""SENDER"

tagsobject or null(tags)

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)

typestring

The identity type.

Value"BUSINESS"

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities/IDrH4G2VTfNjn1VFkvhcyMYj/associated_identities \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": {
      "first_name": "John",
      "last_name": "Smith",
      "title": "Founder",
      "dob": {
        "month": 1,
        "day": 1,
        "year": 2013
      },
      "principal_percentage_ownership": 25,
      "phone": "14158885080",
      "personal_address": {
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "90650",
        "line1": "123 Main Street",
        "country": "USA"
      },
      "email": "john.smith@company1.com",
      "tax_id": "123456789"
    }
  }'

Responses

Single Associated Identity object

Bodyapplication/json

Any of:

idstringnon-empty

The ID of the Identity resource.

created_atstring(date-time)(CreatedAt)

Timestamp of when the object was created.

updated_atstring(date-time)(UpdatedAt)

Timestamp of when the object was last updated.

additional_underwriting_dataobject or null

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

applicationstringnon-empty

ID of the Application associated with the Identity.

entityobject

The underwriting details required to verify the Identity.

identity_rolesArray of strings(identity_roles)

The sets of permissions available to the Identity.

Items Enum"APPLICATION_OWNER""BENEFICIAL_OWNER""BUYER""PLATFORM_OWNER""RECIPIENT""SELLER""SENDER"

typestring

The identity type.

Value"BUSINESS"

tagsobject or null(tags)

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": "IDiLhNvSHfxkR4xvENPVqW1g",
  "created_at": "2024-08-09T08:34:22.30Z",
  "updated_at": "2024-08-09T08:34:22.30Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "entity": {
    "ach_max_transaction_amount": 0,
    "amex_mid": null,
    "annual_card_volume": 0,
    "business_address": null,
    "business_name": null,
    "business_phone": null,
    "business_tax_id_provided": false,
    "business_type": null,
    "default_statement_descriptor": null,
    "discover_mid": null,
    "dob": { … },
    "doing_business_as": null,
    "email": "john.smith@company1.com",
    "first_name": "John",
    "has_accepted_credit_cards_previously": false,
    "incorporation_date": null,
    "last_name": "Smith",
    "max_transaction_amount": 0,
    "mcc": null,
    "ownership_type": null,
    "personal_address": { … },
    "phone": "14158885080",
    "principal_percentage_ownership": 25,
    "short_business_name": null,
    "tax_authority": null,
    "tax_id_provided": true,
    "title": "Founder",
    "url": null
  },
  "identity_roles": [
    "BENEFICIAL_OWNER"
  ],
  "tags": {},
  "type": "PERSONAL",
  "_links": {
    "self": { … },
    "verifications": { … },
    "merchants": { … },
    "settlements": { … },
    "authorizations": { … },
    "transfers": { … },
    "payment_instruments": { … },
    "associated_identities": { … },
    "disputes": { … },
    "application": { … }
  }
}

Instrument Updates

With Finix's instrument_updates API, you can update the credit card information you have saved for customers without needing to contact each individual cardholder.

Related Guides: Account Updater

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

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

Payment Links

Payment Links create individual links you can send to buyers to complete a transaction. You can share these links on different platforms such as web pages, email, text, or QR codes.

Related Guides: Payment Links

Operations

Payout Links

A Payout Link is a unique, one-time link you can send via email or text to a recipient for fast and secure payouts. For card-based payouts, funds are typically available within minutes.

Payout Links can be used for various purposes, including insurance payments, sales commissions, and more. Each link can be customized to display your brand name and logo, providing a seamless experience for recipients.

Related Guides: Payout Links

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

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: Onboarding Process, Collecting Fees

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: Collecting Fees

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

Finix API

Authentication

Environments

HTTP Codes and Errors

Idempotent Requests

Query Parameters

Tags

Versioning

Authorizations

Compliance Forms

Devices

Disputes

Fees

Fee Profiles

Files

Identities

Fetch an Identity

Request

Responses

Was this helpful?

Update an Identity

Request

Responses

Was this helpful?

Create an Associated Identity

Request

Responses

Was this helpful?

Instrument Updates

Merchants

Onboarding Forms

Payment Instruments

Settlements

Settlement Queue Entries

Split Transfers

Transfers

Users

Webhooks

Checkout Forms

Payment Links

Payout Links

Receipts

Subscriptions

Subscription Plans

Transfer Attempts

Balances

Balance Adjustments

Application Profiles

Applications

Balance Transfers

Merchant Profiles

Payout Profiles

Review Queue Items

Verifications