Onboarding Forms

Save time onboarding sellers by using our Onboarding Forms.

Finix’s Onboarding Forms provide an easy way to onboard sellers onto your platform using a web form built and hosted by Finix.

Compared to building your own onboarding experience from the ground up, using our Onboarding Forms has several advantages:

  • Save development time using our pre-built forms instead of building an onboarding flow from scratch.
  • Brand our pre-built forms with your own logo and brand colors.
  • Pre-fill Onboarding Forms for sellers so they can save time and start processing payments ASAP.
  • Save progress so sellers can finish forms at their leisure.
  • Finix handles changes and updates, so there's no need to worry about updating forms.

Review the following to see the form in action:

Supported Countries

  • United States
  • Canada

Branding

We recommend customizing the form with your branding before sharing it with your sellers. By default, the Onboarding Form has a dark blue banner with no logo.

For details on how to customize Onboarding Forms with your logo and brand colors, see White Labeling and Customizing Finix Dashboards.

Finix Onboarding Form

How Onboarding Forms Work

Using our forms, the onboarding flow gets simplified into 3 key steps:

  1. Create an onboarding_form for the seller.
  2. Ask the seller to complete the Onboarding Form using the link that gets created.
  3. Fetch the resources that get created and start processing payments. The resources that get created include an Identity , Merchant , and Payment Instrument .

Creating Onboarding Forms using the Finix Dashboard

To create Onboarding Forms using the Finix Dashboard, click Merchants > Onboarding Forms.

Click Create New Form and follow the steps on-screen to generate a URL to an Onboarding Form. You can share this URL with your seller, so they can complete the form and provide the information that's needed to process payments and get onboarded.

Once submitted, the seller's information gets reviewed by Finix's underwriting team.

Creating Onboarding Forms using the Finix API

This diagram shows what the end-to-end onboarding flow looks like using our API:

onboarding flow diagram

Step 1: Create a Finix Onboarding Form

To onboard a seller with Finix built forms, first create an onboarding_form.

An onboarding_form represents the attempt to board a seller using Finix's Onboarding Forms. You use this onboarding_form resource to create the links that sellers will use to fill out the form.

Include the onboarding_link_details to automatically return an onboarding link. You can also manually create Onboarding Form links as needed.

  • Sellers get redirected to the return_url when they complete the Onboarding Form.
  • If time expires, sellers get redirected to the expired_session_url .
USACAN
Copy
Copied
curl https://finix.sandbox-payments-api.com/onboarding_forms \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "onboarding_data": {
      "country": "USA",
      "entity": {
        "title": "CEO",
        "first_name": "John",
        "last_name": "Smith",
        "email": "owner@democompany.com",
        "business_name": "Demo Company, LLC",
        "business_type": "CORPORATION",
        "doing_business_as": "Demo Company",
        "phone": "1234567890",
        "business_phone": "1234567890",
        "personal_address": {
          "city": "Seattle",
          "country": "USA",
          "line1": "123 Boren Ave",
          "postal_code": "98040",
          "region": "WA"
        },
        "business_address": {
          "city": "Bellevue",
          "country": "USA",
          "line1": "123 Bellevue Way",
          "postal_code": "98039",
          "region": "WA"
        },
        "dob": {
          "day": 13,
          "month": 4,
          "year": 1982
        },
        "incorporation_date": {
          "day": 9,
          "month": 3,
          "year": 2018
        },
        "mcc": "4900",
        "url": "www.democompany.com",
        "ownership_type": "PRIVATE",
        "default_statement_descriptor": "DEMOCOMPANY",
        "max_transaction_amount": 100000,
        "annual_card_volume": 1000000,
        "principal_percentage_ownership": 75,
        "tax_id": "123456789",
        "business_tax_id": "123456789",
        "has_accepted_credit_cards_previously": false
      },
      "additional_underwriting_data": {
        "refund_policy": "NO_REFUNDS",
        "card_volume_distribution": {
          "ecommerce_percentage": 100,
          "card_present_percentage": 0,
          "mail_order_telephone_order_percentage": 0
        },
        "average_ach_transfer_amount": 20000000,
        "average_card_transfer_amount": 20000,
        "annual_ach_volume": 20000000,
        "business_description": "CONSUMER",
        "volume_distribution_by_business_type": {
          "other_volume_percentage": 0,
          "person_to_person_volume_percentage": 0,
          "business_to_business_volume_percentage": 90,
          "business_to_consumer_volume_percentage": 10,
          "consumer_to_consumer_volume_percentage": 0
        }
      },
      "associated_entities": [
        {
          "title": "CFO",
          "first_name": "Numbers",
          "last_name": "McGee",
          "email": "numbers@democompany.com",
          "phone": "123456789",
          "personal_address": {
            "city": "Bellevue",
            "country": "USA",
            "line1": "4848 84th St",
            "postal_code": "98032",
            "region": "WA"
          },
          "dob": {
            "day": 13,
            "month": 4,
            "year": 1985
          },
          "principal_percentage_ownership": 25,
          "tax_id": "123456789"
        }
      ],
      "payment_instruments": {
        "account_number": "123456789",
        "account_type": "CHECKING",
        "bank_code": "123456789",
        "country": "USA",
        "currency": "USD",
        "name": "JOE BANKER",
        "type": "BANK_ACCOUNT"
      },
      "max_transaction_amount": 100000
    },
    "merchant_processors": [
      {
        "processor": "LITLE_V1"
      }
    ],
    "onboarding_link_details": {
      "return_url": "https://www.democompany.com/home",
      "expired_session_url": "https://www.democompany.com/login",
      "terms_of_service_url": "https://www.democompany.com/ToS",
      "fee_details_url": "https://www.democompany.com/fee_details",
      "expiration_in_minutes": 10080
    }
  }'
Copy
Copied
curl https://finix.sandbox-payments-api.com/onboarding_forms \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "onboarding_data": {
      "country": "CAN",
      "entity": {
        "title": "CEO",
        "first_name": "John",
        "last_name": "Smith",
        "email": "owner@democompany.com",
        "business_name": "Demo Company, LLC",
        "business_type": "CORPORATION",
        "doing_business_as": "Demo Company",
        "phone": "1234567890",
        "business_phone": "1234567890",
        "personal_address": {
          "city": "Toronto",
          "country": "CAN",
          "line1": "123 Main St",
          "postal_code": "A1A 2B2",
          "region": "ON"
        },
        "business_address": {
          "city": "Toronto",
          "country": "CAN",
          "line1": "456 Main St",
          "postal_code": "A1A 2B2",
          "region": "ON"
        },
        "dob": {
          "day": 13,
          "month": 4,
          "year": 1982
        },
        "incorporation_date": {
          "day": 9,
          "month": 3,
          "year": 2018
        },
        "mcc": "4900",
        "url": "www.democompany.com",
        "ownership_type": "PRIVATE",
        "default_statement_descriptor": "DEMOCOMPANY",
        "max_transaction_amount": 100000,
        "annual_card_volume": 1000000,
        "principal_percentage_ownership": 75,
        "tax_id": "123456789",
        "business_tax_id": "123456789",
        "has_accepted_credit_cards_previously": false
      },
      "additional_underwriting_data": {
        "refund_policy": "NO_REFUNDS",
        "card_volume_distribution": {
          "ecommerce_percentage": 100,
          "card_present_percentage": 0,
          "mail_order_telephone_order_percentage": 0
        },
        "average_ach_transfer_amount": 20000000,
        "average_card_transfer_amount": 20000,
        "annual_ach_volume": 20000000,
        "business_description": "CONSUMER",
        "volume_distribution_by_business_type": {
          "other_volume_percentage": 0,
          "person_to_person_volume_percentage": 0,
          "business_to_business_volume_percentage": 90,
          "business_to_consumer_volume_percentage": 10,
          "consumer_to_consumer_volume_percentage": 0
        }
      },
      "associated_entities": [
        {
          "title": "CFO",
          "first_name": "Numbers",
          "last_name": "McGee",
          "email": "numbers@democompany.com",
          "phone": "123456789",
          "personal_address": {
            "city": "Vancouver",
            "country": "CAN",
            "line1": "786 Main St",
            "postal_code": "H1H 2I2",
            "region": "BC"
          },
          "dob": {
            "day": 13,
            "month": 4,
            "year": 1985
          },
          "principal_percentage_ownership": 25,
          "tax_id": "123456789"
        }
      ],
      "payment_instruments": {
        "account_number": "123123123",
        "account_type": "BUSINESS_CHECKING",
        "country": "CAN",
        "currency": "CAD",
        "institution_number": "123",
        "name": "JOE BANKER",
        "transit_number": "12345",
        "type": "BANK_ACCOUNT"
      },
      "max_transaction_amount": 100000
    },
    "merchant_processors": [
      {
        "processor": "LITLE_V1"
      }
    ],
    "onboarding_link_details": {
      "return_url": "https://www.democompany.com/home",
      "expired_session_url": "https://www.democompany.com/login",
      "terms_of_service_url": "https://www.democompany.com/ToS",
      "fee_details_url": "https://www.democompany.com/fee_details",
      "expiration_in_minutes": 10080
    }
  }'
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 201 and the onboarding_form resource.

USACAN
Copy
Copied
{
  "id": "obf_6QyNWTcE7LeyBsGamKCxCS",
  "onboarding_data": {
    "entity": {
      "title": "CEO",
      "first_name": "John",
      "last_name": "Smith",
      "email": "owner@democompany.com",
      "business_name": "Demo Company, LLC",
      "business_type": "CORPORATION",
      "doing_business_as": "Demo Company",
      "phone": "1234567890",
      "business_phone": "1234567890",
      "mcc": "4900",
      "url": "www.democompany.com",
      "ownership_type": "PRIVATE",
      "default_statement_descriptor": "DEMOCOMPANY",
      "max_transaction_amount": 100000,
      "annual_card_volume": "1000000",
      "principal_percentage_ownership": "75",
      "tax_id": "*****6789",
      "business_tax_id": "*****6789",
      "has_accepted_credit_cards_previously": false,
      "personal_address": {
        "line1": "123 Boren Ave",
        "city": "Seattle",
        "region": "WA",
        "postal_code": "98040",
        "country": "USA"
      },
      "business_address": {
        "line1": "123 Bellevue Way",
        "city": "Bellevue",
        "region": "WA",
        "postal_code": "98039",
        "country": "USA"
      },
      "dob": {
        "day": 13,
        "month": 4,
        "year": 1982
      },
      "incorporation_date": {
        "day": 9,
        "month": 3,
        "year": 2018
      }
    },
    "associated_entities": [
      {
        "title": "CFO",
        "first_name": "Numbers",
        "last_name": "McGee",
        "email": "numbers@democompany.com",
        "phone": "123456789",
        "personal_address": {
          "line1": "4848 84th St",
          "city": "Bellevue",
          "region": "WA",
          "postal_code": "98032",
          "country": "USA"
        },
        "dob": {
          "day": 13,
          "month": 4,
          "year": 1985
        },
        "principal_percentage_ownership": 25,
        "tax_id": "*****6789"
      }
    ],
    "payment_instruments": {
      "name": "JOE BANKER",
      "bank_code": "123456789",
      "account_number": "*****6789",
      "account_type": "CHECKING",
      "type": "BANK_ACCOUNT",
      "country": "USA",
      "currency": "USD"
    },
    "additional_underwriting_data": {
      "refund_policy": "NO_REFUNDS",
      "average_ach_transfer_amount": 20000000,
      "average_card_transfer_amount": 20000,
      "merchant_agreement_ip_address": null,
      "merchant_agreement_accepted": null,
      "merchant_agreement_timestamp": null,
      "merchant_agreement_user_agent": null,
      "credit_check_timestamp": null,
      "credit_check_user_agent": null,
      "annual_ach_volume": 20000000,
      "business_description": "CONSUMER",
      "volume_distribution_by_business_type": {
        "other_volume_percentage": 0,
        "person_to_person_volume_percentage": 0,
        "business_to_business_volume_percentage": 90,
        "business_to_consumer_volume_percentage": 10,
        "consumer_to_consumer_volume_percentage": 0
      },
      "card_volume_distribution": {
        "ecommerce_percentage": 100,
        "card_present_percentage": 0,
        "mail_order_telephone_order_percentage": 0
      },
      "amex_marketing_consent": null
    },
    "max_transaction_amount": 100000,
    "country": "USA",
    "associated_files": []
  },
  "merchant_processors": [
    {
      "processor": "LITLE_V1"
    }
  ],
  "onboarding_link_details": {
    "return_url": "https://www.democompany.com/home",
    "expired_session_url": "https://www.democompany.com/login",
    "fee_details_url": "https://www.democompany.com/fee_details",
    "terms_of_service_url": "https://www.democompany.com/ToS",
    "expiration_in_minutes": 10080
  },
  "onboarding_link": {
    "expires_at": "2024-03-06T16:34:03.875Z",
    "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_6QyNWTcE7LeyBsGamKCxCS&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfNlF5TldUY0U3TGV5QnNHYW1LQ3hDUyIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6bnVsbCwiaXNzIjoiaHR0cHM6Ly93d3cuZmluaXguY29tIiwicmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9ob21lIiwiZXhwIjoxNzA5NzQyODQzLCJhcHBsaWNhdGlvbl9pZCI6IkFQZ1BEUXJMRDUyVFl2cWF6akhKSmNoTSIsImlhdCI6MTcwOTEzODA0MywibWVyY2hhbnRfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwLCJ0ZXJtc19vZl9zZXJ2aWNlX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9Ub1MifQ.mW2SZZMokW2ANlDqdcJPCja-5UVGhk_hbv8iE0LS0SF16gvOiqNg6pFjipXI4i81DxoYUUkSlbAPxIrUIambXQ"
  },
  "status": "IN_PROGRESS",
  "identity_id": null,
  "application_id": "APgPDQrLD52TYvqazjHJJchM",
  "created_at": "2024-02-28T16:34:03.865229Z",
  "updated_at": "2024-02-28T16:34:03.865229Z",
  "tags": {}
}
Copy
Copied
{
  "id": "obf_i9FRWWXc1xmuoMpDz6XM1g",
  "onboarding_data": {
    "entity": {
      "title": "CEO",
      "first_name": "John",
      "last_name": "Smith",
      "email": "owner@democompany.com",
      "business_name": "Demo Company, LLC",
      "business_type": "CORPORATION",
      "doing_business_as": "Demo Company",
      "phone": "1234567890",
      "business_phone": "1234567890",
      "mcc": "4900",
      "url": "www.democompany.com",
      "ownership_type": "PRIVATE",
      "default_statement_descriptor": "DEMOCOMPANY",
      "max_transaction_amount": 100000,
      "annual_card_volume": "1000000",
      "principal_percentage_ownership": "75",
      "tax_id": "*****6789",
      "business_tax_id": "*****6789",
      "has_accepted_credit_cards_previously": false,
      "personal_address": {
        "line1": "123 Main St",
        "city": "Toronto",
        "region": "ON",
        "postal_code": "A1A 2B2",
        "country": "CAN"
      },
      "business_address": {
        "line1": "456 Main St",
        "city": "Toronto",
        "region": "ON",
        "postal_code": "A1A 2B2",
        "country": "CAN"
      },
      "dob": {
        "day": 13,
        "month": 4,
        "year": 1982
      },
      "incorporation_date": {
        "day": 9,
        "month": 3,
        "year": 2018
      }
    },
    "associated_entities": [
      {
        "title": "CFO",
        "first_name": "Numbers",
        "last_name": "McGee",
        "email": "numbers@democompany.com",
        "phone": "123456789",
        "personal_address": {
          "line1": "786 Main St",
          "city": "Vancouver",
          "region": "BC",
          "postal_code": "H1H 2I2",
          "country": "CAN"
        },
        "dob": {
          "day": 13,
          "month": 4,
          "year": 1985
        },
        "principal_percentage_ownership": 25,
        "tax_id": "*****6789"
      }
    ],
    "payment_instruments": {
      "name": "JOE BANKER",
      "account_number": "*****3123",
      "account_type": "BUSINESS_CHECKING",
      "type": "BANK_ACCOUNT",
      "country": "CAN",
      "currency": "CAD",
      "transit_number": "12345",
      "institution_number": "123"
    },
    "additional_underwriting_data": {
      "refund_policy": "NO_REFUNDS",
      "average_ach_transfer_amount": 20000000,
      "average_card_transfer_amount": 20000,
      "merchant_agreement_ip_address": null,
      "merchant_agreement_accepted": null,
      "merchant_agreement_timestamp": null,
      "merchant_agreement_user_agent": null,
      "credit_check_timestamp": null,
      "credit_check_user_agent": null,
      "annual_ach_volume": 20000000,
      "business_description": "CONSUMER",
      "volume_distribution_by_business_type": {
        "other_volume_percentage": 0,
        "person_to_person_volume_percentage": 0,
        "business_to_business_volume_percentage": 90,
        "business_to_consumer_volume_percentage": 10,
        "consumer_to_consumer_volume_percentage": 0
      },
      "card_volume_distribution": {
        "ecommerce_percentage": 100,
        "card_present_percentage": 0,
        "mail_order_telephone_order_percentage": 0
      },
      "amex_marketing_consent": null
    },
    "max_transaction_amount": 100000,
    "country": "CAN",
    "associated_files": []
  },
  "merchant_processors": [
    {
      "processor": "LITLE_V1"
    }
  ],
  "onboarding_link_details": {
    "return_url": "https://www.democompany.com/home",
    "expired_session_url": "https://www.democompany.com/login",
    "fee_details_url": "https://www.democompany.com/fee_details",
    "terms_of_service_url": "https://www.democompany.com/ToS",
    "expiration_in_minutes": 10080
  },
  "onboarding_link": {
    "expires_at": "2024-03-06T16:36:37.573Z",
    "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_i9FRWWXc1xmuoMpDz6XM1g&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfaTlGUldXWGMxeG11b01wRHo2WE0xZyIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6bnVsbCwiaXNzIjoiaHR0cHM6Ly93d3cuZmluaXguY29tIiwicmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9ob21lIiwiZXhwIjoxNzA5NzQyOTk3LCJhcHBsaWNhdGlvbl9pZCI6IkFQZ1BEUXJMRDUyVFl2cWF6akhKSmNoTSIsImlhdCI6MTcwOTEzODE5NywibWVyY2hhbnRfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwLCJ0ZXJtc19vZl9zZXJ2aWNlX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9Ub1MifQ.-fbBfnwAdH-mNnHhyt-ZBMxijkHTDIEM38yVx2Y88H5IHuRW4ba2v2OIOpRys8-CtqyhL0I9byyDfKxhZ87dmA"
  },
  "status": "IN_PROGRESS",
  "identity_id": null,
  "application_id": "APgPDQrLD52TYvqazjHJJchM",
  "created_at": "2024-02-28T16:36:37.561449Z",
  "updated_at": "2024-02-28T16:36:37.561449Z",
  "tags": {}
}

Next, redirect the seller so they can fill out the Onboarding Form. If you provided onboarding_link_details, the Onboarding Form link you can direct sellers to gets returned in onboarding_link#link_url.

Prefilling Fields

While creating an onboarding_form, if you've already collected some information about your seller, you can prefill fields in the Onboarding Form by including that pre-collected information in your request.

This helps avoid asking your sellers to re-enter information they've already provided, like their email or name.

Displaying Processing Fees

It's important to let your sellers know about any fees they'll be charged in a clear and transparent manner before they enter your onboarding flow.

When creating an onboarding_form, we require a URL to a public page that displays the fees you apply to sellers. Sellers must be able to view this page and it must be included in your onboarding flow so they can confirm their applicable fees.

Additionally, we require you to share this public fee page as part of onboarding and we'll verify the listed fees match the fees configured in your Fee Profile.

Step 2: Redirecting Sellers

With an onboarding_form created, you need to redirect your seller so they can fill out the Onboarding Form. If you provided onboarding_link_details the onboarding link you send your seller 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.

In our Onboarding Form, sellers are prompted to enter their business information, bank account, ownership profile, and underwriting-related data. After the seller agrees to the Finix Terms of Service and submits the Onboarding Form, the data gets submitted to Finix and the seller gets redirected back to the return_url.

An Identity#id gets added as a query parameter as part of this redirect.

  • Here's an example of what the redirect URL can look like: https://www.example.com/handle-onboarding-form?identityId=IDeoSwE888omd6pn73hzLA5a .

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

  • No additional parameters are included when users get directed to the expired_session_url . You'll need to configure the expired_session_url so it directs sellers to the Onboarding Form they were originally finishing.

The Identity#id is the id of the Identity that was created for the seller. You use this Identity#id to retrieve the created Identity resource.

Step 3: Retrieve the Created Resources

A successfully completed Onboarding Form creates a Merchant, the key resource that any onboarded seller needs. A successfully provisioned Merchant is necessary to process payments.

There are three ways you can retrieve the created Merchant:

All approaches require using the Identity#id which gets returned in the redirect URL and webhook events.

List the Merchants

To retrieve the Merchant, query our API for a list of Merchants associated with the Identity#id.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/ID8yUjXJv5oNW2e3BPU1u2pK/merchants \
  -H 'Finix-Version: 2022-02-01' \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

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

Copy
Copied
{
  "_embedded": {
    "merchants": [
      {
        "id": "MUhJWbFxDL1EFrieFDPVHMAM",
        "created_at": "2023-01-01T10:50:48.53Z",
        "updated_at": "2023-01-01T10:51:02.90Z",
        "application": "APgPDQrLD52TYvqazjHJJchM",
        "card_cvv_required": false,
        "card_expiration_date_required": true,
        "convenience_charges_enabled": false,
        "creating_transfer_from_report_enabled": true,
        "default_partial_authorization_enabled": false,
        "disbursements_ach_pull_enabled": false,
        "disbursements_ach_push_enabled": false,
        "disbursements_card_pull_enabled": false,
        "disbursements_card_push_enabled": false,
        "fee_ready_to_settle_upon": "RECONCILIATION",
        "gateway": null,
        "gross_settlement_enabled": false,
        "identity": "ID8yUjXJv5oNW2e3BPU1u2pK",
        "level_two_level_three_data_enabled": false,
        "mcc": null,
        "merchant_name": "dwayne lbc",
        "merchant_profile": "MPdyRZgBRwEbdf2Qcm3xqAY1",
        "mid": "FNX3zhtdAjuJLwMk9ASxnyuUB",
        "onboarding_state": "APPROVED",
        "processing_enabled": true,
        "processor": "DUMMY_V1",
        "processor_details": {
          "mid": "FNX3zhtdAjuJLwMk9ASxnyuUB",
          "api_key": "secretValue"
        },
        "ready_to_settle_upon": "RECONCILIATION",
        "rent_surcharges_enabled": false,
        "settlement_enabled": true,
        "settlement_funding_identifier": "UNSET",
        "surcharges_enabled": false,
        "tags": {
          "test_key_100": "test_val_100"
        },
        "verification": "VId1MRt94w1xdzRU7zFRAL9W",
        "_links": {
          "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUhJWbFxDL1EFrieFDPVHMAM"
          },
          "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID8yUjXJv5oNW2e3BPU1u2pK"
          },
          "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUhJWbFxDL1EFrieFDPVHMAM/verifications"
          },
          "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPdyRZgBRwEbdf2Qcm3xqAY1"
          },
          "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
          },
          "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VId1MRt94w1xdzRU7zFRAL9W"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID8yUjXJv5oNW2e3BPU1u2pK/merchants?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 1
  }
}

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

Onboarding Form Updated Webhook

We send an entity = onboarding_form, type = updated webhook event when the onboarding_form gets saved or submitted by the seller. Use the identity_id in the webhook to retrieve the PROVISIONING Merchant.

Copy
Copied
{
  "type": "updated",
  "entity": "onboarding_form",
  "occurred_at": "2022-12-12T21:37:44.385255",
  "_embedded": {
    "onboarding_forms": [
      {
        "id": "obf_7EMbv4C2bCvzFkVFwDWnEo",
        "onboarding_data": {
          "allowed_countries": ["USA", "CAN"],
          "entity": {
            "title": "CEO",
            "first_name": "John",
            "last_name": "Smith",
            "email": "john@example.com",
            "business_name": "Finix Flowers",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "doing_business_as": "Finix Flowers",
            "phone": "5558675309",
            "business_phone": "5558675309",
            "mcc": "4900",
            "url": "example.com",
            "ownership_type": "PRIVATE",
            "default_statement_descriptor": "FNX",
            "max_transaction_amount": 100000,
            "annual_card_volume": "10000000",
            "principal_percentage_ownership": "100",
            "tax_id": "*****6789",
            "business_tax_id": "*****6890",
            "personal_address": {
              "line1": "631 Howard St.",
              "city": "San Francisco",
              "region": "CA",
              "postal_code": "94105",
              "country": "USA"
            },
            "business_address": {
              "line1": "631 Howard St.",
              "city": "San Francisco",
              "region": "CA",
              "postal_code": "94105",
              "country": "USA"
            },
            "dob": {
              "day": 1,
              "month": 1,
              "year": 1981
            },
            "incorporation_date": {
              "day": 1,
              "month": 1,
              "year": 2007
            }
          },
          "payment_instruments": {
            "name": "John Smith",
            "bank_code": "123456789",
            "account_number": "*****6789",
            "account_type": "CHECKING",
            "type": "BANK_ACCOUNT"
          },
          "additional_underwriting_data": {
            "refund_policy": "NO_REFUNDS",
            "average_ach_transfer_amount": 0,
            "average_card_transfer_amount": 10000,
            "merchant_agreement_ip_address": "4.14.107.114",
            "merchant_agreement_accepted": true,
            "merchant_agreement_timestamp": "2022-11-16T00:53:45.228537Z",
            "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36",
            "annual_ach_volume": 0,
            "business_description": "Flowers",
            "volume_distribution_by_business_type": {
              "other_volume_percentage": 0,
              "business_to_business_volume_percentage": 100,
              "business_to_consumer_volume_percentage": 0
            },
            "card_volume_distribution": {
              "ecommerce_percentage": 100,
              "card_present_percentage": 0,
              "mail_order_telephone_order_percentage": 0
            }
          },
          "max_transaction_amount": 100000
        },
        "merchant_processors": [
          {
            "processor": "DUMMY_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",
          "fee_details_url": "https://www.finix.com/docs",
          "terms_of_service_url": "https://www.finix.com/terms-and-policies",
          "expiration_in_minutes": 10080
        },
        "status": "COMPLETED",
        "identity_id": "ID8XfQPGnxM2oviYgdzjMWsn",
        "application_id": "APgPDQrLD52TYvqazjHJJchM",
        "created_at": "2022-11-16T00:50:23.787426Z",
        "updated_at": "2022-11-16T00:53:46.124008Z",
        "tags": {
          "seller": "Finix Flowers"
        }
      }
    ]
  }
}

Merchant Created Webhook

We send an entity = merchant, type = created webhook event when a Merchant gets created. The webhook contains the Merchant that was created. You can confirm this by matching the Identity in the webhook event with the Identity#id 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": "4900",
        "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 details and underwriting the seller. If the Merchant is rejected, you'll need to follow up and handle why the seller was rejected.

Restart an Onboarding Form Session

Ideally, your seller completes an Onboarding Form session immediately, but there may be some sellers 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 to help a seller pickup where they left off in the Onboarding Form.

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

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 seller to the link_url so they can complete onboarding. Once completed, retrieve the Merchant resource that was created for the seller.

Sellers are usually approved within minutes and can start processing payments as soon as they complete onboarding.

Rejected Merchants

If a seller is rejected, the state of the Merchant becomes REJECTED, and you'll need to appeal the onboarding rejection.

Our Onboarding Forms only support initial information gathering. For details on how to handle onboarding rejections see Onboarding Rejections.