Onboarding Forms

Finix offers and hosts pre-built onboarding forms that you can use to collect onboarding and identity verification information from your users.

Related Guides: Onboarding, Onboarding Forms.

Create an 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.

Only ROLE_PARTNER credentials can be used to create an onboarding_form.

Request

Request Body schema: application/json

required	object The prefilled information of the user that's being onboarded. For more information, see Prefilling Fields.
required	Array of objects An array of objects with the processors and gateways users will be onboarded to.
required	object The information of the initial onboarding link. This is only provided when creating an `onboarding_form`.
	object or null Include up to 50 `key: value` pairs to annotate requests with custom metadata. Maximum character length for individual `keys` is 40. Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)

Responses

200

A single onboarding_form object.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

post/onboarding_forms

Request samples

curl

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

Response samples

application/json

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

Fetch an Onboarding Form

Retrieve the details of an onboarding_form.

Request

path Parameters

onboarding_form_id

required

string

The id of the onboarding_form.

header Parameters

string

Default: application/hal+json

Responses

200

A single onboarding_form object.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

get/onboarding_forms/{onboarding_form_id}

Request samples

curl

curl "https://finix.sandbox-payments-api.com/onboarding_forms/obf_jJHv5y5xCTVsga8FFim9X9" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X GET

Response samples

application/json

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

Create an Onboarding Form Link

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

Request

path Parameters

onboarding_form_id

required

string

The ID of the onboarding_form resource.

header Parameters

string

Default: application/hal+json

Request Body schema: application/json

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

Responses

200

A link for users to return to their onboarding_form at any time.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

post/onboarding_forms/{onboarding_form_id}/links

Request samples

curl

curl "https://finix.sandbox-payments-api.com/onboarding_forms/obf_jJHv5y5xCTVsga8FFim9X9/links" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '
  {
    "expiration_in_minutes": 30,
    "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"
  }'

Response samples

application/json

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