Before an entity can receive or make payments via Monite, this entity must be onboarded.
If the partner previously stored the entity onboarding requirements (the information required to use the Monite payment rails) in the Monite system, then you can onboard the entity via API.
By onboarding via API, you can streamline the entity 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:
Unless mentioned otherwise, the endpoints used in this guide can be called with both the partner access token and entity user tokens. In the latter case, the entity user needs a role with the following permissions:
onboarding: create, updateperson: create, update, deleteAn entity is a party (person or business) that can receive payments via Monite partner’s payment rails. To learn how to create and manage entities that represent your customers, see Entities.
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 provided in advance, and the related endpoints:
Entity name must be no longer than 100 characters.
An entity must have at least one bank account in order to receive payments. The bank account currency should match the payment currency. If an entity has several bank accounts (whether for the same currency or different currencies), it must set the default bank account for each currency.
To use the sepa_credit payment method, the entity’s default bank account must be in a country in the SEPA zone.
Entities of the type organization must register the information of the legally responsible individuals associated with their organization. See Persons for further information.
To complete the onboarding, the entities and persons must also provide the onboarding data and onboarding documents.
To specify the payment methods that an entity expects to be using, call PUT /entities/{entity_id}/payment_methods. In the request body, the payment_methods_receive list specifies the methods by which the entity can receive payments from its counterparts, and the payment_methods_send list specifies the methods that the entity can use to make payments to others.
Notes:
us_ach can only be used by US-based entities, and sepa_credit can only be used in European countries that are part of the Single Euro Payments Area (SEPA).us_ach can only be used in payment_methods_receive and cannot be used in payment_methods_send.The steps below are optional if the chosen payment methods do not require onboarding for payments.
An entity may need to provide additional information or documents before it can use certain payment methods. To check if any additional information is required to complete the onboarding process, call GET /onboarding_requirements:
The successful response lists the information that is still missing to complete the onboarding process:
Some fields are explained below:
requirements - the list of required information that the entity needs to provide to finish the onboarding.currently_due - the list of minimum fields required to keep the entity’s account enabled. This data must be provided by the current_deadline date.current_deadline - date by which the fields in currently_due must be collected to keep the entity’s account enabled.eventually_due - the list of fields that are not needed immediately, but will be needed at some point later.business_profile.mcc - merchant category code (MCC) of the entity.entities.onboarding_data.ownership_declaration.* - a declaration, from the person submitting the entity information, that the business is appropriately registered and that the information provided is correct.persons.representative.phone - means that the phone number of the entity’s representative must be provided.persons.123e4567-e89b-12d3-a456-426614174000.first_name - when a UUID is found in a field name, it means that a resource with that ID is missing some information. the first_name must be provided for the person with ID 123e4567-e89b-12d3-a456-426614174000.After an entity provides this additional information, you can call GET /onboarding_requirements again at any time to check the updated list.
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 need to provide the ownership_declaration at this stage.
To provide the information about the ownership_declaration, call PATCH /entities/{entity_id}/onboarding_data passing ownership_declaration.ip and ownership_declaration.date in the body.
You can be notified of every change in the entity onboarding requirements by subscribing to these webhooks:
entity.onboarding_requirements.updated - triggered every time an entity makes a change to the list of requirements.entity.onboarding_requirements.status_updated - triggered every time the verification_status of an entity’s onboarding process changes.To subscribe to these webhooks, call POST /webhook_subscriptions with the following request body, replacing the url with the URL of your webhook listener endpoint:
Webhook events sent by Monite contain the entity_id, which you can use to identify the affected entity:
The entity ID received from a webhook event can be used to check the progress of entity onboarding by calling GET /onboarding_requirements. Once all the requirements are provided, the response will look like this:
Learn how to provide information about the key persons of organization-type entities.