> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# 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 \[#permissions]

Unless mentioned otherwise, the endpoints used in this guide can be called with both the [partner access token](../../../get-started/credentials#generate-partner-token) and [entity user tokens](../../../api/concepts/authentication#entity-user-token). In the latter case, the entity user needs a role with the following [permissions](../../../api/concepts/authentication#permissions):

* `onboarding`: `create`, `update`
* `person`: `create`, `update`, `delete`

## 1. Create an entity \[#create-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](../../../entities/index).

### Required information for onboarding \[#required-info]

Providing as much information as possible during the entity's registration process will make the [onboarding process](#provide-missing-requirements) 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`](/api/entity-bank-accounts/post-bank-accounts)                                              |
| `entities.x`                 | `entities.phone`                                                                                                                                                                                                     | [`PATCH /entities/{entity_id}`](/api/entities/patch-entities-id)                                                   |
| `persons.x`                  | `persons.representative.phone`                                                                                                                                                                                       | [`POST /persons`](/api/entity-persons/post-persons)                                                                |
| `persons.documents`          | `persons.documents.additional_document` `persons.documents.verification_document` See [Manage documents](./documents) for more information about these document types.                                               | [`POST /persons/{person_id}/onboarding_documents`](/api/onboarding-documents/post-persons-id-onboarding-documents) |
| `entities.onboarding_data.x` | `entities.onboarding_data.business_profile.mcc`                                                                                                                                                                      | [`PATCH /entities/{entity_id}/onboarding_data`](/api/entity-onboarding-data/patch-entities-id-onboarding-data)     |
| `entities.documents`         | `entities.documents.additional_document` `entities.documents.verification_document`  `entities.documents.proof_of_registration` See [Manage documents](./documents) for more information about these document types. | [`POST /onboarding_documents`](/api/onboarding-documents/post-onboarding-documents)                                |

> **Important**
>
> * Entity name must be no longer than 100 characters.
>
> * An entity must have at least one [bank account](../../../entities/bank-accounts) 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](../../../entities/bank-accounts#default) 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](./persons#add). See [Persons](./persons) for further information.
>
> * To complete the onboarding, the entities and persons must also provide the [onboarding data](./additional-data) and [onboarding documents](./documents).

## 2. Assign payment methods \[#assign-payment-methods]

To specify the [payment methods](../../payment-methods) that an entity expects to be using, call [`PUT /entities/{entity_id}/payment_methods`](/api/payment-methods/put-entities-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.

```sh
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/payment_methods' \
     -H 'X-Monite-Version: 2024-05-25' \
     -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](../../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](https://en.wikipedia.org/wiki/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`.

> **Info**
>
> The steps below are **optional** if the chosen payment methods do **not** require onboarding for payments.

## 3. Check for missing requirements \[#check-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`](/api/onboarding-requirements/get-onboarding-requirements):

```sh
curl -X GET 'https://api.sandbox.monite.com/v1/onboarding_requirements' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
```

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

```json
{
    "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)](../../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`](/api/onboarding-requirements/get-onboarding-requirements) again at any time to check the updated list.

## 4. Provide the missing requirements \[#provide-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](#required-info).

> **Info**
>
> 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`](./additional-data#provide), call [`PATCH /entities/{entity_id}/onboarding_data`](/api/entity-onboarding-data/patch-entities-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](../../../references/webhooks/index):

* `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`](/api/webhook-subscriptions/post-webhook-subscriptions)  with the following request body, replacing the `url` with the URL of your webhook listener endpoint:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/webhook_subscriptions' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object_type": "entity",
       "event_types": [
         "onboarding_requirements.updated",
         "onboarding_requirements.status_updated"
       ],
       "url": "https://yourcompany.com/webhook-listener"
     }'
```

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

#### onboarding\_requirements.updated

```json
{
  "id": "8cac4aa7-09c0-40e7-94a3-54adb9cc744e",
  "created_at": "2024-03-04T20:08:16.097467+00:00",
  "action": "entity.onboarding_requirements.updated",
  "api_version": "2024-05-25",
  "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
  "description": "entity_onboarding_requirements_updated",
  "object": {
    "id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0"
  },
  "object_type": "entity",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
```

#### onboarding\_requirements.status\_updated

```json
{
  "id": "90cc1b23-9681-40f4-a54b-4c059cd4397d",
  "created_at": "2024-03-04T20:12:48.399442+00:00",
  "action": "entity.onboarding_requirements.status_updated",
  "api_version": "2024-05-25",
  "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
  "description": "entity_onboarding_requirements_status_updated",
  "object": {
    "id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0"
  },
  "object_type": "entity",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
```

The entity ID received from a webhook event can be used to check the progress of entity onboarding by calling [`GET /onboarding_requirements`](/api/onboarding-requirements/get-onboarding-requirements). Once all the requirements are provided, the response will look like this:

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