Hosted Onboarding Form

Finix’s Hosted Onboarding Form is a pre-built, web form hosted by Finix that takes care of the onboarding process. The hosted page collects onboarding and identity verification information to help you provision merchants.

With our Hosted 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.

Finix Onboarding Form

The Hosted Form saves your user's progress so they can pick up where they left off if they abandon the hosted onboarding session.

attention

The APIs to create Hosted Onboarding Forms are only available for Finix Flex customers. If you have additional questions, please reach out to your Finix point of contact.

Hosted Onboarding Flow

This diagram show what the end to end hosted onboarding flow looks like:

hosted onboarding flow diagram

This Flow is reduced down to 3 key steps:

  1. Create an onboarding_form for the user.
  2. Redirect the user to the link that gets created with the Hosted Onboarding form.
  3. Retrieve the resulting Identity, merchant, and payment instrument that get created to start processing payments.

Step 1: Create a Finix Onboarding Form

To start the hosted onboarding flow, create an onboarding_form. An onboarding_form represents the attempt to board a user with our hosted onboarding form. You use this onboarding_form resource to generate the links that directs your user to complete the form.

Provide the onboarding_link_details to automatically return an onboarding link. You can also manually create onboarding form links as needed.

  • Users get redirected to the return_url when they complete the onboarding form.
  • If time expires, users get redirected to the expired_session_url .
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.example.com/finix-handlers/onboarding-return",
        "expired_session_url": "https://www.example.com/finix-handlers/onboarding-expires",
        "terms_of_service_url": "https://www.finix.com/terms-and-policies",
        "fee_details_url": "https://www.finix.com/docs",
        "expiration_in_minutes": "30"
    }
}'
attention

Your Finix point of contact will provide the processor to use. If you don't know your Finix point of contact, email Finix Support.

A successful response returns the onboarding_form.

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" : { }
}

Next, redirect the user to complete the onboarding form. If you provided onboarding_link_details the onboarding form link you can send your user to is returned in onboarding_link.link_url.

Prefilling Fields

While creating an onboarding_form, if you've already collected some of the information about your user, you can prefill the fields in your request.

This helps avoid asking your user to re-enter information they've already provided like names or addresses.

Displaying Processing Fees

It's your responsibility to display the fees applicable to your sellers 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 sellers.

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

Step 2: Redirecting Users

With onboarding_form created, you need to redirect the user to the Finix Hosted Form. If you provided onboarding_link_details the onboard link to send your user to is returned in onboarding_link.link_url. Otherwise, create an onboarding form link.

We recommend creating the link in a new tab or window.

On Finix's hosted page, sellers will be prompted to enter their business information, bank account, ownership profile, and underwriting-related data. 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 the return_url.

An identityId gets added as a query parameter as part of the redirect. Here's an example of what a redirect url can look like: https://www.example.com/handle-onboarding-form?identityId=IDeoSwE888omd6pn73hzLA5a.

If a user session expires, they get redirected to the URL set in expired_session_url.

  • No additional parameters are included when the user gets directed to the expired_session_url URL. You'll need to configure the expired_session_url URL to redirect the user to the onboarding form they were originally finishing.

The identityId is the id of the Identity that was created for the user. You use this to retrieve the created resources .

Step 3: Retrieve the Created Resources

A successfully complete hosted onboarding form creates a merchant, the key resource that any onboarded user needs. A successfully provisioned merchant is necessary to process payments.

There are two ways you can retrieve the created merchant:

  • List the merchants on the Identity ID.
  • Listen for an entity = merchant , type = created webhook event.

Both approaches require using the Identity ID which gets returned in the redirect URL.

List the Merchants

To retrieve the merchant, query the list of merchants for the Identity.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDeoSwE888omd6pn73hzLA5a/merchants \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

This returns a list of every merchant associated with the Identity.

Copy
Copied
{
  "_embedded":{
    "merchants":[
      {
        "id":"MUoBGzwPdFxb397BKM3bHUvf",
        "onboarding_state":"PROVISIONING",
        ...
      }
    ]
  }
  "_links" : {...},
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 0
  }
}

The newly created merchant will have an initial onboarding_state of PROVISIONING, which indicates Finix is currently verifying and underwriting the merchant. You'll receive a webhook once the merchant is approved for processing.

Merchant Created Webhook

We send an entity = merchant, type = created webhook event when a merchant gets created. The webhook contains the merchant that got created. You can confirm this by matching the Identity in the webhook event with the identityId you received in the redirect URL.

Copy
Copied
{
    "type":"create",
    "entity":"merchant",
    "occured_at":"2021-11-14T19:20:29.48Z",
    "_embedded":{
        "merchants":[
            {
                "id" : "MUoBGzwPdFxb397BKM3bHUvf",
                "application" : "APcVnXxyWotD6TGRWV2bRWuD",
                "identity" : "IDeoSwE888omd6pn73hzLA5a",
                "verification" : "VIeZ3gBoRemaDimjp6qS58An",
                "merchant_profile" : "MP9e916zYUTTqHUDe4F9ZQvp",
                "processor" : "DUMMY_V1",
                "processing_enabled" : true,
                "settlement_enabled" : true,
                "gross_settlement_enabled" : false,
                "creating_transfer_from_report_enabled" : false,
                "card_expiration_date_required" : true,
                "card_cvv_required" : false,
                "tags" : {
                    "key_2" : "value_2"
                },
                "mcc" : "0742",
                "mid" : "FNXqtgiZAvNPz44hT67Ai632W",
                "merchant_name" : "Finix Flowers",
                "settlement_funding_identifier" : "UNSET",
                "ready_to_settle_upon" : null,
                "fee_ready_to_settle_upon" : "RECONCILIATION",
                "level_two_level_three_data_enabled" : false,
                "created_at" : "2021-11-14T19:20:29.15Z",
                "updated_at" : "2021-11-14T19:20:29.48Z",
                "onboarding_state" : "PROVISIONING"
            }
        ]
    }
}

The newly created merchant will have an initial onboarding_state of PROVISIONING which means Finix is currently verifying and underwriting the merchant. You'll receive a webhook once the merchant is approved for processing. If the merchant is rejected, you will still need to handle rejected merchants.

Restart a Hosted Onboarding Form Session

Ideally, your user completes a hosted onboarding form session immediately, but there may be some users who step away from the computer, take longer than the specified expiration time, or just forget to complete the form.

Finix saves the progress of users and whatever information they've entered into the onboarding_form. Create a new link on the same onboarding_form resource so the user can pickup where they left off in the Hosted Onboarding Form flow.

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 
}'

A successful response returns 200 and the new link_url.

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"
}

Redirect your user to the link_url so they can complete onboarding. Once completed, you'll retrieve the created resources.

Rejected Merchants

Most of the time, your sellers will be approved and you can start processing payments for them. If they become rejected, the state of the merchant will be REJECTED and you will need to handle the Onboarding Rejections programmatically.

The onboarding form only supports initial information gathering.

Customizing Your Finix Onboarding Form

You can customize the Finix Onboarding Form with your logo and a primary color to better match your branding.

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 sellers.

Finix Onboarding Form