For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sign inBook a demo
HomeGuidesAPI ReferenceGlossary
HomeGuidesAPI ReferenceGlossary
  • Home
    • Overview
      • Overview
      • Bank Accounts
      • Checks
      • Plaid Integration
      • Bring Your Own Payments
      • Mercoa Wallet
    • Testing and Errors
Logo
Sign inBook a demo
On this page
  • API Reference
  • Key Features
  • Allowed and Blocked Payment Flows
  • Example: Creating a Wallet Payment Method
  • Wallet Balance Management
  • Wallet Onboarding & Usage Guide
  • 1. Enable Wallet Payment Methods
  • 2. Create a Wallet Payment Method
  • 3. Fund the Wallet
  • 4. Check Wallet Balance
  • 5. Withdraw funds
  • 6. Paying Invoices Using Your Mercoa Wallet
HomePayment Methods

Mercoa Wallet

Was this page helpful?
Previous

Testing and Errors

Next
Built with

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}'
Try it

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}'
Try it

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}'
Try it

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>"
Try it

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}'
Try it

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}'
Try it