Onboarding US entities for payments

Overview

Before a US entity can send or receive payments via Monite, this entity must complete the onboarding process. Monite provides a hosted onboarding page where entities can fill in their business information and upload the supporting documents.

The onboarding process includes the following steps:

1. Create an entity.
2. Add an entity bank account.
3. Enable payment methods for the entity.
4. Generate an onboarding link for the entity.
5. An entity representative fills in the onboarding form.
6. Track the onboarding status.

Roles and permissions

Unless stated otherwise, the endpoints mentioned in this guide require a partner-level access token.

1. Create an entity

An entity is an organization that makes or receives payments. To learn how to create and manage entities that represent your customers, see Entities.

2. Add an entity bank account

A bank account is required for entitites to make or receive payments. To learn how to add bank account details, see Entity bank accounts.

• In accounts payable scenarios, this is the bank account to withdraw the funds from. Bank accounts used for accounts payable must be verified after an entity completes its payments onboarding covered in this guide.

• In accounts receivable scenarios, payouts are sent to the entity bank account designated as default. It is not necessarily the same bank account as listed on invoices.

  Bank accounts for accounts receivable do not need to be verified.

You can add entity bank accounts at any time before or after payments onboarding, but it has to be before creating the first payment link or initiating the first outgoing payment.

An entity can have several USD bank accounts if needed. For example, it is possible to use different bank accounts for accounts payable and accounts receivable payments.

3. Assign payment methods

To specify the payment methods that an entity is going to use, call PUT /entities/{entity_id}/payment_methods. The request body must contain at least one of the following:

• payment_methods_receive - payment methods for accounts receivable, that is, for accepting payments from counterparts. Invoice payment links will display these payment methods.

• payment_methods_send - payment methods for account payable. The entity can use them to send payments to its counterparts. Only us_ach is currently available, which corresponds to ACH Direct Debit and paper checks.

  Support for outgoing USD payments is in beta.

The following example includes all available payment methods for the US:

1
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/3fa85...fa6/payment_methods' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4
     -H 'Content-Type: application/json' \
5
     -d '{
6
       "payment_methods_send": [
7
         "us_ach"
8
       ],
9
       "payment_methods_receive": [
10
         "card",
11
         "us_ach",
12
         "applepay",
13
         "googlepay"
14
       ]
15
     }'

4. Generate an onboarding link

The entity must access a specific link to initialize its payments onboarding. 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).

1
curl -X POST 'https://api.sandbox.monite.com/v1/onboarding_links' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "refresh_url": "https://example.com/expired-link",
8
       "return_url": "https://example.com/onboarding-complete",
9
       "expires_at": "2025-04-01T00:00:00Z"
10
     }'

The response contains the url of Monite-hosted onboarding page for this entity:

1
{
2
  "id": "76047531-2737-4075-b3f6-7f1f42eb78c1",
3
  "entity_id": "ENTITY_ID",
4
  "expires_at": "2025-04-01T00:00:00Z",
5
  "refresh_url": "https://example.com/expired-link",
6
  "return_url": "https://example.com/onboarding-complete",
7
  "url": "https://onboarding.sandbox.monite.com?data=eyJp..."
8
}

5. Entity representative fills in the onboarding form

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

Below are a few sample screens from the onboarding flow:

After the user completes filling the form, Monite automatically redirects the user to the return_url you provided earlier.

6. Track the onboarding status

Entity verification may take up to 2 business days. To track the progress, you can call GET /entities/{entity_id}/payment_methods periodically and check the status of all payment methods. Once all payment methods become active, the entity can start using payments.

1
{
2
  "data": [
3
    {
4
      "direction": "receive",
5
      "name": "Card payments",
6
      "status": "active",
7
      "type": "card"
8
    },
9
    ...
10
    {
11
      "direction": "receive",
12
      "name": "US ACH Payments",
13
      "status": "active",
14
      "type": "us_ach"
15
    },
16
    {
17
      "direction": "send",
18
      "name": "US ACH Payments",
19
      "status": "active",
20
      "type": "us_ach"
21
    }
22
  ]
23
}

Next steps

The next steps depend on whether the entity will use payments for accounts payable, accounts receivable, or both:

• Payments for accounts payable (and optionally accounts receivable):

  • The entity needs to verify the bank account from which the funds will be withdrawn.

• Payments for accounts receivable only:

  • No additional verification is needed. The entity can now start creating payment links for invoices.