Onboarding for payments acceptance

Overview

In order to allow a recipient to use Monite's payments rails, you have to onboard this recipient. The steps below describe the full payments onboarding flow:

1. Create the recipient.
2. Get the payments onboarding link.
3. The recipient fills the onboarding form.
4. Track the payments onboarding status changes.

1. Create the recipient

A recipient is a party (person or business) with whom the SMEs may send or receive payments. It can be either an entity or a counterpart.

Follow one of the links below to learn how to create each type of recipient:

• Create an entity
• Create a counterpart

2. Get the payments onboarding link

💡

This step is optional if the chosen payment method does not require the payments onboarding(i.e. sepa_credit).

To enable a recipient for payments, call POST /payment_onboarding_links passing the:

• type of the recipient (entity or counterpart) and its ID obtained in the previous step;
• refresh_url field, to redirect the recipient in case the link is expired or was already visited;
• return_url field, to allow the recipient to automatically return to your platform after the onboarding process if wished.

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>>"
     },
     "capabilities":[
        "card_payments",
        "transfers",
        "ideal_payments",
        "sepa_debit_payments",
        "eps_payments"
     ],
     "refresh_url":"https://refresh.com",
     "return_url":"https://return.com"
  }'

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": "counterpart",
       "id": "<<Counterpart ID>>"
     },
     "capabilities":[
        "card_payments",
        "transfers",
        "ideal_payments",
        "sepa_debit_payments",
        "eps_payments"
     ],
     "refresh_url":"https://refresh.com",
     "return_url":"https://return.com"
  }'

The response contains an url of the payments onboarding flow, which will be used by the recipient to finish its payments 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"
  },
  "capabilities": [
    "card_payments",
    "transfers",
    "ideal_payments",
    "sepa_debit_payments",
    "eps_payments"
  ],
  "refresh_url":"https://refresh.com",
  "return_url":"https://return.com"
}

3. The recipient fills the payments onboarding form

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

4. Track the payments onboarding status changes

Once the payments onboarding is initiated, you can track its status by subscribing to a webhook, so you are notified when the payments onboarding status changes to pending or done.

To enable this webhook, call POST /webhook_settings, passing in the body the object_type as account and the URL of your endpoint:

curl -X POST 'https://api.sandbox.monite.com/v1/webhook_settings' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -d '{
    "object_type": "account",
    "url": "https://yourendpointurl.com"
  }'

📘

It is possible to run this call more than once and associate one object_type with multiple URLs.

The successful response contains the ID of the webhook:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "account",
  "url": "https://yourendpointurl.com"
}

📘

Check our Webhooks page for further information.