Creating Payouts via API

In this guide, we will be using Mercoa for AP Payments. We will not be using the frontend components or workflows.

If you plan to use Mercoa’s frontend components, check out our Frontend Integration guide.

Install SDK

$npm install --save @mercoa/javascript
># or
>yarn add @mercoa/javascript

Create the payer entity

API Reference

The payer entity is the customer who will initiate the payment of an invoice. In order to start processing payments for the customer, you will need to collect data required to run KYB.

If you do not have all the data required, you can use Mercoa’s hosted onboarding to capture it.

By using a foreignId, you don’t need to store the Mercoa entityId in your system.

You can query for entities by foreignId with:

In this example, the entityId is ent_8545a84e-a45f-41bf-bdf1-33b42a55812c

Create Representatives

API Reference

If the entity is a business, you will need to collect information about the owners and controllers of the business.

See the Business Representatives guide for more details.

Mercoa’s hosted onboarding can capture this information for you!

Accept Terms of Service

Once the entity and representatives are created, your user will need to accept the Mercoa ToS. There are a few ways to do this:

  1. Include the Mercoas ToS as part of your ToS and have the user accept the updated ToS
  2. Show the Mercoa ToS directly, and have the user accept the Mercoa ToS

Mercoa’s hosted onboarding can have the user accept the terms of service directly

Once the user has accepted the ToS, use the Accept ToS Endpoint to indicate as such.

Initiate KYB

Once all data is captured and ToS is verified, you can initiate the KYB process.

Create Payer Bank Account

The easiest way to connect the payer bank account is to use our Plaid integration

You can also create the account via API and use micro-deposits to verify it. Micro-deposits can take 2-5 days to show up in the bank account.

Create

Initiate Micro Deposits

Complete Micro Deposits

In this example, the payer’s paymentMethodId is pm_4794d597-70dc-4fec-b6ec-c5988e759769

Create the vendor entity

The next step is to create the vendor entity. This is the entity that will be paid by your customer. For a business, we require their legal business name as well as their website or description.

In this example, the vendor entityId is ent_21661ac1-a2a8-4465-a6c0-64474ba8181d

Create vendor payment method

If you have the vendor’s bank acount information, you can pre-create their payment method

Vendor bank accounts do not need to be verified.

If you don’t have the vendor’s account information, you can collect it using the entity onboarding link

In this example, the vendor’s paymentMethodId is pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18

Create and schedule the payment

The final step to make a payment is to create and schedule the invoice.

If you don’t have the paymentDestinationId, you can collect it using the payment acceptance link. The invoice needs to be set into the DRAFT or NEW state as it cannot be scheduled without a paymentDestinationId

On the deductionDate, the payment will be triggered! If the deductionDate is set to a past date or is set after the daily payments cutoff, the payment will be triggered on the next payments window.