Mercury 支付技能

概述

通过 Mercury 银行 API 支付发票，通知 Zeni（记账员）及供应商，并始终附上发票 PDF 文件。

前提条件

• Mercury API Token（需写入权限）：$MERCURY_API_TOKEN 或通过 pass show 获取
• 认证方式：Authorization: Bearer （基础认证亦可：将 token: 进行 base64 编码）
• 基础 URL：https://api.mercury.com/api/v1

账户

动态发现账户 ID（请勿硬编码组织专属 ID）：

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

默认付款账户须在付款时确认。

已知收款方

请将收款方 ID 保存于您自身的安全记录中，或在运行时按收款方名称动态解析。

支付流程

1. 获取明确批准

未经授权操作员明确批准，切勿发起付款。 须向操作员清晰呈现：金额、收款方、发票编号、付款账户。

2. 下载发票 PDF

定位包含发票的邮件，将附件下载至 /tmp/ 目录。

3. 检查收款方是否已存在

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

4. 如需则创建收款方

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. 发起付款

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

境内电汇付款：

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"
  }'

电汇必须提供 purpose 字段。 格式为：{"simple": {"category": "", "additionalInfo": ""}} 可用分类包括：employee、landlord、vendor、contractor、subsidiary、transferToMyExternalAccount、familyMemberOrFriend、forGoodsOrServices、angelInvestment、savingsOrInvestments、expenses、travel、other

6. 邮件通知记账员（必须执行）

发送至您的记账收件箱（例如：bookkeeping@example.com），内容包括：

• 主题： Invoice — Paid
• 正文：付款金额、付款方式、预计到账时间
• 务必附上发票 PDF

7. 邮件通知供应商（必须执行）

如可能，请在原有邮件会话中直接回复。内容应包括：

• 付款确认信息（含金额）
• 务必附上发票 PDF
• 预计到账日期

内部转账（Mercury 账户间）

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"
  }'

必需字段：sourceAccountId、destinationAccountId、amount、idempotencyKey。 转账即时生效。响应中同时包含 creditTransaction 和 debitTransaction 对象。

查询交易记录

# 最近交易（默认约 30 天内）
curl -s -H "Authorization: Bearer $TOKEN" "https://api.mercury.com/api/v1/account/{id}/transactions?limit=500"

# 指定日期范围（可查询更早记录）
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"

注意：若未指定 start/end 参数，API 默认仅返回约 30 天内的交易记录。如需查询更久远的数据，请显式传入 start 和 end 参数。

幂等性密钥（Idempotency Keys）

建议使用具描述性的密钥格式：{vendor}-{invoice}-{period}（例如：finra-trc37332-nov2025）

检查清单

• 已获得授权操作员的明确批准
• 已下载发票 PDF
• 收款方已存在（或已成功创建）
• 已以正确金额、付款方式和备注发起付款
• 已向 Zeni 发送邮件并附上发票 PDF
• 已向供应商发送邮件并附上发票 PDF
• 已将本次付款记录至每日记忆文件中