Mercury Payments Skill

Overview

Pay invoices via Mercury bank API, notify Zeni (bookkeeper) and the vendor, and always attach the invoice PDF.

Prerequisites

• Mercury API token (write access): $MERCURY_API_TOKEN or pass show <vault-path>
• Auth: Authorization: Bearer <token> (Basic auth also works: token: base64)
• Base URL: https://api.mercury.com/api/v1

Accounts

Discover account IDs dynamically (do not hardcode organization-specific IDs):

curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/accounts"

Default payment account should be confirmed at payment time.

Known Recipients

Keep recipient IDs in your own secure records or resolve by recipient name at runtime.

Payment Flow

1. Get explicit approval

NEVER send money without explicit approval from the authorized operator. Present: amount, recipient, invoice #, account.

2. Download the invoice PDF

Find the invoice email, download the attachment to /tmp/.

3. Check for existing recipient

curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/recipients" | python3 -c "..."

4. 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": "...",
    "emails": ["..."],
    "defaultPaymentMethod": "ach",
    "electronicRoutingInfo": {
      "accountNumber": "...",
      "routingNumber": "...",
      "electronicAccountType": "businessChecking",
      "address": { "address1": "...", "city": "...", "region": "...", "postalCode": "...", "country": "US" }
    },
    "defaultAddress": { ... }
  }'

5. Send payment

ACH payment:

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": 533.13,
    "paymentMethod": "ach",
    "note": "INV123 - Vendor - Period",
    "idempotencyKey": "unique-key-here"
  }'

Domestic wire payment:

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": 1080.00,
    "paymentMethod": "domesticWire",
    "purpose": {"simple": {"category": "vendor", "additionalInfo": "Invoice TRC37332 TRACE Data"}},
    "note": "INV-001 - Vendor - Jan 2026",
    "idempotencyKey": "unique-key-here"
  }'

Wire purpose is required. Format: {"simple": {"category": "<cat>", "additionalInfo": "<desc>"}} Categories: employee, landlord, vendor, contractor, subsidiary, transferToMyExternalAccount, familyMemberOrFriend, forGoodsOrServices, angelInvestment, savingsOrInvestments, expenses, travel, other

6. Email bookkeeper (always)

Send to your bookkeeping inbox (e.g., bookkeeping@example.com) with: - Subject: <Vendor> Invoice <number> — Paid - Body: amount, method, estimated delivery - Attach the invoice PDF

7. Email vendor (always)

Reply in the existing email thread if possible. Include: - Confirmation of payment with amount - Attach the invoice PDF - Estimated delivery date

Internal Transfers (Between Mercury Accounts)

curl -s -X POST "https://api.mercury.com/api/v1/transfer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "YOUR_SOURCE_ACCOUNT_ID",
    "destinationAccountId": "YOUR_DESTINATION_ACCOUNT_ID",
    "amount": 465.00,
    "idempotencyKey": "unique-key-here"
  }'

Required fields: sourceAccountId, destinationAccountId, amount, idempotencyKey. Transfers post instantly. Response contains both creditTransaction and debitTransaction.

Querying Transactions

# Recent (default ~30 days)
curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/account/{id}/transactions?limit=500"

# Date range (goes further back)
curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/account/{id}/transactions?start=2025-12-01&end=2026-01-18&limit=500"

Note: Without date params, API only returns ~30 days. Use start/end to go further back.

Idempotency Keys

Use descriptive keys: {vendor}-{invoice}-{period} (e.g., finra-trc37332-nov2025)

Checklist

• [ ] Explicit approval received from authorized operator

  小蔥技能站7w4.net，專業的AI技能分享平臺。

• [ ] Invoice PDF downloaded
• [ ] Recipient exists (or created)
• [ ] Payment sent with correct amount, method, and note
• [ ] Zeni emailed with invoice attached
• [ ] Vendor emailed with invoice attached
• [ ] Payment logged in daily memory file

這個Skill質量中規中矩，流程設計較為完整，提供了清晰的支付步驟指引和檢查清單，能基本滿足通過Mercury銀行付款的需求。優點是包含了多種支付方式示例，步驟邏輯清晰。不足之處在於說明不夠詳細實用，缺少實際的操作示例和遇到問題時的處理方法，整體更像是技術備忘錄而非可直接參考的操作指南，實際使用時可能還需要查閱更多資料才能順利執行。