Onboarding via API [Beta]
Learn how to onboard entities for payment acceptance via API.
This feature is currently in closed beta version, subject to change, and is only available upon customer requests. If you are an eligible partner of Monite and would like to get access to the Onboarding via API, please contact your Account Manager at Monite.
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 previously stores in the Monite system the entity onboarding requirements, i.e. the information necessary for using the Monite payment rails, you can perform the entity's onboarding via API.
Through onboarding via API, you can streamline the entity's onboarding process and reduce the time and effort required to onboard new entities.
These are the required steps to onboard an entity for payment acceptance via API:
- Create an entity.
- Assign payment methods.
- Check for missing requirements.
- Provide the missing requirements
- Track the payments onboarding status changes.
1. Create an entity
An entity is a party (person or business) that can receive payments via Monite partner's payment rails. To learn how to create and manage an entity that represents your customer, see Entities.
Required information for onboarding
Providing as much information as possible during the entity's registration process will make the onboarding process smoother. Here is the list of the information necessary for onboarding that should be fulfilled in advance and its related endpoints:
Object | Example | Endpoint |
---|---|---|
bank_account | bank_account | POST /bank_accounts |
entities.x | entities.phone | PATCH /entities/{entity_id} |
persons.x | persons.representative.phone | POST /persons |
persons.onboarding_documents | persons.onboarding_documents | POST /persons/{person_id}/documents |
entities.onboarding_data.x | entities.onboarding_data.business_profile.mcc | PUT /entities/{entity_id}/onboarding_data |
entities.onboarding_documents | entities.onboarding_documents | POST /entities/{entity_id}/documents |
Important
- It is necessary to set at least one default bank account for the entity in order to perform payouts.
- If you are creating an entity of the type
organization
, it is important to register the information of the legally responsible individuals associated with that organization. See Persons for further information.- To complete the onboarding, the entities and persons must also inform the onboarding data and onboarding documents.
2. Assign payment methods
Assign the list of payment methods that will be accepted by this entity by calling PUT /entities/{entity_id}/payment_methods
:
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/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 that Monite supports.
This steps below are optional if the chosen payment method does not require onboarding for payments.
3. Check for missing requirements
Some entity's requirements for onboarding may still be missing after the entity creation. You can check which requirements are still missing to complete the onboarding process by calling GET /entities/{entity_id}/onboarding_requirements
:
curl -X GET 'https://api.sandbox.monite.com/v1/entities/{entity_id}/onboarding_requirements' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer ACCESS_TOKEN'
The successful response lists the information that is still missing to complete the onboarding process:
{
"verification_status": "disabled",
"disabled_reason": "requirements.past_due",
"requirements_errors": [],
"verification_errors": [],
"requirements": {
"currently_due": [
"bank_account",
"entities.onboarding_data.business_profile.mcc",
"entities.onboarding_data.ownership_declaration.date",
"entities.onboarding_data.ownership_declaration.ip",
"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.onboarding_data.ownership_declaration.date",
"entities.onboarding_data.ownership_declaration.ip",
"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.entities.onboarding_data.ownership_declaration.*
: a declaration, from the one submitting the company information, that the business is appropriately registered and that the information provided is correct.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
.
You can call the GET /entities/{entity_id}/onboarding_requirements
endpoint to check the updated list at any time.
4. Provide the missing requirements
Once you know which requirements are missing to finish the onboarding for payments, you can provide them via the API.
The endpoint used to update the missing requirements and complete the onboarding process depends on the missing information's object. See the complete list of the required information for onboarding and its related endpoints.
Depending on the payment provider and the inconsistencies found in the information sent, you may have to provide the
ownership_declaration
at this stage.To provide the information about the
ownership_declaration
, callPUT /entities/{entity_id}/onboarding_data
passingownership_declaration.ip
andownership_declaration.date
in the body.
5. Track the payments onboarding status changes
You can be notified of every change in the entity onboarding requirements by subscribing to these webhooks:
entity.onboarding_requirements.updated
: Every time the entity makes a change to the list ofrequirements
, theonboarding_requirements.updated
webhook is triggered.entity.onboarding_requirements.status_updated
. Every time the entity onboarding has a change on itsverification_status
, theonboarding_requirements.status_updated
webhook is triggered.
To subscribe to these webhooks, 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"
}
{
"object_id": "3087f89a-a708-49ef-b0bd-3b88245bca38",
"object_type": "entity",
"action": "entity.onboarding_requirements.status_updated",
"name": "entity_onboarding_requirements_status_updated",
"entity_id": "3087f89a-a708-49ef-b0bd-3b88245bca38"
}
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
. Once all the requirements are provided, the result of the call will look like this:
{
"verification_status": "enabled",
"disabled_reason": null,
"requirements_errors": [],
"verification_errors": [],
"requirements": {
"currently_due": [],
"eventually_due": [],
"current_deadline": null,
"pending_verification": []
}
}
Updated 11 days ago