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:
-
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.
- Users get prompted to enter their business information, bank account, ownership profile, and underwriting-related data into Finix’s Onboarding Form.
-
The entire form can also be prefilled with the user's information while creating their
onboarding_form
. - 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.
- 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
.
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
{
"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:
|
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.
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
{
"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:
- Click Dashboard Configurations under Settings .
- Enter the URL that has the image you want to use as your logo.
- 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.