Onboard for payments acceptance

Learn how 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 payments acceptance. The steps below describe the full payments acceptance onboarding flow:

  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 '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.

3. Get the payments onboarding link

💡

This step is optional if the chosen payment method does not require the onboarding for payments, e.g. sepa_credit.

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-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -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:

{
  "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.

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 '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 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -H 'accept: application/json' \

The response contains the information about the entity onboarding:

{
  "verification_status": "disabled",
  "disabled_reason": "requirements.past_due",
  "requirements_errors": [],
  "verification_errors": [],
  "provided_data": {
    "tos_acceptance": {
      "date": null,
      "ip": null,
      "service_agreement": null,
      "user_agent": null
    }
  },
  "requirements": {
    "currently_due": [
      "business_profile.mcc",
      "business_profile.url",
      "external_account",
      "individual.dob.day",
      "individual.dob.month",
      "individual.dob.year",
      "individual.email",
      "individual.phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "eventually_due": [
      "business_profile.mcc",
      "business_profile.url",
      "external_account",
      "individual.dob.day",
      "individual.dob.month",
      "individual.dob.year",
      "individual.email",
      "individual.phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "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
  • business_profile.mcc: merchant category code
  • tos_acceptance.ip, tos_acceptance.date: terms of service
  • individual.dob.day, individual.dob.month, individual.dob.year: date of birth

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

Updated 13 days ago