Copay 商户接入指南
面向商户运营与客服同事的使用指南。开发者对接请看 API 开发者手册。
一、创建收款订单
- 调用建单接口传
amount(你要净收的金额),系统返回payable_amount(= amount + 手续费,付款人实际要支付的金额)。 - ⚠️ 最常见错误:把
amount展示给付款人。订单金额容差为 0,少付一分都无法完成——展示给付款人的必须是payable_amount。 - 订单默认有效期 30 分钟(建单时可通过
expired_in自定义),超时未支付自动过期。
二、托管支付页(推荐)
- 建单响应中的
checkout_url是 Copay 托管的支付页:金额、收款地址、二维码、倒计时、支付状态自动刷新,均由我们保证准确。 - 把链接发给付款人即可,无需自建支付界面;也可继续使用响应中的原始字段自行渲染。
三、接收回调(Webhook)
- 商户后台 → 开发者 → Webhook,添加你的接收 URL,订阅
order.status.update(收款)/payout.status.update(提现)。 - 回调为 POST,携带
X-Webhook-Signature(HMAC-SHA256)与X-Webhook-Timestamp头,建议验签。 - 你的接口需返回 HTTP 2xx;非 2xx 或超时我们将自动重试 3 次。
四、常见问题
没收到回调? 按顺序自查:
- Webhook 是否已配置并订阅对应事件;
- 订单是否发生了状态变化——仅建单未支付不会产生回调,支付成功或过期才会推送;
- 你的接收端是否返回了 2xx。
付款人少付/多付了? 订单不会自动完成,请联系客服处理:Telegram @copay8888 / [email protected]。
如何测试? 建一笔小额订单实际支付;或建单后等 30 分钟,会收到"已过期"回调,可验证通道连通。
其他问题随时联系:Telegram @copay8888 · [email protected]