johnalbertini14-glitch Mercury Payments
Pay invoices via the Mercury Bank API.
Prerequisites
- Mercury API token with write access
- Auth header:
Authorization: Bearer <token> - Base URL:
https://api.mercury.com/api/v1
Account Discovery
curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/accounts"
Returns all accounts with IDs, names, and last-4 digits.
Payment Flow
1. Get explicit approval
NEVER send money without explicit approval. Present: amount, recipient, invoice #, account.
2. Check for existing recipient
curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/recipients" \
| python3 -c "import sys,json; [print(r['name'],r['id']) for r in json.load(sys.stdin)]"
3. Create recipient if needed
curl -s -X POST "https://api.mercury.com/api/v1/recipients" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Vendor Name",
"emails": ["vendor@example.com"],
"defaultPaymentMethod": "ach",
"electronicRoutingInfo": {
"accountNumber": "...",
"routingNumber": "...",
"electronicAccountType": "businessChecking",
"address": { "address1": "...", "city": "...", "region": "...", "postalCode": "...", "country": "US" }
}
}'
4. Send payment
ACH:
curl -s -X POST "https://api.mercury.com/api/v1/account/{accountId}/transactions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"recipientId": "...",
"amount": 500.00,
"paymentMethod": "ach",
"note": "INV-001 - Vendor - Jan 2025",
"idempotencyKey": "vendor-inv001-jan2025"
}'
Domestic wire:
curl -s -X POST "https://api.mercury.com/api/v1/account/{accountId}/transactions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"recipientId": "...",
"amount": 1000.00,
"paymentMethod": "domesticWire",
"purpose": {"simple": {"category": "vendor", "additionalInfo": "Invoice INV-001 Service Description"}},
"note": "INV-001 - Vendor - Jan 2025",
"idempotencyKey": "vendor-inv001-jan2025"
}'
Wire purpose is required. Format: {"simple": {"category": "<cat>", "additionalInfo": "<desc>"}}
Categories: employee, landlord, vendor, contractor, subsidiary, transferToMyExternalAccount, familyMemberOrFriend, forGoodsOrServices, angelInvestment, savingsOrInvestments, expenses, travel, other
5. Notify bookkeeper and vendor
After payment, email the bookkeeper and reply to the vendor with payment confirmation and invoice attached.
Querying Transactions
# Recent (~30 days default)
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.mercury.com/api/v1/account/{accountId}/transactions?limit=500"
# Date range (required to go further back)
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.mercury.com/api/v1/account/{accountId}/transactions?start=2025-01-01&end=2025-01-31&limit=500"
Without start/end, the API only returns ~30 days of history.
Idempotency Keys
Use descriptive keys: {vendor}-{invoice}-{period} (e.g., acme-inv123-jan2025). Prevents duplicate payments on retry.
Payment Checklist
- Payment explicitly approved
- Invoice PDF downloaded
- Recipient exists (or created)
- Payment sent with correct amount, method, and note
- Bookkeeper notified with invoice attached
- Vendor notified with invoice attached