Onboarding Form

Finix’s Onboarding Form is a pre-built web form hosted by Finix that takes care of collecting onboarding and identity verification information from your users.

Using Finix's Onboarding Form, you have fewer responsibilities in developing an onboarding flow and can get started processing payments more quickly. You can also customize the onboarding forms with your logo and a primary color.

attention

The APIs to create Hosted Onboarding Forms are only available for Finix Flex customers. Currently these APIs are in early access. If you’re interested in early access or have additional questions, please reach out to your Finix point of contact.

For more information about the overall onboarding flow and what's required to process payments, see Onboarding.

Onboarding users

When Finix's Onboarding Form gets enabled on your app or website:

  1. Your users enter the onboarding workflow via a Sign-up page on your app or website.

    • This page is usually a marketing page or some other value-proposition driver that entices the user to sign up so they can get started processing payments.
  2. Users get prompted to enter their business information, bank account, ownership profile, and underwriting-related data into Finix’s Onboarding Form.
  3. The entire form can also be prefilled with the user's information while creating their onboarding_form .
  4. After the user agrees to the Finix Terms of Service and submits the onboarding form, the data gets submitted to Finix and the user gets redirected back to your app or website.
  5. If the user needs to save their progress, you can reactivate the form and link users directly to where they left off when they're ready to resume.

Create a Finix Onboarding Form

Create an onboarding_form with the name of the processor you plan to onboard users to and the links they get redirected to when completing or moving away from the Finix Onboarding Form.

Use your ROLE_PARTNER credentials to create an onboarding_form.

Copy
Copied
curl -X POST \
  https://finix.sandbox-payments-api.com/onboarding_forms \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version:2022-02-01' \
  -d '{
    "onboarding_data":{
        "entity": {},
        "associated_entities": [],
        "additional_underwriting_data": {},
        "payment_instruments": {},
        "max_transaction_amount": 100000
    },
    "merchant_processors": [
        {
            "processor":"LITLE_V1"
        }
    ],
    "onboarding_link_details":{
        "return_url": "https://www.finix.com/docs",
        "expired_session_url": "https://www.finix.com/",
        "terms_of_service_url": "https://www.finix.com/terms-and-policies",
        "fee_details_url": "https://www.finix.com/docs",
        "expiration_in_minutes": "30"
    }
}'

HTTP Request

POST https://finix.sandbox-payments-api.com/onboarding_forms

Request Arguments

Field Type Description
onboarding_data object, optional The prefilled information of the user that's being onboarded. See Prefilling Fields.
merchant_processors object, required An array of objects with the processors and gateways users will be onboarded to.
merchant_processors.processor string, required The name of the processor the user will be onboarded to.
merchant_processors.gateways array, optional An array of strings with the gateways of the processor the user is onboarded to.
onboarding_link_details object, required The information of the initial onboarding link. This is only provided when creating an onboarding_form.
tags object, optional Key value pair for annotating custom metadata (e.g. customer number).

Onboarding Data Object Request Arguments

Field Type Description
entity object, optional The entity information saved in the Identity of the user.
associated_entities objects, optional The entities saved in the associated_identities of the user. For more information, see Create an Associated Identity.
additional_underwriting_data object, optional Additional underwriting data about the user.
payment_instruments object, optional The Payment Instrument that'll be used to payout the user. For more information, see Payouts.
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters) Note: Must be equal to or less than your max_transaction_amount.

Onboarding Link Details Object Request Arguments

Field Type Description
terms_of_service_url string, optional Your Terms of Service URL. The URL is provided to users for consent along with Finix's Terms of Service.
return_url string, required The URL users get sent to after completing the onboarding flow.
fee_details_url string, required The URL of the page where you display the fees related to processing payments (for more info, see Displaying Processing Fees).
expired_session_url string, required The URL users get sent to if the bearer token expires.
expiration_in_minutes integer, optional How long (in minutes) the link should be valid for. Defaults to 60 minutes.

Example Response

Copy
Copied
{
  "id" : "obf_bXQj8iSgYwXf432yJcWbKv",
  "onboarding_data" : {
    "entity" : { },
    "associated_entities" : [ ],
    "payment_instruments" : { },
    "additional_underwriting_data" : { },
    "max_transaction_amount" : 100000
  },
  "merchant_processors" : [ {
    "processor" : "LITLE_V1"
  } ],
  "onboarding_link" : {
    "expires_at" : "2022-07-11T22:19:32.123Z",
    "link_url" : "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_bXQj8iSgYwXf432yJcWbKv&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfYlhRajhpU2dZd1hmNDMyeUpjV2JLdiIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS9kb2NzIiwiZXhwaXJlZF9zZXNzaW9uX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS8iLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL2RvY3MiLCJleHAiOjE2NTc1Nzc5NzIsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNjU3NTc2MTcyLCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL3Rlcm1zLWFuZC1wb2xpY2llcyJ9.A_ItGe4ORB-vnUJ2_mrqz6mI1Hu4nSauvBzo5Utk_aQePfuAPL8ZLBWR5JGRyAB8waV6UyTsbEnxPK22s3cGMg"
  },
  "status" : "IN_PROGRESS",
  "created_at" : "2022-07-11T21:49:32.11832Z",
  "updated_at" : "2022-07-11T21:49:32.11832Z",
  "tags" : { }
}

Response

Field Type Description
id string The ID of the onboarding_form resource.
status string Status of the onboarding_from.
Available values include:
  • IN_PROGRESS
  • COMPLETED
.
onboarding_data object The prefilled information of the user that's being onboarding. See Prefilling Fields below.
merchant_processors object An array of objects with the processors and gateways users will be onboarded to.
merchant_processors.processor string The name of the processor the user will be onboarded to.
merchant_processors.gateways array The gateways of the processor the user is onboarded to.
onboarding_link object The information of the initial onboarding link. This is only provided when creating anonboarding_form.
identity_id string The ID of the identity resource.
created_at timestamp Timestamp of when the onboarding_form resource was created.
updated_at timestamp Timestamp of when the onboarding_form resource was created.
tags object Key value pair for annotating custom metadata (e.g. order numbers).

Onboarding Data Object Response

Field Type Description
entity object The entity information saved in the Identity of the user.
associated_entities object The entities saved in the associated_identities of the user. For more information, see Create an Associated Identity.
additional_underwriting_data object Additional underwriting data about the user.
payment_instruments object The Payment Instrument that'll be used to payout the user. For more information, see Payouts.
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters) Note: Must be equal to or less than your max_transaction_amount.

Onboarding Link Object Response

Field Type Description
link_url string The URL of the user's Finix Onboarding Form. Users can use the link_url to return to the form until the link expires.
expires_at timestamp A UTC timestamp detailing when the onboarding form expires and will no longer be available via link_url. To generate a new link to the same form, see Get an Onboarding Form URL.

Prefilling Fields

While creating an onboarding_form, you can prefill all of the fields by including them in your request.

Prefilling fields reduces the amount of information your users need to gather so they can complete the onboarding form more quickly.

Business Information

Information related to the business entity and its organization.

Field Type Description
business_name string User's full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters).
doing_business_as string Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters).
business_type string Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY.
business_tax_id string Nine digit Tax Identification Number (TIN) (also called an Employer Identification Number (EIN)). If the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and they do not have an EIN, use the sole proprietor's Social Security Number (SSN).
url string User's publicly available website (max 100 characters).
business_phone string Customer service phone number where the user can be reached (max 10 characters).
incorporation_date object Date company was founded (See below for a full list of the child attributes).
business_address object Primary address for the legal entity (Full description of child attributes below).
ownership_type string Values can be either PUBLIC to indicate a publicly-traded company or PRIVATE for privately-held businesses.

Control Person Information

The Control Person is the individual who owns the business (Sole proprietor) or any individual that has significant responsibility in managing and controlling the business.

  • All representatives with 25% or more ownership of the business must be added as beneficial owners as Associated Identities (or Principals as they get referred to in the form).
  • The total percentage ownership of the Control Person and beneficial owners can't exceed 100%.
Field Type Description
first_name string Full legal first name of the entity's control person (max 20 characters).
last_name string Full legal last name of the entity's control person (max 20 characters).
title string Control person's corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters).
principal_percentage_ownership integer Percentage of company owned by the control person (must be greater than 0; max 100).
tax_id string Nine digit Social Security Number (SSN) for the control person.
dob object Control person's date of birth (Full description of child attributes below).
phone string Control person's phone number (max 10 characters).
email string Control person's email address where they can be reached (max 100 characters).
personal_address object Control person's personal home address. This field is used for identity verification purposes (Full description of child attributes below).

Additional Principal Owners Information

If you have additional owners with at least 25% ownership, each individual must be added along with the Control Person.

Field Type Description
first_name string Full legal first name of the additional principal owner (max 20 characters).
last_name string Full legal last name of the additional principal owner (max 20 characters).
title string The additional principal owner's corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters).
principal_percentage_ownership integer Percentage of company owned by the additional principal owner (must be greater than 0; max 100).
tax_id string Nine digit Social Security Number (SSN) for the additional principal owner.
dob object The additional principal owner's date of birth (Full description of child attributes below).
phone string The additional principal owner's phone number (max 10 characters).
email string The additional principal owner's email address where they can be reached (max 100 characters).
personal_address object The additional principal owner's personal home address. This field is used for identity verification purposes (Full description of child attributes below).

Processing Information

Information related to how to transactions will be processed.

Field Type Description
default_statement_descriptor string The billing descriptor you want displayed on the buyer's bank or card statement (Length must be between 1 and 20 characters).
annual_card_volume integer Approximate annual credit card sales expected to be processed in cents by this user (max 19 characters).
mcc string Merchant Category Code (MCC) that this user will be classified under.
has_accepted_credit_cards_previously boolean Defaults to false if not passed.
amex_mid integer Assigned Amex MID value. If included must be 10 or 11 digits.
discover_mid integer Assigned Discover MID value.

Bank Account Information

Information related to the user and the entity's bank account.

Field Type Description
account_type string Defaults to BUSINESS_CHECKING. No prefill value required.
name string Account owner's full name (max 40 characters).
bank_code string Bank routing number.
account_number string Bank account number.

Additional Business Information

Additional information needed to verify the entity.

Field Type Description
business_description string Description of the user's business (max 200 characters).
average_card_transfer_amount integer Approximate average credit card sale amount in cents for this entity (max 10 characters).
average_ach_transfer_amount integer Approximate average ACH sale amount in cents for this entity (max 10 characters).
annual_ach_volume integer Approximate annual ACH sales expected to be processed in cents by this entity (max 10 characters).
refund_policy string Please select one of the following values: NO_REFUNDS, MERCHANDISE_EXCHANGE_ONLY, WITHIN_30_DAYS, OTHER.
card_volume_distribution object The distribution of the entity's credit card volume (See below for a full list of the child attributes).
volume_distribution_by_business_type object The distribution of the entity's credit card volume by business type (See below for a full list of the child attributes).

Address Object Arguments

Information related to where the entity is located.

Field Type Description
line1 string First line of the address (max 35 characters).
line2 string Second line of the address (max 35 characters).
city string City (max 20 characters).
region string 2-letter State code (50 US states only, no territories).
postal_code string Zip or Postal code (max 7 characters).
country string 3-Letter Country code.

Incorporation Date Arguments

Information related to when the entity was registered.

Field Type Description
day integer Day entity was incorporated (between 1 and 31).
month integer Month entity was incorporated (between 1 and 12).
year integer Year entity was incorporated (4-digit).

DOB Object Date Arguments

The date of birth of the Control Person.

Field Type Description
day integer Day of birth (between 1 and 31).
month integer Month of birth (between 1 and 12).
year integer Year of birth (4-digit).

Card Volume Distribution Arguments

Information related to the card volume of the business. The total sum of card_volume_distribution must be 100%.

Field Type Description
card_present_percentage integer The percentage of the user's business that is card present (between 0 and 100).
ecommerce_present_percentage integer The percentage of the user's business that is ecommerce (between 0 and 100).
mail_order_telephone_order_percentage integer The percentage of the user's business that is mail order or telephone order (between 0 and 100).

Volume Distribution by Business Type Arguments

Information related to transaction volume of the business. The total sum of volume_distribution_by_business_type must be 100%.

Field Type Description
business_to_business_volume_percentage integer The percentage of the user's volume that's business to business (between 0 and 100).
business_to_consumer_volume_percentage integer The percentage of the user's volume that's business to consumer (between 0 and 100).
other_volume_percentage integer The percentage of the user's volume that is not represented by the previous fields (between 0 and 100).

Displaying Processing Fees

It's your responsibility to display the fees applicable to your merchants in a clear and transparent manner before they enter the Hosted Onboarding experience.

When creating an onboarding_form, we require a URL that links to a public page that displays the fees you apply to merchants.

Merchants must be able to view this page at the final step of your onboarding experience should they want to confirm their applicable fees. As part of your onboarding experience, we require you to share this fee display page with us to ensure that the fees displayed match the fees configured in your Fee Profile.

Get an Onboarding Form URL

You can use the hosted_onboarding_link API to create a link that can return users to where they left off completing their Finix Onboarding Form.

Copy
Copied
curl -X POST \
  https://finix.sandbox-payments-api.com/onboarding_forms/obf_bXQj8iSgYwXf432yJcWbKv/links \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version:2022-02-01' \
  -d '{
  "terms_of_service_url":"https://www.finix.com/terms-and-policies",
  "return_url":"https://www.finix.com/docs",
  "fee_details_url":"https://www.finix.com/docs",
  "expired_session_url":"https://www.finix.com/",
  "expiration_in_minutes":30 
}'

HTTP Request

POST https://finix.sandbox-payments-api.com/onboarding_forms/{onboarding_form_id}/links

Request Arguments

Field Type Description
terms_of_service_url string, optional Your Terms of Service URL. The URL is provided to users for consent along with Finix's Terms of Service.
fee_details_url string, required The URL of the page where you display the fees related to processing payments (for more info, see Displaying Processing Fees).
return_url string, required The URL users get sent to after completing the onboarding flow.
expired_session_url string, required The URL users get sent to if the bearer token expires.
expiration_in_minutes integer, optional How long (in minutes) the link is valid for.

Example Response

Copy
Copied
{
  "expires_at" : "2022-07-11T22:39:55.469Z",
  "link_url" : "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_bXQj8iSgYwXf432yJcWbKv&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfYlhRajhpU2dZd1hmNDMyeUpjV2JLdiIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS9kb2NzIiwiZXhwaXJlZF9zZXNzaW9uX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS8iLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL2RvY3MiLCJleHAiOjE2NTc1NzkxOTUsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNjU3NTc3Mzk1LCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL3Rlcm1zLWFuZC1wb2xpY2llcyJ9.uQvwqhOxSmpX4zMSVn891ClNB_cWHmXhLfyOzRiKRoyn7VAqVOWrO8dJiY-OvN4venPWnPOxM0r3NiIyfgQv6g"
}

Response Arguments

Field Type Description
link_url string The URL of the user's Finix Onboarding Form. Users can use the link_url to return to the form at any time.
expires_at timestamp A UTC timestamp detailing when the onboarding form expires and will no longer be available via link_url. To generate a new link to the same form, see Get an Onboarding Form URL.

Customizing Your Finix Onboarding Form

You can customize the Finix Onboarding Form that you send users to with your logo and a primary color.

To customize your Finix Onboarding Form:

  1. Click Dashboard Configurations under Settings .
  2. Enter the URL that has the image you want to use as your logo.
  3. Choose your banner color in the Sidebar Background Color color tool.

If you don't customize your forms they'll default to a dark blue banner with no logo. We recommend configuring your branding before introducing the onboarding forms to your users.

Finix Onboarding Form