Onboarding via API [Beta]

🚧

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:

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.

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:

📘

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 the current_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 in currently_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 ID 123e4567-e89b-12d3-a456-426614174000 must provide first_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, call PUT /entities/{entity_id}/onboarding_data passing ownership_declaration.ip and ownership_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 of requirements, the onboarding_requirements.updated webhook is triggered.
• entity.onboarding_requirements.status_updated. Every time the entity onboarding has a change on its verification_status, the onboarding_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": []
  }
}