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
1from mercoa import Mercoa
2from mercoa.payment_method_types import PaymentMethodRequest_Wallet
3
4client = Mercoa(
5 token="YOUR_TOKEN",
6)
7client.entity.payment_method.create(
8 entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9 request=PaymentMethodRequest_Wallet(),
10)

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

Below are the steps 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
1from mercoa import Mercoa
2from mercoa.payment_method_types import PaymentMethodRequest_Wallet
3
4client = Mercoa(
5 token="YOUR_TOKEN",
6)
7client.entity.payment_method.create(
8 entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9 request=PaymentMethodRequest_Wallet(),
10)

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
1from mercoa import Mercoa
2
3client = Mercoa(
4 token="YOUR_TOKEN",
5)
6client.entity.payment_method.wallet.add_wallet_funds(
7 entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
8 payment_method_id="pm_4794d597-70dc-4fec-b6ec-c5988e759769",
9 amount=100.0,
10 currency="USD",
11 source_payment_method_id="pm_f19d27ad-e493-4bf5-a28b-9cb323de495a",
12)

4. Check Wallet Balance

You can get your wallet balance using:

GET
/entity/:entityId/paymentMethod/:paymentMethodId/wallet-balance
1from mercoa import Mercoa
2
3client = Mercoa(
4 token="YOUR_TOKEN",
5)
6client.entity.payment_method.wallet.get_wallet_balance(
7 entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
8 payment_method_id="pm_4794d597-70dc-4fec-b6ec-c5988e759769",
9)

5. Withdraw funds

To withdraw funds from your Wallet, update the destinationPaymentMethodId:

POST
/entity/:entityId/paymentMethod/:paymentMethodId/withdraw-wallet-funds
1from mercoa import Mercoa
2
3client = Mercoa(
4 token="YOUR_TOKEN",
5)
6client.entity.payment_method.wallet.withdraw_wallet_funds(
7 entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
8 payment_method_id="pm_4794d597-70dc-4fec-b6ec-c5988e759769",
9 amount=100.0,
10 currency="USD",
11 destination_payment_method_id="pm_f19d27ad-e493-4bf5-a28b-9cb323de495a",
12)

6. Paying Invoices Using Your Mercoa Wallet

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

POST
/invoice
1import datetime
2
3from mercoa import Mercoa
4from mercoa.invoice_types import (
5 InvoiceCreationWithEntityRequest,
6 InvoiceLineItemCreationRequest,
7 PaymentDestinationOptions_Check,
8)
9
10client = Mercoa(
11 token="YOUR_TOKEN",
12)
13client.invoice.create(
14 request=InvoiceCreationWithEntityRequest(
15 status="NEW",
16 amount=100.0,
17 currency="USD",
18 invoice_date=datetime.datetime.fromisoformat(
19 "2021-01-01 00:00:00+00:00",
20 ),
21 due_date=datetime.datetime.fromisoformat(
22 "2021-01-31 00:00:00+00:00",
23 ),
24 invoice_number="INV-123",
25 note_to_self="For the month of January",
26 payer_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
27 payment_source_id="pm_4794d597-70dc-4fec-b6ec-c5988e759769",
28 vendor_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
29 payment_destination_id="pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
30 payment_destination_options=PaymentDestinationOptions_Check(
31 delivery="MAIL",
32 print_description=True,
33 ),
34 line_items=[
35 InvoiceLineItemCreationRequest(
36 amount=100.0,
37 currency="USD",
38 description="Product A",
39 name="Product A",
40 quantity=1.0,
41 unit_price=100.0,
42 category="EXPENSE",
43 service_start_date=datetime.datetime.fromisoformat(
44 "2021-01-01 00:00:00+00:00",
45 ),
46 service_end_date=datetime.datetime.fromisoformat(
47 "2021-01-31 00:00:00+00:00",
48 ),
49 metadata={"key1": "value1", "key2": "value2"},
50 gl_account_id="600394",
51 )
52 ],
53 creator_entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
54 creator_user_id="user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
55 ),
56)