Key Resources and Account Structure
Understand the structure of your Finix account and how the different components work together to process payments.
Finix is composed of several objects and resources that work together. The following details those different resources and how they relate to each other.
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
Webhooks, and your
Application Profile. These are discussed in further detail down below.
If you are a Core customer. Your setup is slightly different with your
Platform resource as your root entity. You will still need to create one or more
Applications for the rest of your API interactions with Finix.
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
Identityresource includes Know Your Customer, and they'll need to get onboarded.
- For buyers, it stores whatever information you want Finix to store , commonly this is addresses, emails, or phone numbers.
Identity object links many resources together.
Transfers) and payment methods (called
Payment Instruments) get created under and linked with an
Identityresource helps manage payments, payment methods, bank accounts, transaction history, identity verification, and payouts between buyers and sellers.
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.
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 Instrument object represents a payment method (a credit card, bank account, token etc.).
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.
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.
Transfer resource represents any flow of money from one
Payment Instrument to another.
Transfers appear on the Finix Dashboard under Transactions.
Authorization always creates a
Transfer when captured; however,
Transfers can get created for other reasons, including processing refunds, reversals, and paying out merchants.
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 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 ACH (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:
Transferis still processing. It will resolve to another state. If a transfer stays in PENDING for an extended period of time, reach out to Support.
The Transfer was successful, and the funds will soon be available for
ready_to_settle_atfield indicates when the
Transferwill be included and batched into a
The Payment was declined. Refer to the
failure_messagefor details on why the transaction was declined .
- CANCELED: There was an issue with the processor, please reach out to support.
A connection or timeout issue occurred while the
Transfergot created or updated. Reattempt the
Authorization resource represents a charge or card hold made by a
Merchant to verify the buyer's payment method has the necessary funds.
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.
Authorization gets captured, a
Transfer resource gets created to process the movement of funds.
Settlement resource represents a collection (i.e. batch) of
Transfers that will get paid out to a
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.
- Dashboard User
- API User
To Create a dashboard user, reach out to Finix support. You must create API User yourself.
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
Finix uses a concept called "profiles" that enable you to define a root configuration for charging fees, risk settings, and payout schedules.
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
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 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 specifies the risk configuration for a
Per Merchant Customization
You can change the profiles on a
Merchant Profile and it will only affect the
Merchant Profile is associated to.
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