Getting Started

Payments Only Integration

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

Mercoa has a fully documented Rest API that can be used in any language. We also have Node, Python, Go, and Java SDKs.

If you plan on using the frontend components, check out our standard 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.

POST
1curl -X POST https://api.mercoa.com/entity \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "isCustomer": true,
6  "accountType": "business",
7  "profile": {
8    "business": {
9      "legalBusinessName": "Acme Inc.",
10      "email": "customer@acme.com",
11      "businessType": "llc",
12      "phone": {
13        "countryCode": "1",
14        "number": "4155551234"
15      },
16      "website": "http://www.acme.com",
17      "address": {
18        "addressLine1": "123 Main St",
19        "city": "San Francisco",
20        "stateOrProvince": "CA",
21        "postalCode": "94105",
22        "addressLine2": "Unit 1",
23        "country": "US"
24      },
25      "taxId": {
26        "ein": {
27          "number": "12-3456789"
28        }
29      }
30    }
31  },
32  "isPayor": true,
33  "isPayee": false,
34  "foreignId": "MY-DB-ID-12345"
35}'

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:

GET
1curl -G https://api.mercoa.com/entity \
2     -H "Authorization: Bearer <token>" \
3     -d isCustomer=true \
4     -d foreignId=MY-DB-ID-12345 \
5     -d paymentMethods=true

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!

POST
1curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/representative \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": {
6    "firstName": "John",
7    "lastName": "Adams",
8    "middleName": "Quincy",
9    "suffix": "Jr."
10  },
11  "phone": {
12    "countryCode": "1",
13    "number": "4155551234"
14  },
15  "email": "john.doe@acme.com",
16  "address": {
17    "addressLine1": "123 Main St",
18    "city": "San Francisco",
19    "stateOrProvince": "CA",
20    "postalCode": "94105",
21    "addressLine2": "Unit 1",
22    "country": "US"
23  },
24  "birthDate": {
25    "day": "1",
26    "month": "1",
27    "year": "1980"
28  },
29  "governmentID": {
30    "ssn": "123-45-6789"
31  },
32  "responsibilities": {
33    "isController": true,
34    "isOwner": true,
35    "ownershipPercentage": 40
36  }
37}'

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.

POST
1curl -X POST https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/accept-tos \
2     -H "Authorization: Bearer <token>"

Initiate KYB

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

POST
1curl -X POST https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/request-kyb \
2     -H "Authorization: Bearer <token>"

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

POST
1curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/paymentMethod \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "type": "bankAccount",
6  "accountNumber": "99988767623",
7  "accountType": "CHECKING",
8  "routingNumber": "12345678",
9  "bankName": "Chase"
10}'

Initiate Micro Deposits

POST
1curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/paymentMethod/pm_4794d597-70dc-4fec-b6ec-c5988e759769/micro-deposits \
2     -H "Authorization: Bearer <token>"

Complete Micro Deposits

PUT
1curl -X PUT https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/paymentMethod/pm_4794d597-70dc-4fec-b6ec-c5988e759769/micro-deposits \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "amounts": [
6    40,
7    2
8  ]
9}'

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.

Javascript/Typescript
1const vendor = await mercoa.entity.create({
2    isCustomer: false,
3    isPayor: false,
4    isPayee: true,
5    accountType: Mercoa.AccountType.Business,
6    foreignId: "YOUR_DATABASE_ID",
7    profile: {
8        business: {
9            legalBusinessName: "Acme Inc.",
10            website: "http://www.acme.com",
11            description: "Consulting Services",
12        }
13    }
14});

Create vendor payment method

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

Javascript/Typescript
1const vendorPaymentMethod = await mercoa.entity.paymentMethod.create(vendor.id, {
2  type: Mercoa.PaymentMethodType.BankAccount, //'bankAccount'
3  accountNumber: '98766544354',
4  routingNumber: '12345678',
5  bankName: 'Bank of America',
6  accountType: Mercoa.BankType.Checking, //'CHECKING'
7});

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

Create and schedule the payment

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

Javascript/Typescript
1const invoice = await mercoa.invoice.create({
2  status: Mercoa.InvoiceStatus.Scheduled,//'SCHEDULED',
3  payerId: payer.id,
4  creatorEntityId: payer.id,
5  vendorId: vendor.id,
6  amount: 1000,
7  currency: Mercoa.CurrencyCode.Usd,//'USD',
8  invoiceDate: '2021-01-01',
9  dueDate: '2021-01-15',
10  deductionDate: '2021-01-13',
11  paymentSourceId: payerPaymentMethod.id,
12  paymentDestinationId: vendorPaymentMethod.id
13});

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.

Built with