HomeGuidesAPI ExplorerDiscussionsSandbox

Onboarding via link

Learn how to sent an invite link to onboard entities for payment acceptance.

Suggest Edits

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 does not store in the Monite system the entity onboarding requirements, i.e. the information necessary for using the Monite payment rails, the entity itself will have to provide the necessary information about its business through by following a link that will take them to a branded onboarding page.

The steps below describe the full payments acceptance onboarding flow via link:

  1. Create an entity.
  2. Assign payment methods.
  3. Get the payments onboarding link.
  4. The entity fills the payments onboarding form.
  5. Track the payments onboarding status changes.

1. Create an entity

An entity is a party (person or business) that receives payments. To learn how to create and manage an entity that represents your customer, see the Entities page.

2. Assign payment methods

Once the entity is created, set which payment methods will be assigned for this entity by calling PUT /entities/{entity_id}/payment_methods:

curl -X PUT 'https://api.sandbox.monite.com/v1/entities/3fa85f64...3f66afa6/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 Monite supports.

💡

This steps below are optional if the chosen payment method does not require onboarding for payments.

3. Get the payments onboarding link

The entity must access a specific link to initialize its onboarding for payments acceptance. To get this link, call POST /payment_onboarding_links passing the:

  • type of the recipient (entity) and its ID obtained in the step 1;
  • refresh_url field, to redirect the entity in case the link is expired or was already visited;
  • return_url field, to allow the entity to automatically return to your platform after the onboarding process.
curl -X POST 'https://api.sandbox.monite.com/v1/payment_onboarding_links' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "recipient": {
          "type": "entity",
          "id": "<<Entity ID>>"
        },
        "refresh_url":"https://refresh.com",
        "return_url":"https://return.com"
     }'

The response contains the link url, which will be used by the entity to proceed with its onboarding. The maximum payment link size is 400 characters:

{
  "id": "G5h67rf-5717-4562-b3fc-2c3nno77gDFa6",
  "created_at": "2022-09-12T17:27:42.772Z",
  "expires_at": "2022-09-12T17:27:42.772Z",
  "url": "https://connect.com/setup/c/acct_1LJHnC2QBdOEilEZ/f8ZXCHmQcgLo",
  "recipient": {
    "type": "entity",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "refresh_url":"https://refresh.com",
  "return_url":"https://return.com"
}

4. The entity fills the payments onboarding form

The entity then will be redirected to the payments onboarding URL address, where they will be able to fill out the onboarding form.

Onboarding page example.

Onboarding page example.

5. Track the payments onboarding status changes

5.1. Webhooks

You can be notified of every change in the status of the entity onboarding by subscribing to the entity.onboarding_requirements.status_updated webhook. 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"
}

5.2. Get onboarding requirements

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:

curl -X GET 'https://api.sandbox.monite.com/v1/entities/3fa85f64...3f66afa6/onboarding_requirements' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The response contains the information about the entity onboarding:

{
    "verification_status": "disabled",
    "disabled_reason": "requirements.past_due",
    "requirements_errors": [],
    "verification_errors": [],
    "requirements": {
        "currently_due": [
          "bank_account",
          "entities.onboarding_data.business_profile.mcc",
          "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.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.
  • 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.

Every time the entity makes a change to the list of requirements, the onboarding_requirements.updated webhook is triggered.

Updated 4 days ago