Onboarding via API [Beta]

🚧
This feature is currently in closed beta, 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 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:

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 entities that represent your customers, 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 provided in advance, and the 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

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.

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.

2. Assign payment methods

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.

curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/payment_methods' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payment_methods_receive": [
         "card",
         "eps",
         "ideal",
         "sepa_credit",
         "sepa_debit"
       ],
       "payment_methods_send": [
         "sepa_credit"
       ]
     }'

📘
Notes

Some payment methods are limited to certain countries or currencies. For example, 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).

Some payment methods can be used both to send and receive payments, while others can be used only to send or only to receive payments.

Currently, us_ach can only be used in payment_methods_receive and cannot be used in payment_methods_send.

💡
This steps below are optional if the chosen payment methods do not require onboarding for payments.

3. Check for missing requirements

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 /entities/{entity_id}/onboarding_requirements:

curl -X GET 'https://api.sandbox.monite.com/v1/entities/{entity_id}/onboarding_requirements' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'Authorization: Bearer YOUR_PARTNER_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 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 /entities/{entity_id}/onboarding_requirements again at any time to check the updated list.

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 need to provide the ownership_declaration at this stage.
To provide the information about the ownership_declaration, call PUT /entities/{entity_id}/onboarding_data passing ownership_declaration.ip and ownership_declaration.date in the body.

5. Track the payments onboarding status

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_settings with the request body containing the the URL of your webhook listener endpoint and the object_type field set to "entity":

curl -X POST 'https://api.sandbox.monite.com/v1/webhook_settings' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object_type": "entity",
       "url": "https://yourendpointurl.com"
     }'

Webhook events sent by Monite contain 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 a webhook event can be used to check the progress of entity onboarding by calling GET /entities/{entity_id}/onboarding_requirements. Once all the requirements are provided, the response will look like this:

{
  "verification_status": "enabled",
  "disabled_reason": null,
  "requirements_errors": [],
  "verification_errors": [],
  "requirements": {
    "currently_due": [],
    "eventually_due": [],
    "current_deadline": null,
    "pending_verification": []
  }
}