一步步教你接入 Crypto Payment API 实现链上收款

OxaPay Crypto Payment API 让在线收款像调用几个接口一样简单。本文按照“原理 → 实操 → 安全 → 上线”的逻辑，手把手带你完成加密货币支付接入。关键词包括：加密货币支付、Crypto Payment API、链上收款、Webhook、Sandbox 测试、USDT 收款、去中心化支付等，文中已自然融入。

1 加密货币支付 API 到底解决了什么问题？

传统链上收款需自建钱包、跟踪交易哈希、确认到账，流程繁琐且容易出错。Crypto Payment API 把这一套封装为“一句话”调用：

自动生成唯一收款地址/链接
实时通知支付状态
自动更新订单
开发者不用再和区块链底层打交道，前端一键展示，后端轻松收款。

2 OxaPay 方案的优势亮点

无 KYC 快速注册：邮箱或 Telegram 一键，隐私保护友好
统一接口：BTC、ETH、USDT（多链）、USDC 等主流币一次接入
多环境支持：Sandbox 测试网 → 生产网无缝切换
官方插件：WooCommerce、WordPress、EasyDigitalDownloads 已就绪，零代码开箱即用
webhook 秒级通知：上线即享“到账 → 发货”全自动化体验

3 上线前做好 4 项配置

3.1 生成 API Key

注册 OxaPay → Dashboard → Merchant API → Generate API Key
勾选所需币种，务必保管 key，禁止前端泄露。

3.2 全局参数

剩余可选：订单有效期（lifeTime）、地址手续费由谁承担（feePaidByPayer）、小额度缺口容忍（underPaidCover，如 5%）。

3.3 单笔覆盖

若部分订单需特殊设置，可在 createInvoice 请求里直接用 JSON 覆盖全局配置：

{
  "amount": 49.99,
  "currency": "USDT",
  "lifeTime": 30,
  "underPaidCover": 10,
  "feePaidByPayer": true
}

3.4 IP 白名单 + HTTPS 强制

生产系统务必开启官方白名单及 HTTPS，拒绝明文传输。

4 十个步骤完成集成（含代码示例）

步骤	目标	关键字段 / API 方法
1	生成订单	`POST /merchant/invoice`
2	获取支付链接	`payLink`
3	前端展示	按钮跳转或直接 iFrame
4	接收实时状态	`callbackUrl`（Webhook）
5	验证来源	`X-Webhook-Secret`
6	更新订单状态	据 `trackId / orderId` 入库
7	发货 or 激活会员	业务逻辑
8	异常处理	`underPaid / expired`
9	Sandbox 回归	`https://sandbox.oxapay.com/...`
10	生产上线	替换正式 API Key

👉 点此查看 Sandbox 实战视频，边看边敲，不再踩坑！

Python 极简示例

import requests
payload = {
    "merchant": "YOUR_API_KEY",
    "amount": 29.9,
    "currency": "USDT",
    "orderId": "sdk-demo-001",
    "callbackUrl": "https://yoursite.com/webhook",
    "returnUrl": "https://yoursite.com/thankyou"
}
res = requests.post("https://api.oxapay.com/merchant/invoice", json=payload)
print(res.json()["payLink"])

拿到 payLink 直接给用户，即完成收款。

5 前端如何优雅展示支付入口？

重定向法：后端返回 payLink，前端 location.href = payLink
弹窗法：将支付页嵌入 Modal/iframe，提升品牌一致性
按钮文案：推荐“立即使用加密货币支付 / Pay with Crypto”——语义清晰、CTR 高。

6 用 Webhook 做链上状态实时同步

样本回调 JSON：

{
  "trackId": "eqv712x",
  "status": "paid",
  "amount": "29.90",
  "currency": "USDT"
}

常见状态	业务动作示例
waiting	展示“等待支付”动画
confirming	提示“区块确认中”
paid	解锁课程、发确认邮件
underPaid	引导补足差价
expired	提示订单已超时

Python Flask 校验示例：

if request.headers.get('X-Webhook-Secret') != WEBHOOK_SECRET:
    abort(403)

HTTPS + Secret + IP 白名单，三重保险。

7 安全加固清单

✅ API Key 存放服务器环境变量，禁止出现在前端 Git 仓库
✅ Webhook URL 强制 HTTPS，内网不可访问
✅ 双重校验 trackId 与数据库一致性，防伪造
✅ 记录日志 30 天，便于追溯纠纷

👉 一步搞定加密支付风控秘籍，点击查看

8 Sandbox 全链路演练

Dashboard 切 Sandbox → 生成 Sandbox Key
请求 https://sandbox.oxapay.com/merchant/invoice
浏览器打开 payLink 模拟支付
手动触发 underPaid / expired 场景
回归测试通过 → 平滑切到生产

在 Sandbox 上多踩坑，频发测试，生产环境就不会心惊胆战。

9 进阶扩展能力

静态地址：为 VIP 用户绑定固定地址，方便月付或打赏
Swap API：让用户付 BTC，你实时收 USDT，规避币价波动
批量出款（Payout API）：对空投活动、返现返现、UGC 内容创作者批量发放奖励

10 常见问题 FAQ

Q1 我只会建站，不懂区块链，能接入吗？
A：零门槛。用 WordPress/WooCommerce 插件即可开始，仅需 10 分钟完成部署。

Q2 不想让顾客自己挑币种，只想收 USDT 可以么？
A：在后台仅启用 USDT，即可屏蔽其他币种，接口创建时无需额外字段。

Q3 付款超时怎么办？
A：默认 30 分钟失效，可在订单详情页手动延长；或设置更长的 lifeTime 解决。

Q4 Webhook 延迟大吗？
A：多数公链平均 1–3 秒即可收到首次通知，BTC 网络确认后自动转为 paid。

Q5 没有公司，能注册并收款吗？
A：可以。个人开发者亦可申请，无纸质审核。

写在最后

现在你已经从原理、配置、代码、测试到上线，完整掌握了 Crypto Payment API 接入套路。
记住两个要点：第一，先在 Sandbox 跑通所有场景；第二，保护好 API Key 与 Webhook 安全。搞定这两件事，剩下的就是把支付入口放到结账页，让你的业务向全球接受加密货币支付迈出真正一步。