Onboarding via API

Overview

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:

1. Create an entity.
2. Assign payment methods.
3. Check for missing requirements.
4. Provide the missing requirements
5. Track the payments onboarding status changes.

Roles and permissions

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, update
• person: create, update, delete

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:

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.

1
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/payment_methods' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4
     -H 'Content-Type: application/json' \
5
     -d '{
6
       "payment_methods_receive": [
7
         "card",
8
         "eps",
9
         "ideal",
10
         "sepa_credit",
11
         "sepa_debit"
12
       ],
13
       "payment_methods_send": [
14
         "sepa_credit"
15
       ]
16
     }'

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.

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 /onboarding_requirements:

1
curl -X GET 'https://api.sandbox.monite.com/v1/onboarding_requirements' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The successful response lists the information that is still missing to complete the onboarding process:

1
{
2
    "verification_status": "disabled",
3
    "disabled_reason": "requirements.past_due",
4
    "requirements_errors": [],
5
    "verification_errors": [],
6
    "requirements": {
7
        "currently_due": [
8
          "bank_account",
9
          "entities.onboarding_data.business_profile.mcc",
10
          "entities.onboarding_data.ownership_declaration.date",
11
          "entities.onboarding_data.ownership_declaration.ip",
12
          "entities.organization.directors_provided",
13
          "entities.phone",
14
          "persons.representative.phone",
15
          "persons.123e4567-e89b-12d3-a456-426614174000.first_name"
16
        ],
17
        "eventually_due": [
18
          "bank_account",
19
          "entities.onboarding_data.business_profile.mcc",
20
          "entities.onboarding_data.ownership_declaration.date",
21
          "entities.onboarding_data.ownership_declaration.ip",
22
          "entities.organization.directors_provided",
23
          "entities.phone",
24
          "persons.representative.phone",
25
          "persons.123e4567-e89b-12d3-a456-426614174000.first_name"
26
        ],
27
        "current_deadline": null,
28
        "pending_verification": []
29
    }
30
}

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.

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.

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 following request body, replacing the url with the URL of your webhook listener endpoint:

1
curl -X POST 'https://api.sandbox.monite.com/v1/webhook_settings' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4
     -H 'Content-Type: application/json' \
5
     -d '{
6
       "object_type": "entity",
7
       "event_types": [
8
         "onboarding_requirements.updated",
9
         "onboarding_requirements.status_updated"
10
       ],
11
       "url": "https://yourcompany.com/webhook-listener"
12
     }'

Webhook events sent by Monite contain the entity_id, which you can use to identify the affected entity:

1
{
2
  "id": "8cac4aa7-09c0-40e7-94a3-54adb9cc744e",
3
  "created_at": "2024-03-04T20:08:16.097467+00:00",
4
  "action": "entity.onboarding_requirements.updated",
5
  "api_version": "2023-09-01",
6
  "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
7
  "name": "entity_onboarding_requirements_updated",
8
  "object_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
9
  "object_type": "entity",
10
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
11
}

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:

1
{
2
  "verification_status": "enabled",
3
  "disabled_reason": null,
4
  "requirements_errors": [],
5
  "verification_errors": [],
6
  "requirements": {
7
    "currently_due": [],
8
    "eventually_due": [],
9
    "current_deadline": null,
10
    "pending_verification": []
11
  }
12
}