Onboard for payments acceptance
Learn how 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 payments acceptance. The steps below describe the full payments acceptance onboarding flow:
- 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 '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.
3. Get the payments onboarding link
This step is optional if the chosen payment method does not require the onboarding for payments, e.g.
sepa_credit
.
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-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-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:
{
"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.
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 '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 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'accept: application/json' \
The response contains the information about the entity onboarding:
{
"verification_status": "disabled",
"disabled_reason": "requirements.past_due",
"requirements_errors": [],
"verification_errors": [],
"provided_data": {
"tos_acceptance": {
"date": null,
"ip": null,
"service_agreement": null,
"user_agent": null
}
},
"requirements": {
"currently_due": [
"business_profile.mcc",
"business_profile.url",
"external_account",
"individual.dob.day",
"individual.dob.month",
"individual.dob.year",
"individual.email",
"individual.phone",
"tos_acceptance.date",
"tos_acceptance.ip"
],
"eventually_due": [
"business_profile.mcc",
"business_profile.url",
"external_account",
"individual.dob.day",
"individual.dob.month",
"individual.dob.year",
"individual.email",
"individual.phone",
"tos_acceptance.date",
"tos_acceptance.ip"
],
"current_deadline": null,
"pending_verification": []
}
}
Some fields are explained below:
requirements
: the list of required information still owed by the entity to finish the onboardingbusiness_profile.mcc
: merchant category codetos_acceptance.ip
,tos_acceptance.date
: terms of serviceindividual.dob.day
,individual.dob.month
,individual.dob.year
: date of birth
Every time the entity makes a change to the list of requirements
, the onboarding_requirements.updated
webhook is triggered.
Updated 13 days ago