Seller Onboarding via API

Learn how to onboard your sellers with Finix APIs.

Finix offers APIs to onboard your sellers directly to Finix. The process follows the same steps as our Onboarding Forms, while giving you the most control over your seller's onboarding experience.

Onboarding sellers via API involves 5 steps:

Collect your sellers' information and consent to the onboarding process
Create an Identity with your seller's business and personal information
Create a Payment Instrument with your seller's bank account information
Create a Merchant that your seller will use to process payments
Listen for updates to the Merchant account as Finix reviews your seller

Step 1: Collect Information and Consent

To board sellers directly via API, Finix requires that you:

Collect your sellers' business, ownership, processing, and bank account information
Present language to your sellers that their information will be verified
Present both Finix's and your own terms of service to your sellers
Present your payment processing fees to your sellers

Collecting Information

Finix requires you collect the following information about your sellers:

Business information: Finix collects data about your seller's business, such as their business name.
Owner information: Finix collects data about your seller's control person, such as their personal name.
Processing information: Finix collects data about your seller's processing information, such as volumes.
Bank account information: Finix collects details about your seller's bank account for their payouts.

See Onboarding Data and Identities for the full list of required fields and data formats.

Collecting Bank Account Information

When collecting bank account information, you must use the following language to communicate to your sellers that the bank account provided should only be used for business purposes:

You agree to use this bank account for legitimate business purposes, and not for personal, family, or household purposes.

Verification Consent

You must present your sellers with language informing them that they are applying for payment processing services, and that their identity will be verified. Please add the following text at the beginning of your onboarding process:

The information you provide will be used to verify your identity. Additional information may be requested.

Terms of Service

You must present both Finix's and your own terms of service to your sellers, which your sellers must explicitly consent to via click-through agreement. Please add the following text to your onboarding process, which should hyperlink to both Finix's and your own terms of service:

By continuing, you agree to our Terms of Service and the Finix Terms of Service.

The Finix Terms of Service version you link to varies by your seller's business country and payment processor:

Country	Processor	ToS Version
United States (USA)	`FINIX_V1`	Link
United States (USA)	`LITLE_V1`	Link
United States (USA)	`VANTIV_V1`	Link
Canada (CAN)	`FINIX_V1`	Link

Finix will collect information about your seller's consent on the Identity resource in the next step.

Presenting Fees

You must present your payment processing fees to your sellers clearly and prominently in your onboarding process. In addition, you must communicate fee changes to your sellers with prior notice.

Step 2: Create an Identity

After the previous step is complete, you are ready to create an Identity for your seller. The Identity holds the business, personal, processing, and consent information from your seller, which Finix underwrites during the review process. Each Identity can hold one person's information; should your seller's business have one or more beneficial owners with 25% or more ownership, you must create an Associated Identity for each beneficial owner.

See Onboarding Data and Identities for the full list of required fields and data formats.

Request:

curl -X POST \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/identities \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        ... (request body here)
    }'

Response:

{
    "id": "IDfbYwPeMVE2dVWbGuuZxMyD",
    "created_at": "2024-08-15T21:25:53.55Z",
    "updated_at": "2024-08-15T21:25:53.55Z",
    ... (response body here)
}

Step 3: Add a Bank Account

Next, you're ready to link your seller's bank account to their Identity with the Payment Instruments API. This is the bank account to which your seller will receive payouts, and is reviewed during Finix's seller underwriting process.

Request:

curl -X POST \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/payment_instruments \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        ... (request body here)
    }'

Response:

{
    "id": "PI3dGTEWFHC8XHZrqpHBHpHc",
    "created_at": "2024-08-16T12:23:02.94Z",
    "identity": "IDfbYwPeMVE2dVWbGuuZxMyD",
    ... (response body here)
}

Step 4: Create a Merchant

With your seller's Identity and Payment Instrument created, you are ready to create your seller's Merchant.

Request:

curl -X POST \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/merchants \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        ... (request body here)
    }'

Response:

{
    "id": "MUa2uYEkaRBzP8EEDeKweE5h",
    "created_at": "2024-08-16T12:23:30.79Z",
    "identity": "IDfbYwPeMVE2dVWbGuuZxMyD",
    ... (response body here)
}

Step 5: Review Process

Your seller will be ready to process payments once their Merchant account is APPROVED. Finix will update the Merchant's onboarding_state after the review process.

Receiving Webhooks

Finix sends webhooks to update you about your seller's progress throughout the onboarding process.

Handling Update Requests

Should Finix require additional information to board your seller, we will move their Merchant to an UPDATE_REQUESTED state and explain what additional information is required.

Next Steps

Next, learn how to handle update requests and listen to webhooks to move your sellers through onboarding.