capay/backend/README.md

Capay 一站式加密货币支付平台（自托管模板）

本仓库提供：

• 统一商户开通（简单 Merchant API）
• x402 Facilitator（EVM/Solana）配置模板
• BTCPay / Keagate 对接占位
• Webhook 聚合 /payments/webhook
• 低开销交易跟踪（免费套餐默认低频轮询）
• Nginx 反向代理与 HTTPS（Let's Encrypt）示例

目录结构

app/                       # 统一业务 API
infra/nginx/sites-enabled/ # Nginx 配置
infra/docker/              # BTCPay/Keagate 占位
x402/facilitator/          # x402 配置模板

快速开始（App）

cd app
npm install
npm run dev

服务默认监听 :3001（可在 app/.env 修改）。 通过域名访问时统一前缀为：https://capay.hao.work/backend。

免费套餐低频监控

在 app/.env 中已设置：

• TX_POLL_INTERVAL_MS=180000（3 分钟）
• MAX_TX_CHECK_PER_CYCLE=20
• MIN_CONFIRMATIONS=1

交易跟踪采用“待确认 tx 列表 + 轮询 receipt”的低开销方式。 支持多个 Alchemy 免费 key：使用 ALCHEMY_API_KEYS=key1,key2，系统会按轮询周期进行轮转调用，降低单 key 的频率。

API 说明（简化版）

域名访问时请在路径前加 /backend 前缀（例如：/backend/payments/orders）。

1) 开通商户

POST /merchants

{ "name": "Acme", "email": "ops@acme.com", "webhookUrl": "https://merchant.example.com/webhook" }

返回：merchantId、apiKey、webhookSecret

2) 创建订单

POST /payments/orders Headers: x-merchant-id, x-api-key

{ "amount": "9.99", "currency": "USD", "network": "evm:ethereum", "asset": "USDC", "description": "API Access" }

返回：订单信息与 paymentRequirementsBase64。

3) 追踪链上交易（低开销）

POST /payments/track Headers: x-merchant-id, x-api-key

{ "orderId": "ORD123", "txHash": "0x...", "network": "evm:ethereum" }

Bitcoin 示例：

{ "orderId": "ORD123", "txHash": "btc_txid", "network": "btc:mainnet" }

4) Webhook 聚合入口

POST /payments/webhook

• X-Source: keagate | btcpay | x402
• Keagate 校验：x-keagate-sig（sha512 HMAC）
• BTCPay 校验：btcpay-sig（sha256 HMAC）
• x402 校验：x402-sig（sha256 HMAC）

Nginx + HTTPS（免费）

配置在：infra/nginx/sites-enabled/capay.conf

证书建议使用 certbot（Let’s Encrypt）：

apt-get update && apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d capay.hao.work -d pay.capay.hao.work -d btc.capay.hao.work

x402 Facilitator

配置文件在：x402/facilitator/，已绑定 pay.capay.hao.work，并写入 Alchemy ETH RPC。

Bitcoin 节点（Alchemy）

默认使用 ALCHEMY_BTC_API_KEY(S) 或 BTC_RPC_URL(S) 来访问 Bitcoin 主网 RPC。 /payments/track 的 network 统一使用 btc:mainnet。

生产建议

• 把 .env 中的密钥替换为强随机值
• 生产环境建议使用数据库（PostgreSQL/MySQL）替换本地 JSON
• 重要订单建议提高 MIN_CONFIRMATIONS
• Webhook 需做好幂等与重试