Onboarding via link (US only)

📘

This guide applies only to US-based entities who want to use ACH payments. Entities from other countries should use API-only onboarding.

Overview

In order to allow a US-based 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 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.

Roles and permissions

Most endpoints mentioned in this guide require a partner-level access token.

The GET /onboarding_requirements can also be called with an entity user access token if this user has a role with the read permission for onboarding.

1. Create an entity

An entity is a party (person or business) that makes or receives payments. To learn how to create and manage entities that represent your customers, see Entities.

2. Subscribe to webhooks

To get notified about the onboarding progress of your entities, subscribe to the entity.onboarding_requirements.status_updated webhook. To do this, call POST /webhook_subscriptions with the following request body, replacing the url with the URL of your webhook listener endpoint:

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

3. Assign payment methods

To specify the payment methods that an entity expects to be using, call PUT /entities/{entity_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.

The following example enables the ACH payment method for an entity:

curl -X PUT 'https://api.sandbox.monite.com/v1/entities/3fa85...fa6/payment_methods' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payment_methods_send": [
         "us_ach"
       ]
     }'

📘

Notes

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

💡

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

4. 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 /onboarding_links with the entity ID in the X-Monite-Entity-Id field and with the request body containing the following fields:

• refresh_url - the URL on your platform to which the entity user should be redirected if the original onboarding link has expired or was already visited;
• return_url - the URL on your platform to which the entity will be redirected after the onboarding process.
• expires_at - the date and time when this link will expire (in the ISO 8601 format).

curl -X POST 'https://api.sandbox.monite.com/v1/onboarding_links' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "refresh_url": "https://example.com/expired-link",
       "return_url": "https://example.com/onboarding-complete",
       "expires_at": "2024-04-01T00:00:00Z"
     }'

The response contains the url of Monite-hosted onboarding page that the entity can use to proceed with its onboarding.

{
  "refresh_url": "https://example.com/expired-link",
  "return_url": "https://example.com/onboarding-complete",
  "expires_at": "2024-04-01T00:00:00Z",
  "id": "76047531-2737-4075-b3f6-7f1f42eb78c1",
  "entity_id": "37156af0-fbf7-44f7-b375-42e4d98733e2",
  "url": "https://example.com/onboarding-link-for-this-entity"
}

5. The entity fills the payments onboarding form

Next, redirect the user to onboarding url you obtained on the previous step. This onboarding page will prompt the user to fill in information about their entity.

After the user completes filling the form, Monite will redirect the user to the return_url you provided earlier.

6. Track the payments onboarding status

6.1. Webhooks

Assuming you have subscribed to the payment webhooks, you will receive the entity.onboarding_requirements.status_updated webhook event whenever an entity's onboarding status is changed. The event payload contains entity_id that can be used to identify the affected entity:

{
  "id": "8cac4aa7-09c0-40e7-94a3-54adb9cc744e",
  "created_at": "2024-03-04T20:08:16.097467+00:00",
  "action": "entity.onboarding_requirements.status_updated",
  "api_version": "2024-01-31",
  "entity_id": "37156af0-fbf7-44f7-b375-42e4d98733e2",
  "description": "entity_onboarding_requirements_status_updated",
  "object": {
    "id": "37156af0-fbf7-44f7-b375-42e4d98733e2"
  },
  "object_type": "entity",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}

6.2. Get onboarding requirements

The entity ID received from the webhook can be used to check the progress of entity onboarding, by calling GET /onboarding_requirements:

curl -X GET 'https://api.sandbox.monite.com/v1/onboarding_requirements' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -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 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 - the merchant category code (MCC) of the entity.
• 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. In this example, the first_name must be provided for the person with ID 123e4567-e89b-12d3-a456-426614174000.

Every time the entity provides some of the listed requirements, the onboarding_requirements.updated webhook is triggered.

Next steps

After a US-based entity is onboarded, it needs to verify its bank account. See Verifying bank accounts for ACH payments.