Account Structure

Finix is composed of several objects and resources that work together and get updated based on the transaction at hand.

This guide details those different resources and how they make changes to one another to process payments.

Account Overview

When you sign up for Finix, you get a pair of credentials that you use to setup your Finix Dashboard or create requests with Finix's API. Due to the sensitive nature of these credentials, access is tightly controlled.

Users have three potential roles in Finix, which provide different levels of access:

Role	Permissions
ROLE_PLATFORM	Access to all `Applications` and `Merchant` data (Finix Core Only). Access every permission for any `Application` created with the ROLE_PLATFORM credentials (e.g., Create a Sale, `Identity`, `Reversal`, `Payment Instrument`, etc.). Users can create `Applications`, `Merchants` and assign ROLE_PARTNER and ROLE_MERCHANT credentials. ROLE_PLATFORM credentials are Finix's highest level of access; ROLE_PLATFORM users can see and manage almost everything.
ROLE_PARTNER	Access to the data of one `Application` and that application’s `Merchant` data (i.e., `Merchants` created under the `Application`). Access to ROLE_MERCHANT permissions for any `Merchant` created under the `Application` (e.g., Create a Sale, `Identity`, `Reversal`, `Payment Instrument`, etc.). Users can create `Merchants` and assign ROLE_MERCHANT credentials. ROLE_PARTNER credentials are the highest level of access available for Finix Flex customers; ROLE_PARTNER credentials enable you to investigate any issues that can come up when processing a `Merchants` payments.
ROLE_MERCHANT	Access to the data of one `Merchant`. Freely use Finix's API with one `Merchant` (e.g., Create a Sale, `Identity`, `Reversal`, `Payment Instrument`, etc.). ROLE_MERCHANT credentials are for your customers; `Merchants` who use your platform to connect with buyers.

Finix ROLE_PLATFORM credentials have the highest levels of access and offer the most customizability. However, more developer work is involved, and ROLE_PLATFORM users are held liable for more responsibilities like approving Settlements.

Finix Flex customers receive ROLE_PARTNER credentials.
Finix Core customers receive ROLE_PLATFORM credentials.

If you have any questions about the credentials you receive, reach out to your Finix point of contact or Finix Support.

Resources

Applications

The Application resource represents your app or platform. This could be an iOS or Android app, a website, an online marketplace, a 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 that's integrating with Finix and merchants are using to connect with customers (i.e. buyers).

Authorizations

An Authorization resource represents a charge or card hold made by a Merchant to verify the buyer's payment method has the necessary funds.

When an Authorization gets created, a specific amount gets reserved on the Payment Instrument associated with the Identity that represents the buyer. The amount gets captured (i.e. debited) at a later date, usually within 7 days.

When an Authorization gets captured, a Transfer resource gets created to process the movement of funds.

Identities

The Identity resource represents either a buyer or a merchant.

Sales (called Transfers ) and payment methods (called Payment Instruments) get created under and linked with an Identity`.
The Identity resource helps manage payments, payment methods, bank accounts, transaction history, identity verification, and payouts between buyers and merchants.

Merchants

The Merchant resource represents a business, such as a web service that connects buyers (i.e. customers) and sellers (i.e. merchants) and the account created for them with our payment processor.

A Merchant is created under an Identity (or a collection of Identity resources) and is used to process buyers' credit cards and receive Merchant Identification Numbers (MIDs) from our payment processor.

Payment Instruments

The Payment Instrument object represents a payment method (a credit card, bank account, token etc.).

A Payment Instrument gets created under an Identity and can only get linked to that one Identity. Once created, a Payment Instrument can't be disconnected from the Identity it was created under.

When a Payment Instrument gets created, the payment method details get tokenized, and a unique Payment Instrument ID gets created that represents the payment method in Finix moving forward.

Settlements

A Settlement resource represents a collection (i.e. batch) of Transfers that will get paid out to a Merchant.

Merchants get paid out when settlements are approved by either the platform (Finix Core only) or Finix. For more information, see Payouts.

Transfers

A Transfer resource represents any flow of money from one Payment Instrument to another.

An Authorization always creates a Transfer when captured; however, Transfers can get created for other reasons, including processing refunds, reversals, and paying out merchants.