Pay via paper checks

Monite enables US-based entities to pay their vendors with paper checks, utilizing ACH Direct Debit for fund transfer from the entity's bank account.

📘

All API calls mentioned in this guide require a partner access token.

Requirements

This guide assumes that:

• Both the entity and the counterparts (payee) are US-based.
• The entity has the us_ach_paper_checks payment method enabled.
• The entity has verified the ownership of its bank account. This is required for Monite to be able to withdraw funds from the entity's bank account.

Requirements for counterparts:

• The address specified by default_billing_address_id must have all fields filled in, including optional fields. Optional fields with no value should be stored as empty strings instead of null.
• If default_billing_address_id is not specified, the counterpart's default address is instead used as the billing address. This default address must have all fields filled in.

How it works

The typical flow for paper check payouts is as follows:

• The entity provides its bank account details, and completes the verification of its bank account.
• The entity chooses to pay one or more payables (bills).
• The entity chooses paper checks as the payment method for some or all of the selected payables or for specific counterparts.
• Monite initiates an ACH Direct Debit to pull funds from the entity's bank account. The amount pulled is the total amount of all payables that the entity chose to pay.
• Monite prints a check and mails it to the counterpart's address. The checks are sent as if they were from the entity.

Paper check delivery time

Paper checks take 7-10 business days to arrive to the counterpart (payee). Monite partners should display the information about delivery times in their applications when users select "paper check" as the payment method.

1. Subscribe to the webhooks

To get notified about the status updates of payments made by entities, you need to subscribe to these webhooks:

• batch_payment.status_updated - notifies about status transitions of a batch payment as a whole;
• payment_intent.status_updated - notifies about status transitions of individual payment intents within the batch payment.

2. Create a batch payment with the paper check delivery method

To issue paper checks on behalf of an entity, call POST /batch_payments and provide information about the payables that the entity wants to pay and the entity's bank account to withdraw funds from. A single request can include one or more payables. A separate paper check will be issued for each payable listed in the request.

📘

The specified payables must be in the waiting_to_be_paid status.

curl -X POST 'https://api.sandbox.monite.com/v1/batch_payments' \
     -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 '{
           "payment_method": "us_ach",
           "payer_bank_account_id": "<<ID of the entity bank account>>",
           "payment_intents": [
             {
               "object": {
                 "type": "payable",
                 "id": "<<ID of the payable>>"
               },
               "recipient": {
                 "type": "counterpart",
                 "id": "<<ID of the counterpart>>",
                 "payout_method": "paper_check"
               }
             },
                
             // other payments
             ...
           ]
         }'

The key fields in the request are:

• payment_method - must be "us_ach".
• payment_intents[].recipient.payout_method - must be paper_check.

Other fields:

• payer_bank_account_id - the ID of the entity's US bank account to withdraw the funds from. This bank account must be verified.
• payment_intents - an array containing information about the payables that the entity wants to pay. The currency of each of these payables must be USD.
  • object.type - must be "payable".
  • object.id - the ID of a payable to pay.
  • recipient.type - must be "counterpart".
  • recipient.id - the ID of the counterpart that issued the payable specified by object.id and to whom the entity wants to send a paper check. This counterpart must be US-based.

Combining paper checks and ACH Direct Debit payments

An entity can use a combination of ACH Direct Debit and paper check payouts within a single /batch_payment request. For example, use ACH Direct Debit to pay some of the payables listed, and paper checks to pay other payables.

3. Track the payment status

Batch payment statuses

A batch payment goes through several statuses, some of which also reflect the statuses of the individual payment intents within this batch payment.

Check the batch payment status

Assuming you have subscribed to the payment webhooks, you will receive the batch_payment.status_updated and payment_intent.status_updated webhooks whenever the payment status is updated.

In the case of the batch_payment.status_updated webhook, the event payload contains the batch payment ID (object_id) and the ID of the entity that made this payment (entity_id):

{
  "id": "dc84fcee-3788-436e-9e7a-31d9e335925a",
  "created_at": "2024-03-04T20:06:48.593225+00:00",
  "action": "batch_payment.status_updated",
  "api_version": "2024-01-31",
  "entity_id": "bebe3e93-3984-4a07-b2cc-897766c6f8d2",
  "name": "batch_payment_status_updatedd",
  "object": null,
  "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "batch_payment",
  "significance": "medium",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}

Use these IDs to query the new status of the batch payment by calling GET /batch_payment/{id}:

curl 'https://api.sandbox.monite.com/v1/batch_payments/3fa85...fa6' \
  -H 'X-Monite-Version: 2024-01-31' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The returned batch payment object contains the statuses of the batch payment itself and its individual payment intents, among other details. If the batch payment status is partially_successful or failed, the error fields contain any errors that occurred while processing the batch payment as a whole and individual payment intent.

{
  "id": "6a0611dc-73a9-4bf2-9d90-0a78d1b0770a",
  "created_at": "2023-10-03T13:17:17.400Z",
  "payment_method": "us_ach",
  "payer_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

  "payment_intents": [
    {
      "id": "3900fc5b-2ff1-41a4-a958-e2139f779c81",
      "created_at": "2023-10-03T13:17:17.400Z",
      ...
      "status": "failed",
      "error": {
        "message": "Error message goes here"
      }
    },
    ... // Other payment intents
  ],
  ...

  "status": "partially_successful",
  "error": null
}