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, Hosted Onboarding Form.

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

	object The prefilled information of the user that's being onboarded. For more information, see Prefilling Fields.
	Array of objects An array of objects with the processors and gateways users will be onboarded to.
	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. (e.g., `order number`: 25, `item_type`: produce, `department`: sales, etc.)

Responses

200

A single onboarding_from objext.

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": {
    "entity": {
      "title": "CEO",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@finix.com",
      "business_name": "Finix Flowers",
      "business_type": "CORPORATION",
      "doing_business_as": "Finix Flowers",
      "phone": "14158885080",
      "business_phone": "14158885080",
      "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": "4952",
      "url": "https://www.finix.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": 2000000,
      "average_card_transfer_amount": 20000,
      "annual_ach_volume": 2000000,
      "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": "Alex",
        "last_name": "Smith",
        "email": "alex.smith@finix.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": {
      "name": "SARAH BANKER",
      "bank_code": "123456789",
      "account_number": "123456789",
      "account_type": "CHECKING",
      "type": "BANK_ACCOUNT"
    },
    "max_transaction_amount": 100000
  },
  "merchant_processors": [
    {
      "processor": "LITLE_V1"
    }
  ],
  "onboarding_link_details": {
    "return_url": "https://www.finixflowers.com/",
    "expired_session_url": "https://www.finixflowers.com/login",
    "terms_of_service_url": "https://www.finixflowers.com/ToS",
    "fee_details_url": "https://www.finixflowers.com/fee_details",
    "expiration_in_minutes": 10080
  }
}'

Response samples

application/json

{"id": "obf_cJUfiz97L8de54EwkC3Hiu",
"onboarding_data": {"entity": {"title": "CEO",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@finix.com",
"business_name": "Finix Flowers",
"business_type": "CORPORATION",
"doing_business_as": "Finix Flowers",
"phone": "14158885080",
"business_phone": "14158885080",
"mcc": "4900",
"url": "https://www.finix.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": "Alex",
"last_name": "Smith",
"email": "alex.smith@finix.com",
"phone": "14158885080",
"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": "SARAH BANKER",
"bank_code": "123456789",
"account_number": "*****6789",
"account_type": "CHECKING",
"type": "BANK_ACCOUNT"
},
"additional_underwriting_data": {"refund_policy": "NO_REFUNDS",
"average_ach_transfer_amount": 2000000,
"average_card_transfer_amount": 20000,
"annual_ach_volume": 2000000,
"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
}
},
"max_transaction_amount": 100000
},
"merchant_processors": [{"processor": "LITLE_V1"
}
],
"onboarding_link_details": {"return_url": "https://www.finixflowers.com/",
"expired_session_url": "https://www.finixflowers.com/login",
"fee_details_url": "https://www.finixflowers.com/fee_details",
"terms_of_service_url": "https://www.finixflowers.com/ToS",
"expiration_in_minutes": 10080
},
"onboarding_link": {"expires_at": "2023-04-06T19:16:28.387Z",
"link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_cJUfiz97L8de54EwkC3Hiu&applicationId=APgPDQrLD52TYvqazjHJJchM..."
},
"status": "IN_PROGRESS",
"identity_id": null,
"application_id": "APgPDQrLD52TYvqazjHJJchM",
"created_at": "2023-03-30T19:16:28.377022Z",
"updated_at": "2023-03-30T19:16:28.377022Z",
"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_from objext.

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_cJUfiz97L8de54EwkC3Hiu",
"onboarding_data": {"entity": {"title": "CEO",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@finix.com",
"business_name": "Finix Flowers",
"business_type": "CORPORATION",
"doing_business_as": "Finix Flowers",
"phone": "14158885080",
"business_phone": "14158885080",
"mcc": "4900",
"url": "https://www.finix.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": "Alex",
"last_name": "Smith",
"email": "alex.smith@finix.com",
"phone": "14158885080",
"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": "SARAH BANKER",
"bank_code": "123456789",
"account_number": "*****6789",
"account_type": "CHECKING",
"type": "BANK_ACCOUNT"
},
"additional_underwriting_data": {"refund_policy": "NO_REFUNDS",
"average_ach_transfer_amount": 2000000,
"average_card_transfer_amount": 20000,
"annual_ach_volume": 2000000,
"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
}
},
"max_transaction_amount": 100000
},
"merchant_processors": [{"processor": "LITLE_V1"
}
],
"onboarding_link_details": {"return_url": "https://www.finixflowers.com/",
"expired_session_url": "https://www.finixflowers.com/login",
"fee_details_url": "https://www.finixflowers.com/fee_details",
"terms_of_service_url": "https://www.finixflowers.com/ToS",
"expiration_in_minutes": 10080
},
"onboarding_link": {"expires_at": "2023-04-06T19:16:28.387Z",
"link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_cJUfiz97L8de54EwkC3Hiu&applicationId=APgPDQrLD52TYvqazjHJJchM..."
},
"status": "IN_PROGRESS",
"identity_id": null,
"application_id": "APgPDQrLD52TYvqazjHJJchM",
"created_at": "2023-03-30T19:16:28.377022Z",
"updated_at": "2023-03-30T19:16:28.377022Z",
"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 Displaying Processing Fees).
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"
}