Onboarding Forms

Save time onboarding sellers by using our Onboarding Forms.

Finix's low-code / no-code Onboarding Forms are a fast and flexible way to onboard your sellers. Creating and filling out the form takes just minutes, helping your sellers start processing payments as fast as possible. You can create an Onboarding Form directly from Finix's dashboard, as well as with our APIs.

Finix's Onboarding Forms are purpose-built to make onboarding your sellers as easy as possible:

Low-code / no-code: send an Onboarding Form to your seller immediately, with no technical integrations
White-labeled experience: customize our Onboarding Form with your company's name, logo, and colors
Prefill information: prefill as much information as you want, saving your sellers time
Multi-country support: our Onboarding Forms support boarding both American and Canadian sellers
Save progress: our Onboarding Forms save your sellers' progress, should they need more time
Updating information: our Onboarding Forms are editable, should we request updates during onboarding

Onboarding Form Data

Our Onboarding Forms collect 5 key pieces of data from your sellers:

Seller consent: Finix collects your sellers' consent to both Finix's terms as well as your own terms
Business information: Finix collects data about your seller's business, such as their business name
Owner information: Finix collects data about your seller's control person, such as their personal name
Processing information: Finix collects data about your seller's processing information, such as volumes
Bank account information: Finix collects details about your seller's bank account for their payouts

Managing Onboarding Forms with Finix's Dashboard

Branding Onboarding Forms

Finix lets you brand your Onboarding Forms with your company's name, logo, and colors. To apply your branding, visit Settings > Company > Dashboard Settings > Onboarding Forms on your Finix dashboard. From there, you can set your business name, the logo to use on the form's header, and the color to use for the form's header. You can preview your branding by creating an Onboarding Form in your Sandbox account, or refreshing an existing Onboarding Form.

By default, our Onboarding Form is branded dark blue with no logo. For more information, see White Labeling and Customizing Finix Dashboards.

Creating Onboarding Forms

To create an Onboarding Form with Finix's dashboard, visit Merchants > Onboarding Forms and select Create New Form. From there, we will collect these details to create the form:

Field	Description	Can be preset
Country	Your merchant's business country	No
Merchant Name	Your merchant's business name	No
Link Expiration Time (Days)	Time until your Onboarding Form expires	Yes
Fee URL	Link to webpage explaining your payment processing fees	Yes
Return URL	Link to webpage for your merchants to route after completing their Onboarding Form	Yes
Terms of Service URL	Link to webpage with your Terms of Service	Yes
Expired Session URL	Link to webpage for your merchants to route should the Onboarding Form expire	Yes
Max Transaction Amount (Card)	Maximum transaction amount for your merchant's card payment processing	Yes
Max Transaction Amount (ACH)	Maximum transaction amount for your merchant's ACH payment processing	Yes
Payment Processor	Payment processor for your merchant's processing	No

After creating the Onboarding Form, copy the link to send to your merchant. That's it – your merchant is ready to apply to Finix, with no additional action from your team. Once your merchant submits their Onboarding Form, Finix will create their Merchant account and review their information.

Presetting your Onboarding Form Settings

You can preset most fields required to create an Onboarding Form, making it easy to create forms quickly:

Link Expiration Time (Days)
Fee URL
Return URL
Terms of Service URL
Expired Session URL
Max Transaction Amount (Card)
Max Transaction Amount (ACH)

To apply presets, visit Settings > Company > Dashboard Settings > Onboarding Forms.

Finix automatically presets the Max Transaction Amount fields based on your Finix account's default settings. You can change that amount on a per-Merchant basis when creating an Onboarding Form.

Viewing Onboarding Forms

View all your Onboarding Forms in your Finix dashboard under Merchants > Onboarding Forms. You can view and filter by form status.

Select an Onboarding Form to re-copy the form's link under Actions, as well as view all the information your Merchant has saved to the form while filling it out.

Submitted Onboarding Forms

After your seller submits their Onboarding Form, Finix will mark it Completed and automatically create your seller's Merchant account. After the review process, your seller's Merchant account will be Approved and ready to accept payments. This process often takes just minutes.

Should Finix require more information from your sellers during our review, their Merchant account and Onboarding Form will both move to an Update Requested state. To make the update process as easy as possible, your sellers can use their original Onboarding Form to provide the requested information. After resending your sellers their Onboarding Form link, no additional action is required from your team – Finix will automatically re-review your seller after they submit the requested updates.

Lifecycle event	Onboarding Form	Merchant Account
Onboarding Form Created	`In Progress`	—
Onboarding Form Submitted	`Completed`	`Provisioning`
Merchant Approved	`Completed`	`Approved`
Merchant Rejected	`Completed`	`Rejected`
Updates Requested	`Update Requested`	`Update Requested`
Updates Submitted	`Completed`	`Provisioning`

To learn more about update requests, see Handling Update Requests.

Lifecycle Notifications

Finix offers notifications through both email and the Finix dashboard, making it easy for your team to receive updates as your sellers progress through onboarding. For example, your team can subscribe to receive notifications when your sellers submit their Onboarding Forms and are approved.

To learn more about notifications, see Notifications and Webhooks.

Managing Onboarding Forms with Finix's API

Should you wish to create Onboarding Forms in bulk or directly from your application, you can use the Onboarding Forms API. Finix lets you prefill as many or as few fields as you'd like, and provides a link your seller can use to access the form.

Creating Onboarding Forms

Required Data

Finix requires these fields to create an Onboarding Form:

Field	Type	Description
`expired_session_url`	String	Link to webpage for your merchants to route should the Onboarding Form expire
`fee_details_url`	String	Link to webpage explaining your payment processing fees
`max_transaction_amount`	Integer	Maximum transaction amount for your merchant's card payment processing
`processor`	Enum	Payment processor for your merchant's processing
`return_url`	String	Link to webpage for your merchants to route after completing their Onboarding Form
`terms_of_service_url`	String	Link to webpage with your Terms of Service

Prefilling Fields

Beyond setting the required fields, you may prefill as many other fields as you'd like on the Onboarding Form. This includes the country, as well as all the fields under entity, additional_underwriting_data, associated_entities, and payment_instruments. See an example below of an Onboarding Form request with all fields prefilled, as well as the full list of fields and definitions on the Onboarding Forms API Reference.

Form Link

In the response, Finix provides a link for your seller to access and complete the Onboarding Form (link_url). Should the form's link expire, use the Onboarding Forms Link API to create a new one.

Request Examples

Prefilled FormEmpty FormCanadian Seller

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": "LIMITED_LIABILITY_COMPANY",
            "doing_business_as": "Demo Company",
            "phone": "12223334444",
            "business_phone": "12223334444",
            "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": "https://www.democompany.com",
            "ownership_type": "PRIVATE",
            "default_statement_descriptor": "DEMOCOMPANY",
            "annual_card_volume": 1000000,
            "principal_percentage_ownership": 75,
            "tax_id": "111223333",
            "business_tax_id": "112222222",
            "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": "Jane",
                "last_name": "Doe",
                "email": "jane@democompany.com",
                "phone": "12223334444",
                "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": "111223333"
            }
        ],
        "payment_instruments": {
            "account_number": "783465874368",
            "account_type": "CHECKING",
            "bank_code": "123456789",
            "country": "USA",
            "currency": "USD",
            "name": "JOE BANKER",
            "type": "BANK_ACCOUNT"
        },
        "max_transaction_amount": 100000,
        "ach_max_transaction_amount": 100000
    },
    "merchant_processors": [
        {
            "processor": "DUMMY_V1"
        }
    ],
    "onboarding_link_details": {
        "expiration_in_minutes": 10080,
        "expired_session_url": "https://www.democompany.com/login",
        "fee_details_url": "https://www.democompany.com/fee_details",
        "return_url": "https://www.democompany.com/home",
        "terms_of_service_url": "https://www.democompany.com/ToS"
    }
}'

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": {
          "max_transaction_amount": 10000
      },
      "merchant_processors": [
          {
              "processor": "DUMMY_V1"
          }
      ],
      "onboarding_link_details": {
          "expiration_in_minutes": 10080,
          "expired_session_url": "https://www.democompany.com/login",
          "fee_details_url": "https://www.democompany.com/fee_details",
          "return_url": "https://www.democompany.com/home",
          "terms_of_service_url": "https://www.democompany.com/ToS"
      }
  }'

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",
          "max_transaction_amount": 10000
      },
      "merchant_processors": [
          {
              "processor": "DUMMY_V1"
          }
      ],
      "onboarding_link_details": {
          "expiration_in_minutes": 10080,
          "expired_session_url": "https://www.democompany.com/login",
          "fee_details_url": "https://www.democompany.com/fee_details",
          "return_url": "https://www.democompany.com/home",
          "terms_of_service_url": "https://www.democompany.com/ToS"
      }
  }'

The response will include the form's link (onboarding_link) and expiration timestamp (expires_at), as well as any additional fields set in the request.

Prefilled FormEmpty FormCanadian Seller

Copy

Copied

{
    "id": "obf_242zWmZcV3JGs84CfsX9uS",
    "onboarding_data": {
        "entity": {
            "title": "CEO",
            "first_name": "John",
            "last_name": "Smith",
            "email": "owner@democompany.com",
            "business_name": "Demo Company, LLC",
            "business_type": "LIMITED_LIABILITY_COMPANY",
            "doing_business_as": "Demo Company",
            "phone": "12223334444",
            "business_phone": "12223334444",
            "mcc": "4900",
            "url": "https://www.democompany.com",
            "ownership_type": "PRIVATE",
            "default_statement_descriptor": "DEMOCOMPANY",
            "annual_card_volume": "1000000",
            "principal_percentage_ownership": "75",
            "tax_id": "*****3333",
            "business_tax_id": "*****2222",
            "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": "Jane",
                "last_name": "Doe",
                "email": "jane@democompany.com",
                "phone": "12223334444",
                "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": "*****3333"
            }
        ],
        "payment_instruments": {
            "name": "JOE BANKER",
            "bank_code": "123456789",
            "account_number": "*****4368",
            "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,
        "ach_max_transaction_amount": 100000,
        "country": "USA",
        "associated_files": []
    },
    "merchant_processors": [
        {
            "processor": "DUMMY_V1"
        }
    ],
    "onboarding_link_details": {
        "expiration_in_minutes": 10080,
        "expired_session_url": "https://www.democompany.com/login",
        "fee_details_url": "https://www.democompany.com/fee_details",
        "return_url": "https://www.democompany.com/home",
        "terms_of_service_url": "https://www.democompany.com/ToS"
    },
    "onboarding_link": {
        "expires_at": "2024-09-02T16:27:05.952Z",
        "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_242zWmZcV3JGs84CfsX9uS&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfMjQyeldtWmNWM0pHczg0Q2ZzWDl1UyIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZGVtb2NvbXBhbnkuY29tL2hvbWUiLCJleHAiOjE3MjUyOTQ0MjUsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNzI0Njg5NjI1LCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZGVtb2NvbXBhbnkuY29tL1RvUyJ9.pvlwoKcn_XEYOmoX4blRTdc1Xt5lG4UCsXT6tJkUJ7nnUUKVMBqtfr1KfvfmLPtrBexTbXRrs98P9WFXroHVMg"
    },
    "status": "IN_PROGRESS",
    "identity_id": null,
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "created_at": "2024-08-26T16:27:05.933441Z",
    "updated_at": "2024-08-26T16:27:05.933441Z",
    "tags": {}
}

Copy

Copied

{
    "id": "obf_o3sr8i6FeXrjSu2hXUAz9E",
    "onboarding_data": {
        "max_transaction_amount": 10000,
        "country": "USA",
        "associated_files": []
    },
    "merchant_processors": [
        {
            "processor": "DUMMY_V1"
        }
    ],
    "onboarding_link_details": {
        "expiration_in_minutes": 10080,
        "expired_session_url": "https://www.democompany.com/login",
        "fee_details_url": "https://www.democompany.com/fee_details",
        "return_url": "https://www.democompany.com/home",
        "terms_of_service_url": "https://www.democompany.com/ToS"
    },
    "onboarding_link": {
        "expires_at": "2024-08-15T04:08:51.232Z",
        "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_o3sr8i6FeXrjSu2hXUAz9E&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfbzNzcjhpNkZlWHJqU3UyaFhVQXo5RSIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6bnVsbCwiaXNzIjoiaHR0cHM6Ly93d3cuZmluaXguY29tIiwicmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9ob21lIiwiZXhwIjoxNzIzNjk0OTMxLCJhcHBsaWNhdGlvbl9pZCI6IkFQZ1BEUXJMRDUyVFl2cWF6akhKSmNoTSIsImlhdCI6MTcyMzY5MTMzMSwibWVyY2hhbnRfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDB9.of5WauNDCkSDIHB_Zmex59WSgs0QV96vNUmliOrUCGvuYPklxgxLq2JrK6vCAKu_6B20XWJB-TLYIVEFZWLgzw"
    },
    "status": "IN_PROGRESS",
    "identity_id": null,
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "created_at": "2024-08-15T03:08:51.220078Z",
    "updated_at": "2024-08-15T03:08:51.220078Z",
    "tags": {}
}

Copy

Copied

{
    "id": "obf_vJGR8n4wUsUqFAu5x2ZvcU",
    "onboarding_data": {
        "max_transaction_amount": 10000,
        "country": "CAN",
        "associated_files": []
    },
    "merchant_processors": [
        {
            "processor": "DUMMY_V1"
        }
    ],
    "onboarding_link_details": {
        "expiration_in_minutes": 10080,
        "expired_session_url": "https://www.democompany.com/login",
        "fee_details_url": "https://www.democompany.com/fee_details",
        "return_url": "https://www.democompany.com/home",
        "terms_of_service_url": "https://www.democompany.com/ToS"
    },
    "onboarding_link": {
        "expires_at": "2024-08-15T04:10:35.757Z",
        "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_vJGR8n4wUsUqFAu5x2ZvcU&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfdkpHUjhuNHdVc1VxRkF1NXgyWnZjVSIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6bnVsbCwiaXNzIjoiaHR0cHM6Ly93d3cuZmluaXguY29tIiwicmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9ob21lIiwiZXhwIjoxNzIzNjk1MDM1LCJhcHBsaWNhdGlvbl9pZCI6IkFQZ1BEUXJMRDUyVFl2cWF6akhKSmNoTSIsImlhdCI6MTcyMzY5MTQzNSwibWVyY2hhbnRfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDB9.5euiC-JwIE9QrE9P-koRGnP4RlZ1llpbLyHjm5Gp0IYNeD9hwXeYPi1ZFwgCITLNMfnYMuMBZXS5TpxgNP2gaQ"
    },
    "status": "IN_PROGRESS",
    "identity_id": null,
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "created_at": "2024-08-15T03:10:35.753989Z",
    "updated_at": "2024-08-15T03:10:35.753989Z",
    "tags": {}
}

Fetching an Onboarding Form Link

Should your seller need to re-access their Onboarding Form (for example, if the form expires or your seller needs to update their form), you can create a new link for an existing form. Finix saves your seller's progress as they complete each form step, letting them pick up wherever they left off.

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

The response will have a new link_url your seller can use to re-access the form:

Copy

Copied

{
    "expires_at": "2024-08-22T14:56:03.047Z",
    "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_n4J6QuG6XHoUbZ54Z88v5h&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfbjRKNlF1RzZYSG9VYlo1NFo4OHY1aCIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwMDAwLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZGVtb2NvbXBhbnkuY29tL2hvbWUiLCJleHAiOjE3MjQzMzg1NjMsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNzIzNzMzNzYzLCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZGVtb2NvbXBhbnkuY29tL1RvUyJ9.dIpdz7kN9xr2W5CYSpvJPzGOjl5jvw5wYlQosu5bPLwtvVpeEiB74Aei_lgwLBwo5cU5xymrwy5ssJp-5pLPLw"
}

Submitted Onboarding Forms

Created Resources

After your seller completes their Onboarding Form, Finix automatically creates these API resources for them:

Merchant : your seller will use their Merchant Account to accept payments once it is approved
Verification : this resource puts the Merchant Account into Finix's underwriting system
Identity : this resource contains the data your seller submitted through their Onboarding Form
Payment Instrument : this resource represents the bank account for your seller's payouts

Your seller's Merchant account will transition from PROVISIONING to APPROVED after the underwriting process, letting them accept payments. Should Finix require additional information during the underwriting process, your Merchant's account and the Onboarding Form will both transition into an UPDATE_REQUESTED state. In the event that Finix cannot onboard your seller, their Merchant account will transition to the REJECTED state.

Lifecycle event	Merchant	Verification	Onboarding Form
Onboarding Form Submitted	`PROVISIONING`	`PENDING`	`COMPLETED`
Merchant Approved	`APPROVED`	`SUCCEEDED`	`COMPLETED`
Merchant Rejected	`REJECTED`	`FAILED`	`COMPLETED`
Updates Requested	`UPDATE_REQUESTED`	`FAILED`	`UPDATE_REQUESTED`
Updates Submitted	`PROVISIONING`	`PENDING`	`COMPLETED`

Fetching Resources

Your seller's completed Onboarding Form will have an identity_id, which you can also find appended to the return_url your seller is redirected to:

Return URLCompleted Onboarding Form

Copy

Copied

https://www.demo-company.com/return_url?identityId=IDeoSwE888omd6pn73hzLA5a

Copy

Copied

{
    "id": "obf_osQEKPNUrVT6BFf9ucUH7z",
    "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",
            "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-08-22T03:01:47.445Z",
        "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_osQEKPNUrVT6BFf9ucUH7z&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfb3NRRUtQTlVyVlQ2QkZmOXVjVUg3eiIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6bnVsbCwiaXNzIjoiaHR0cHM6Ly93d3cuZmluaXguY29tIiwicmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9ob21lIiwiZXhwIjoxNzI0Mjk1NzA3LCJhcHBsaWNhdGlvbl9pZCI6IkFQZ1BEUXJMRDUyVFl2cWF6akhKSmNoTSIsImlhdCI6MTcyMzY5MDkwNywibWVyY2hhbnRfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwLCJ0ZXJtc19vZl9zZXJ2aWNlX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9Ub1MifQ.1ePWjKXSSvHF5FJdfMn5dQFgKKnM91ig2urX6kDxiYQD940hKoi4EJVSlQFvcHHTDPeS1Fz84_GGwh7aZC6qLQ"
    },
    "status": "COMPLETED",
    "identity_id": "IDXX",
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "created_at": "2024-08-15T03:01:47.43517Z",
    "updated_at": "2024-08-15T03:01:47.43517Z",
    "tags": {}
}

You can use the identity_id to fetch your seller's Merchant resource:

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 request will return each Merchant for that Identity. Your sellers will typically have only one Merchant account, but may have multiple in some cases (for example, should they need to use multiple payment processors).

Copy

Copied

{
    "_embedded": {
        "merchants": [
            {
                "id": "MUhJWbFxDL1EFrieFDPVHMAM",
                "created_at": "2023-01-01T10:50:48.53Z",
                "updated_at": "2024-03-21T22:37:38.61Z",
                "application": "APgPDQrLD52TYvqazjHJJchM",
                "card_cvv_required": false,
                "card_expiration_date_required": true,
                "card_network_details": null,
                "convenience_charges_enabled": false,
                "country": null,
                "creating_transfer_from_report_enabled": true,
                "currencies": null,
                "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,
                "disbursements_same_day_ach_pull_enabled": false,
                "disbursements_same_day_ach_push_enabled": false,
                "fee_ready_to_settle_upon": "RECONCILIATION",
                "gateway": null,
                "gross_settlement_enabled": false,
                "identity": "ID8yUjXJv5oNW2e3BPU1u2pK",
                "level_two_level_three_data_enabled": false,
                "loan_repayment": null,
                "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",
                "ready_to_settle_upon_delay_alignment": "NONE",
                "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
    }
}

Receiving Webhooks

Finix sends webhooks to update you about your seller's progress throughout the onboarding process. For example, the Merchant Created webhook lets you know when your seller has submitted their Onboarding Form, and the Merchant Updated webhook lets you know when their Merchant account transitions between state.

To learn more about webhooks, see Notifications and Webhooks.

Handling Update Requests

Should Finix request additional information from your seller during the underwriting process, they can use their original Onboarding Form to provide the requested information. Use the Dashboard or API to fetch and send your seller's Onboarding Form link. No additional action is required from your team – Finix will update your seller's API resources and place them back in the underwriting process after they re-submit their Onboarding Form.

To learn more about update requests, see Handling Update Requests.

Next Steps

Next, learn how to handle update requests and subscribe to lifecycle notifications to move your sellers through the onboarding process.