Onboarding via link
Learn how to sent an invite link to onboard entities for payment acceptance.
Overview
In order to allow an entity to use Monite's payments rails, you have to onboard this entity for payment acceptance.
If the partner does not store in the Monite system the entity onboarding requirements, i.e. the information necessary for using the Monite payment rails, the entity itself will have to provide the necessary information about its business through by following a link that will take them to a branded onboarding page.
The steps below describe the full payments acceptance onboarding flow via link:
- Create an entity.
- Assign payment methods.
- Get the payments onboarding link.
- The entity fills the payments onboarding form.
- Track the payments onboarding status changes.
1. Create an entity
An entity is a party (person or business) that receives payments. To learn how to create and manage an entity that represents your customer, see the Entities page.
2. Assign payment methods
Once the entity is created, set which payment methods will be assigned for this entity by calling PUT /entities/{entity_id}/payment_methods
:
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/3fa85f64...3f66afa6/payment_methods' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"payment_methods": [
"card",
"eps",
"ideal",
"sepa_credit",
"sepa_debit"
]
}'
Check the full list of payment methods Monite supports.
This steps below are optional if the chosen payment method does not require onboarding for payments.
3. Get the payments onboarding link
The entity must access a specific link to initialize its onboarding for payments acceptance. To get this link, call POST /payment_onboarding_links
passing the:
type
of the recipient (entity
) and its ID obtained in the step 1;refresh_url
field, to redirect the entity in case the link is expired or was already visited;return_url
field, to allow the entity to automatically return to your platform after the onboarding process.
curl -X POST 'https://api.sandbox.monite.com/v1/payment_onboarding_links' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"recipient": {
"type": "entity",
"id": "<<Entity ID>>"
},
"refresh_url":"https://refresh.com",
"return_url":"https://return.com"
}'
The response contains the link url
, which will be used by the entity to proceed with its onboarding. The maximum payment link size is 400 characters:
{
"id": "G5h67rf-5717-4562-b3fc-2c3nno77gDFa6",
"created_at": "2022-09-12T17:27:42.772Z",
"expires_at": "2022-09-12T17:27:42.772Z",
"url": "https://connect.com/setup/c/acct_1LJHnC2QBdOEilEZ/f8ZXCHmQcgLo",
"recipient": {
"type": "entity",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"refresh_url":"https://refresh.com",
"return_url":"https://return.com"
}
4. The entity fills the payments onboarding form
The entity then will be redirected to the payments onboarding URL address, where they will be able to fill out the onboarding form.

Onboarding page example.
5. Track the payments onboarding status changes
5.1. Webhooks
You can be notified of every change in the status of the entity onboarding by subscribing to the entity.onboarding_requirements.status_updated
webhook. Call POST /webhook_settings
passing the object_type
as entity
and the URL of your endpoint:
curl -X POST 'https://api.sandbox.monite.com/v1/webhook_settings' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"object_type": "entity",
"url": "https://yourendpointurl.com"
}'
The event sent by Monite contains entity_id
, object_type
, and object_id
, which can be used to identify the affected entity:
{
"object_id": "3087f89a-a708-49ef-b0bd-3b88245bca38",
"object_type": "entity",
"action": "entity.onboarding_requirements.updated",
"name": "entity_onboarding_requirements_updated",
"entity_id": "3087f89a-a708-49ef-b0bd-3b88245bca38"
}
5.2. Get onboarding requirements
The entity ID received from the webhook can be used to check the progress of the entity onboarding, by calling GET /entities/{entity_id}/onboarding_requirements
:
curl -X GET 'https://api.sandbox.monite.com/v1/entities/3fa85f64...3f66afa6/onboarding_requirements' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The response contains the information about the entity onboarding:
{
"verification_status": "disabled",
"disabled_reason": "requirements.past_due",
"requirements_errors": [],
"verification_errors": [],
"requirements": {
"currently_due": [
"bank_account",
"entities.onboarding_data.business_profile.mcc",
"entities.organization.directors_provided",
"entities.phone",
"persons.representative.phone",
"persons.123e4567-e89b-12d3-a456-426614174000.first_name"
],
"eventually_due": [
"bank_account",
"entities.onboarding_data.business_profile.mcc",
"entities.organization.directors_provided",
"entities.phone",
"persons.representative.phone",
"persons.123e4567-e89b-12d3-a456-426614174000.first_name"
],
"current_deadline": null,
"pending_verification": []
}
}
Some fields are explained below:
requirements
: the list of required information still owed by the entity to finish the onboarding.currently_due
: the list of minimum fields required to keep the entity's account enabled and has to be collected by thecurrent_deadline
.eventually_due
: the list of fields that are not needed immediately, but will be when certain at a certain moment.current_deadline
: date by which the fields incurrently_due
must be collected to keep the entity's account enabled.business_profile.mcc
: merchant category code of the entity.persons.representative.phone
: it means that the phone of the representative must be provided.persons.123e4567-e89b-12d3-a456-426614174000.first_name
: when an ID is found in the response field, it means that the requirement of this specific ID is missing. In our example, the person with ID123e4567-e89b-12d3-a456-426614174000
must providefirst_name
.
Every time the entity makes a change to the list of requirements
, the onboarding_requirements.updated
webhook is triggered.
Updated 4 days ago