Onboarding With the Finix API

Learn how to onboard your sellers or service providers using the Finix API.

Using the API to onboard your sellers or service providers gives you the most control. Onboarding with the API flow looks the same, regardless the type of business you onboard:

Collect information and consent for Finix's Terms of Service.
Create an Identity.
Add Associated Identities for owners with 25%+ ownership.
Add a bank account.
Verify the Identity.

onboard with api flow

Check out our react.js example for a complete example of how to create an onboarding flow.

Supported Countries

United States
Canada

Step 1: Collect Information and Consent

To enable payment processing for your seller, you need to:

Collect the identifying information of your seller, this includes information about the business and associated owners and peoples.
Obtain the sellers consent to the Finix Terms of Service.
Communicate your payment processing fees to the seller.

Once you've completed these steps, you'll create a Merchant Identity with your seller's information.

Identifying Information

Identifying information is collected to verify:

The identities of the seller's business entity.
The Control Person (the person authorized to sign up the business).
Any additional owners with at least 25% ownership in the business.

The information you need to collect includes data such as names, addresses, tax identification numbers, and the expected processing volumes.

For a full list of applicable fields, see Required Verification Information.

Informing Sellers That Their Identity Will Be Verified

You must inform your sellers that they are applying for payment processing services and that their identity will be verified. You must add the following text at the beginning of the seller application:

Copy

Copied

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

Finix Terms of Service

You must have each seller accept the Finix Terms of Service.

Showing the Finix Terms of Service

You must present your sellers a link to the Finix Terms of Service. The seller must explicitly consent to Finix Terms of Service prior to submitting the Merchant Identity and identifying information to Finix.

Prior to submitting an Identity to Finix, you must present the following to sellers:

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

A link to both Finix and your platform’s terms of service needs to be included in this text.

You indicate to Finix that you've received your seller's consent by providing the following fields to Finix when creating an Identity:

Field	Type	Description
`merchant_agreement_accepted`	boolean, required	Sets whether this seller has accepted the terms and conditions of the Finix Terms of Service.
`merchant_agreement_ip_address`	string, required	IP address of the seller when they accepted Finix Terms of Service (e.g., 42.1.1.113).
`merchant_agreement_timestamp`	string, required	Timestamp of the when the seller accepted Finix Terms of Service (e.g., 2021-04-28T16:42:55Z).
`merchant_agreement_user_agent`	string, required	The user agent of the browser when this merchant accepted the Finix Terms of Service (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)).

Communicating Payment Processing Fees

You must present the payment processing fees to your sellers clearly and prominently on the final application screen. Additionally, you must communicate any fee changes to your sellers with prior notice.

Collecting Bank Account Information

You must explicitly communicate to sellers that bank accounts submitted for a merchant application are only to be used for business purposes.

The following text must be used on the page where bank account information gets collected:

Copy

Copied

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

Step 2: Create an Identity

To submit the information collected in the previous step to Finix, create an Identity.

The Identity is the container for all the identifying information and is the root representation of your seller and their business. It is used to associate other resources for your seller as shown in the following steps.

When you create an Identity, you need to provide information about the primary controlling owner, called a Control Person, which includes their name, date of birth, personal address, and tax ID.

When onboarding sole proprietorships , provide the person's information on the Identity itself, you don't need to create a beneficial owner.
For all other business_types , you must collect beneficial owner

USACAN

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "additional_underwriting_data": {
        "annual_ach_volume": 200000,
        "average_ach_transfer_amount": 200000,
        "average_card_transfer_amount": 200000,
        "business_description": "SB3 vegan cafe",
        "card_volume_distribution": {
          "card_present_percentage": 30,
          "mail_order_telephone_order_percentage": 10,
          "ecommerce_percentage": 60
        },
        "credit_check_allowed": true,
        "credit_check_ip_address": "42.1.1.113",
        "credit_check_timestamp": "2021-04-28T16:42:55Z",
        "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
        "merchant_agreement_accepted": true,
        "merchant_agreement_ip_address": "42.1.1.113",
        "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
        "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
        "volume_distribution_by_business_type": {
          "other_volume_percentage": 0,
          "consumer_to_consumer_volume_percentage": 0,
          "business_to_consumer_volume_percentage": 0,
          "business_to_business_volume_percentage": 100,
          "person_to_person_volume_percentage": 0
        }
      },
      "entity": {
        "annual_card_volume": 12000000,
        "business_address": {
          "city": "San Mateo",
          "country": "USA",
          "line1": "741 Douglass St",
          "line2": "Apartment 8",
          "postal_code": "94114",
          "region": "CA"
        },
        "business_name": "Finix Flowers",
        "business_phone": "+1 (408) 756-4497",
        "business_tax_id": "123456789",
        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "default_statement_descriptor": "Finix Flowers",
        "dob": {
          "year": 1978,
          "day": 27,
          "month": 6
        },
        "doing_business_as": "Finix Flowers",
        "email": "user@example.org",
        "first_name": "John",
        "has_accepted_credit_cards_previously": true,
        "incorporation_date": {
          "year": 1978,
          "day": 27,
          "month": 6
        },
        "last_name": "Smith",
        "max_transaction_amount": 12000000,
        "mcc": "4900",
        "ownership_type": "PRIVATE",
        "personal_address": {
          "city": "San Mateo",
          "country": "USA",
          "line1": "741 Douglass St",
          "line2": "Apartment 7",
          "postal_code": "94114",
          "region": "CA"
        },
        "phone": "1234567890",
        "principal_percentage_ownership": 50,
        "tax_id": "123456789",
        "title": "CEO",
        "url": "www.Finix.com"
      },
      "tags": {
        "Studio Rating": "4.7"
      }
    }'

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "additional_underwriting_data": {
        "annual_ach_volume": 200000,
        "average_ach_transfer_amount": 200000,
        "average_card_transfer_amount": 200000,
        "business_description": "SB3 vegan cafe",
        "card_volume_distribution": {
          "card_present_percentage": 30,
          "mail_order_telephone_order_percentage": 10,
          "ecommerce_percentage": 60
        },
        "credit_check_allowed": true,
        "credit_check_ip_address": "42.1.1.113",
        "credit_check_timestamp": "2021-04-28T16:42:55Z",
        "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
        "merchant_agreement_accepted": true,
        "merchant_agreement_ip_address": "42.1.1.113",
        "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
        "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
        "volume_distribution_by_business_type": {
          "other_volume_percentage": 0,
          "consumer_to_consumer_volume_percentage": 0,
          "business_to_consumer_volume_percentage": 0,
          "business_to_business_volume_percentage": 100,
          "person_to_person_volume_percentage": 0
        }
      },
      "entity": {
        "annual_card_volume": 12000000,
        "business_address": {
          "city": "Toronto",
          "country": "CAN",
          "line1": "456 Main St",
          "line2": "Apartment 8",
          "postal_code": "A1A 2B2",
          "region": "ON"
        },
        "business_name": "Finix Flowers",
        "business_phone": "+1 (408) 756-4497",
        "business_tax_id": "123456789",
        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "default_statement_descriptor": "Finix Flowers",
        "dob": {
          "year": 1978,
          "day": 27,
          "month": 6
        },
        "doing_business_as": "Finix Flowers",
        "email": "user@example.org",
        "first_name": "John",
        "has_accepted_credit_cards_previously": true,
        "incorporation_date": {
          "year": 1978,
          "day": 27,
          "month": 6
        },
        "last_name": "Smith",
        "max_transaction_amount": 12000000,
        "mcc": "4900",
        "ownership_type": "PRIVATE",
        "personal_address": {
          "city": "Toronto",
          "country": "CAN",
          "line1": "123 Main St",
          "line2": "Apartment 7",
          "postal_code": "A1A 2B2",
          "region": "ON"
        },
        "phone": "1234567890",
        "principal_percentage_ownership": 50,
        "tax_id": "123456789",
        "title": "CEO",
        "url": "www.Finix.com"
      },
      "tags": {
        "Studio Rating": "4.7"
      }
    }'

Step 3: Add Associated Identities

For owners with 25% or more ownership, you need to add Associated Identities. If there are no owners with at least 25% ownership, then you may skip this step.

To provide information about additional owners, create an associated_identity on the Identity.

If there are multiple substantial owners, create an Identity for every substantial owner (also called Control Owner) and pass 1 as the principal_percentage_ownership.

USACAN

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities/ID4vjvighzmnNbNQeWim23hJ/associated_identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "entity": {
        "dob": {
          "day": 1,
          "month": 1,
          "year": 2013
        },
        "email": "john.smith@company1.com",
        "first_name": "John",
        "last_name": "Smith",
        "personal_address": {
          "city": "San Francisco",
          "country": "USA",
          "line1": "123 Main Street",
          "postal_code": "90650",
          "region": "CA"
        },
        "phone": "1234567890",
        "principal_percentage_ownership": 25,
        "tax_id": "123456789",
        "title": "Founder"
      }
    }'

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities/ID4vjvighzmnNbNQeWim23hJ/associated_identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "entity": {
        "dob": {
          "day": 1,
          "month": 1,
          "year": 2013
        },
        "email": "john.smith@company1.com",
        "first_name": "John",
        "last_name": "Smith",
        "personal_address": {
          "city": "Toronto",
          "country": "CAN",
          "line1": "123 Main St",
          "postal_code": "A1A 2B2",
          "region": "ON"
        },
        "phone": "1234567890",
        "principal_percentage_ownership": 25,
        "tax_id": "123456789",
        "title": "Founder"
      }
    }'

Step 4: Add a Bank Account

To add a bank account for a seller, create a Payment Instrument. Include the identity_id created in the previous step to associate the Payment Instrument with the seller.

Note: Certain consumer banks will not accept deposits from Finix. In the event that a bank does not accept deposits, we'll ask you to create a new Payment Instrument. The bank account gets verified in the next step (Verify the Seller).

USACANPlaid

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "account_number": "123123123",
      "account_type": "BUSINESS_CHECKING",
      "bank_code": "123123123",
      "country": "USA",
      "currency": "USD",
      "identity": "IDx2ZETjYiWkbitkYdFt1yLF",
      "name": "John",
      "type": "BANK_ACCOUNT",
      "tags": {
        "Bank Account": "Company Account"
      }
    }'

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "account_number": "123123123",
      "account_type": "PERSONAL_CHECKING",
      "country" : "CAN",
      "currency": "CAD",
      "identity": "IDx2ZETjYiWkbitkYdFt1yLF", 
      "institution_number": "123",
      "name": "John Smith",
      "transit_number": "12345",
      "type": "BANK_ACCOUNT",
      "tags": {
        "Bank Account": "Company Account"
      }
    }'

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "identity": "IDpYDM7J9n57q849o9E9yNrG",
      "third_party": "PLAID",
      "third_party_token": "processor-sandbox-0asd1-a92nc",
      "type": "BANK_ACCOUNT"
    }'

Step 5: Verify the Seller

Once all the information has been collected and submitted to Finix, you need to finish onboarding by successfully verifying (also known as provisioning) the seller.

To provision the seller, create a Merchant . You will use the Merchant to create payments and reconcile settlements and payouts.

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities/IDx2ZETjYiWkbitkYdFt1yLF/merchants \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "processor": "DUMMY_V1",
      "tags": {
        "key_2": "value_2"
      }
    }'

A successful response returns the newly created merchant in a PROVISIONING state. At this point, the Merchant isn't ready yet to process payments and is getting reviewed by Finix.

USACAN

Copy

Copied

{
  "id": "MUk3936kZweevCrjyHLN1vsu",
  "created_at": "2022-10-10T05:20:18.12Z",
  "updated_at": "2022-10-10T05:20:18.12Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "convenience_charges_enabled": false,
  "country": "USA",
  "currencies": [
    "USD"
  ],
  "creating_transfer_from_report_enabled": false,
  "default_partial_authorization_enabled": false,
  "fee_ready_to_settle_upon": "RECONCILIATION",
  "gross_settlement_enabled": false,
  "identity": "IDx2ZETjYiWkbitkYdFt1yLF",
  "level_two_level_three_data_enabled": false,
  "mcc": "4900",
  "merchant_name": "Finix Flowers",
  "merchant_profile": "MPnXB4UBGtSUfxwA41z2Hqid",
  "mid": null,
  "onboarding_state": "PROVISIONING",
  "processing_enabled": false,
  "processor": "DUMMY_V1",
  "processor_details": {},
  "ready_to_settle_upon": "RECONCILIATION",
  "rent_surcharges_enabled": false,
  "settlement_enabled": false,
  "settlement_funding_identifier": "UNSET",
  "surcharges_enabled": false,
  "tags": {
    "key_2": "value_2"
  },
  "verification": "VItUgbe9V8vpgSaJAriLDxER",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUk3936kZweevCrjyHLN1vsu"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDx2ZETjYiWkbitkYdFt1yLF"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUk3936kZweevCrjyHLN1vsu/verifications"
    },
    "merchant_profile": {
      "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPnXB4UBGtSUfxwA41z2Hqid"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification": {
      "href": "https://finix.sandbox-payments-api.com/verifications/VItUgbe9V8vpgSaJAriLDxER"
    }
  }
}

Copy

Copied

{
  "id": "MUk3936kZweevCrjyHLN1vsu",
  "created_at": "2022-10-10T05:20:18.12Z",
  "updated_at": "2022-10-10T05:20:18.12Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "convenience_charges_enabled": false,
  "country": "CAN",
  "currencies": [
    "CAD"
  ],
  "creating_transfer_from_report_enabled": false,
  "default_partial_authorization_enabled": false,
  "fee_ready_to_settle_upon": "RECONCILIATION",
  "gross_settlement_enabled": false,
  "identity": "IDx2ZETjYiWkbitkYdFt1yLF",
  "level_two_level_three_data_enabled": false,
  "mcc": "4900",
  "merchant_name": "Finix Flowers",
  "merchant_profile": "MPnXB4UBGtSUfxwA41z2Hqid",
  "mid": null,
  "onboarding_state": "PROVISIONING",
  "processing_enabled": false,
  "processor": "DUMMY_V1",
  "processor_details": {},
  "ready_to_settle_upon": "RECONCILIATION",
  "rent_surcharges_enabled": false,
  "settlement_enabled": false,
  "settlement_funding_identifier": "UNSET",
  "surcharges_enabled": false,
  "tags": {
    "key_2": "value_2"
  },
  "verification": "VItUgbe9V8vpgSaJAriLDxER",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUk3936kZweevCrjyHLN1vsu"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDx2ZETjYiWkbitkYdFt1yLF"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUk3936kZweevCrjyHLN1vsu/verifications"
    },
    "merchant_profile": {
      "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPnXB4UBGtSUfxwA41z2Hqid"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification": {
      "href": "https://finix.sandbox-payments-api.com/verifications/VItUgbe9V8vpgSaJAriLDxER"
    }
  }
}

Verification and underwriting is an asynchronous process and will take several minutes to complete. Once a Merchant has been successfully provisioned, you'll receive a webhook event with an entity of merchant and the type of underwritten.

Merchant Underwritten Webhook Event

USACAN

Copy

Copied

{
  "type": "underwritten",
  "entity": "merchant",
  "occured_at": "2021-11-14T19:20:29.48Z",
  "_embedded": {
    "merchants": [
      {
        "id": "MUk3936kZweevCrjyHLN1vsu",
        "created_at": "2022-10-10T05:20:18.12Z",
        "updated_at": "2022-10-10T05:20:18.12Z",
        "application": "APgPDQrLD52TYvqazjHJJchM",
        "card_cvv_required": false,
        "card_expiration_date_required": true,
        "convenience_charges_enabled": false,
        "country": "USA",
        "currencies": [
          "USD"
        ],
        "creating_transfer_from_report_enabled": false,
        "default_partial_authorization_enabled": false,
        "fee_ready_to_settle_upon": "RECONCILIATION",
        "gross_settlement_enabled": false,
        "identity": "IDx2ZETjYiWkbitkYdFt1yLF",
        "level_two_level_three_data_enabled": false,
        "mcc": "4900",
        "merchant_name": "Finix Flowers",
        "merchant_profile": "MPnXB4UBGtSUfxwA41z2Hqid",
        "mid": null,
        "onboarding_state": "APPROVED",
        "processing_enabled": true,
        "processor": "DUMMY_V1",
        "processor_details": {},
        "ready_to_settle_upon": "RECONCILIATION",
        "rent_surcharges_enabled": false,
        "settlement_enabled": true,
        "settlement_funding_identifier": "UNSET",
        "surcharges_enabled": false,
        "tags": {
          "key_2": "value_2"
        },
        "verification": "VItUgbe9V8vpgSaJAriLDxER"
      }
    ]
  }
}

Copy

Copied

{
  "type": "underwritten",
  "entity": "merchant",
  "occured_at": "2021-11-14T19:20:29.48Z",
  "_embedded": {
    "merchants": [
      {
        "id": "MUk3936kZweevCrjyHLN1vsu",
        "created_at": "2022-10-10T05:20:18.12Z",
        "updated_at": "2022-10-10T05:20:18.12Z",
        "application": "APgPDQrLD52TYvqazjHJJchM",
        "card_cvv_required": false,
        "card_expiration_date_required": true,
        "convenience_charges_enabled": false,
        "country": "CAN",
        "currencies": [
          "CAD"
        ],
        "creating_transfer_from_report_enabled": false,
        "default_partial_authorization_enabled": false,
        "fee_ready_to_settle_upon": "RECONCILIATION",
        "gross_settlement_enabled": false,
        "identity": "IDx2ZETjYiWkbitkYdFt1yLF",
        "level_two_level_three_data_enabled": false,
        "mcc": "4900",
        "merchant_name": "Finix Flowers",
        "merchant_profile": "MPnXB4UBGtSUfxwA41z2Hqid",
        "mid": null,
        "onboarding_state": "APPROVED",
        "processing_enabled": true,
        "processor": "DUMMY_V1",
        "processor_details": {},
        "ready_to_settle_upon": "RECONCILIATION",
        "rent_surcharges_enabled": false,
        "settlement_enabled": true,
        "settlement_funding_identifier": "UNSET",
        "surcharges_enabled": false,
        "tags": {
          "key_2": "value_2"
        },
        "verification": "VItUgbe9V8vpgSaJAriLDxER"
      }
    ]
  }
}

Once underwritten, the Identity has been successfully onboarded and is approved to process payments.

Next Steps

Once approved, your seller can process payments using the Merchant Resource.

Re-Verifying Already Approved Merchants

If the information used to create the Merchant changes, you need to update the info saved for the seller in Finix (e.g. change in address, name, ownership, etc.). To update a Merchant in Finix:

Update the Merchant's Identity .
- Update the information saved in an Identity resource with a PUT call on /identities and any associated identities. For more info, see Update an Identity .
Submit a new Merchant Verification Request.
- To submit a new request, provision the Merchant again. For details, see Reattempt Merchant Provisioning .

Once the provision request is submitted, we re-verify the information saved with the new information provided.

Updating Tax ID Approved Sellers

To update the tax ID information saved for an already approved seller, you need to create a new Identity and onboard them again.