HomePayment Methods

Mercoa Wallet

The Mercoa Wallet is a payment method designed for business-to-business (B2B) payments within the Mercoa platform. It enables seamless payments between payors and recipients, acting as both a funding source and a payment destination. Only one Mercoa Wallet per entity is supported.

API Reference

Key Features

  • Wallet as a Payment Method: The Mercoa Wallet is a top-level payment method, available as both a funding source and as a payment destination on invoices and transactions.
  • D+0 Transfer Speed Advantage: Wallet-to-bank payments are D+0 transfers to the vendor (same-day ACH), which is much faster than D+2 or D+3 for ordinary bank-to-bank transfers.
  • Payment Method Flexibility: Use as a funding source or payment destination for invoices.

Allowed and Blocked Payment Flows

Wallets can be used in the following payment flows only:

Source Payment MethodDestination Payment MethodAllowed?Notes
WalletBank AccountYesD+0 transfer (Same-Day ACH settlement)
Bank AccountWalletYesD+2 transfer (ACH)
CardWalletYesD+1 transfer

Note: Wallet-to-check or wallet-to-card disbursements aren’t supported.

Example: Creating a Wallet Payment Method

POST
/entity/:entityId/paymentMethod
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": "wallet"
6}'

Wallet Balance Management

  • availableBalance: The current wallet balance that is immediately available for use. This is updated when the user’s deposited funds settle, when the user withdraws funds, or when a wallet-funded invoice payment is processed.
  • pendingBalance: The current balance of the incoming wallet funds. This is updated when the user initiates a deposit, and is reset to zero once the deposit settles.

Wallet Onboarding & Usage Guide

The following steps outline how to enable, create, fund, and use a Mercoa Wallet as a payment method.
You can perform these actions via the Mercoa dashboard or directly using the Mercoa API.

1. Enable Wallet Payment Methods

In the Mercoa dashboard, enable the “Wallet” option under the Payment Methods section and click Save.

2. Create a Wallet Payment Method

In the Mercoa dashboard, navigate to your entity’s admin page and create a new wallet payment method under Payment Methods.

By API, use the Create Payment Method endpoint:

POST
/entity/:entityId/paymentMethod
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": "wallet"
6}'

Note: You may only create one Wallet payment method per entity.

3. Fund the Wallet

Wallets can be funded from a bank account or card. To add funds from a bank account:

POST
/entity/:entityId/paymentMethod/:paymentMethodId/add-wallet-funds
1curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/paymentMethod/pm_4794d597-70dc-4fec-b6ec-c5988e759769/add-wallet-funds \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "amount": 100,
6  "sourcePaymentMethodId": "pm_f19d27ad-e493-4bf5-a28b-9cb323de495a",
7  "currency": "USD"
8}'

4. Check Wallet Balance

You can get your wallet balance using:

GET
/entity/:entityId/paymentMethod/:paymentMethodId/wallet-balance
1curl https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/paymentMethod/pm_4794d597-70dc-4fec-b6ec-c5988e759769/wallet-balance \
2     -H "Authorization: Bearer <token>"

5. Withdraw funds

To withdraw funds from your Wallet, update the destinationPaymentMethodId:

POST
/entity/:entityId/paymentMethod/:paymentMethodId/withdraw-wallet-funds
1curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/paymentMethod/pm_4794d597-70dc-4fec-b6ec-c5988e759769/withdraw-wallet-funds \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "amount": 100,
6  "destinationPaymentMethodId": "pm_f19d27ad-e493-4bf5-a28b-9cb323de495a",
7  "currency": "USD"
8}'

6. Paying Invoices Using Your Mercoa Wallet

Replacing paymentSourceId with the Wallet ID lets you create invoices with Mercoa Wallet.

POST
/invoice
1curl -X POST https://api.mercoa.com/invoice \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "status": "NEW",
6  "amount": 100,
7  "currency": "USD",
8  "invoiceDate": "2021-01-01T00:00:00Z",
9  "dueDate": "2021-01-31T00:00:00Z",
10  "invoiceNumber": "INV-123",
11  "noteToSelf": "For the month of January",
12  "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
13  "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
14  "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
15  "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
16  "paymentDestinationOptions": {
17    "type": "check",
18    "delivery": "MAIL",
19    "printDescription": true
20  },
21  "lineItems": [
22    {
23      "amount": 100,
24      "currency": "USD",
25      "description": "Product A",
26      "name": "Product A",
27      "quantity": 1,
28      "unitPrice": 100,
29      "category": "EXPENSE",
30      "serviceStartDate": "2021-01-01T00:00:00Z",
31      "serviceEndDate": "2021-01-31T00:00:00Z",
32      "metadata": {
33        "key1": "value1",
34        "key2": "value2"
35      },
36      "glAccountId": "600394"
37    }
38  ],
39  "creatorEntityId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
40  "creatorUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
41}'