Resources and Account Structure

Finix is composed of several objects and resources that work together.

This guide details:

• The different resources and how they relate to each other.
• How to understand your account structure.

Resources

Here's an overview of Finix resources and how they link together. This diagram is complex, but we explain each resource on their own with their immediate relationships.

Applications

The Application resource represents your own business or platform within the Finix system. As this represents you, it is your root entity in Finix and most resources will include an application id that points back to you.

There are several resources that are the direct child of an application, this includes Users, Identities, Webhooks, and your Application Profile. These are discussed in further detail down below.

Identities

The Identity resource represents either a person or a business and stores their information. You will create them for both the sellers and service providers you board as well as the buyers:

• For your users you are enabling to accept payments (i.e. sellers, service providers, merchants) the Identity resource includes Know Your Customer, and they will need to onboarded.
• For buyers, it stores whatever information you want Finix to store , commonly this is addresses, emails, or phone numbers.

Just one Identity object links many resources together.

• Payments (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 sellers.

Merchants

The merchant resource represents the capability of an Identity to process payments. Usually, identities only need one merchant, but in some scenarios, they may have multiple. Most often, this occurs when an Identity wants to accept both online payments and in-person payments where a merchant is required for each flow.

A merchant is created under an Identity 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.

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.

A transfer represents any flow of funds either to or from a Payment Instrument. For example, a transfer can be a credit to a bank account or a refund to a card; any movement of funds is considered a transfer.

• Currently, transfers can only be created using the Finix API. We're working on bringing this functionality to the Finix Dashboard. If you have any questions about creating a sale, or processing a payment, reach out to your Finix point of contact or email Finix support .

A transfer can have one of three types: Debit, Credit, or Reversal. Each type indicates a different funds flow. For example:

• A Debit is created after capturing an Authorization or creating an eCheck (also called ACH payment) where funds are pulled from the issuer into the settlement account.
• A Reversal represents a refund or chargeback where funds get returned to a customer.
• A Credit is produced when funds are transferred to a merchant's bank account when funding (i.e. paying out) a batch settlement .

transfers can have five possible states:

• PENDING: The transfer is still processing. It will resolve to another state. If a transfer stays in PENDING for an extended period of time, reach out to Support.
• SUCCEEDED: The Transfer was successful, and the funds will soon be available for Payout . The ready_to_settle_at field indicates when the transfer will be included and batched into a Settlement .
• FAILED: The Payment was declined. Refer to the failure_code and failure_message for details on why the transaction was declined .
• CANCELED: There was an issue with the processor, please reach out to support.
• UNKNOWN: A connection or timeout issue occurred while the Transfer got created or updated. Reattempt the Transfer .

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.

Settlements

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

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

Users

A User represents:

• Dashboard User
• API User

To Create a dashboard user, reach out to Finix support. You must create API User yourself.

Files

A File represents a file that is or will be uploaded into Finix. Files can be uploaded for any resource, though this is most often used during onboarding where documents may be required for an Identity or a merchant.

Profiles

Finix uses a concept called "profiles" that enable you to define a root configuration for charging fees, risk settings, and payout schedules.

Application Profile

An Application Profile stores a base set of profiles: fee_profile and risk_profile. Whenever you create a merchant, a new merchant_profile is created with a fee_profile and risk_profile that are a copy of the profiles in the Application Profile.

Merchant Profile

Each merchant will have it's own, unique, merchant_profile. Merchant profiles are not shared between merchants.

The merchant profile points to the fee_profile and risk_profile that applies to the merchant

Fee Profile

A Fee Profile specified how you will charge fees to your seller for their specific merchant's payment processing. The fee profile contains a list of each fee type and the amount you want to charge the merchant.

Risk Profile

A Risk Profile specifies the risk configuration for a merchant.

Per Merchant Customization

You can change the profiles on a merchant_profile and it will only affect the merchant the merchant profile is associated to.

Account structure

Finix enables many payment flows but the key account relationships start with your Application which is your main account. Your Application will have many Identities for your buyers and sellers or service providers.

For buyers, their Identities will have one or more Payment Instruments for each payment method they save with you.

For sellers or service providers, their identities will have one or more Payment Instruments for the bank account their funds are paid out to. Additionally, they will have one or more merchants for each payment capability you enable for them, such as enabling both online and in-store payments with one Identity.