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.
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.
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
id that points back to you.
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 will need to 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.
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
transferscan 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 .
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:
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:
risk_profile. Whenever you create a
merchant, a new
merchant_profile is created with a
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
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
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