接入指南

欢迎使用币趣支付！本指南将带您了解如何快速接入我们的 API。您可以利用这些接口创建支付/收款订单、发起代付/付款请求、处理退款以及获取实时汇率。

我们强烈建议您优先使用我们提供的 官方 SDK 进行对接，以免去复杂的加密签名处理。

1. 准备工作

在开始对接前，请确保您已经：

1. 注册并登录商户后台。
2. 提取您的 商户号 (Merchant ID)。
3. 根据您业务选择的鉴权方式获取 API 证书 或 API Key。
4. 【推荐】下载对应语言的官方 SDK（已包含所有底层签名和验签逻辑）：
   • Java SDK 与 Demo

2. API 鉴权与签名机制

为了保证资金交互的安全，所有核心 API 请求均需进行强鉴权。目前币趣支付支持 两种签名方式：

• API 证书签名 (推荐)：使用平台颁发的证书与商户私钥对请求进行非对称加密签名，安全性最高，适合生产环境核心交易。
• API Key 签名：使用通用的 API Key 进行哈希计算生成签名，集成成本低，适合轻量级接入。

签名提示

• 如果您使用 SDK，无论上述哪种签名方式，您只需在初始化时配置好证书路径或 API Key，SDK 将自动完成发送请求时的加签以及接收回调时的验签。
• 如果您不使用 SDK 而是 原生 HTTP 请求对接，您需要在 HTTP 的 Header 中手动拼接并计算 X-Signature 等签名标头。详细的加密算法与拼接规则，务必参考：签名请求与鉴权机制。

3. 核心业务接入流程

一旦完成鉴权配置，您即可开始对接实际的业务流。

重要：非 SDK 接入前置必读

如果您未采用官方 SDK，而是通过您自己的 HTTP 请求代码库对接，在查阅下方的业务 API 之前，请务必先学习以下基础机制，它们将贯穿每一个业务接口：

1. 如何发起请求（各类 Header 要求）：👉 API 鉴权与请求头规范
2. 如何对请求签名（防篡改的核心摘要算法与编码）：👉 签名请求与底层运算流程

请按您的场景阅读相应的业务接口：

场景 A：支付 / 收款 (Invoice)

实现在您的平台或应用内发起订单，由币趣支付进行收款的业务闭环。

1. 发起支付：调用接口创建支付票据 👉 创建 Invoice
2. 异步回调：接收用户付款成功的异步结果通知 👉 Webhook Invoice 通知
3. 主动查询：(非必选) 主动获取该笔订单当前状态 👉 查询 Invoice

场景 B：代付 / 付款 (Payout)

实现您从商户余额中向目标用户/商户发送资金的业务闭环。

1. 发起代付：提交代付请求 👉 创建 Payout
2. 异步回调：接收代付成功或失败的异步结果通知 👉 Webhook Payout 通知
3. 主动查询：(非必选) 主动获取该笔代付的处理状态 👉 查询 Payout

---

4. Webhook 回调与验签处理

由于真实的链上调用以及确认需要时间，支付和代付的结果均是异步的。您的系统不仅要能接收币趣的 Webhook 通知，更关键的是——为了防止伪造支付成功回调，您必须对接收到的 Webhook请求 执行严格的签名验证！

如果您计划纯手动校验（未使用 SDK 解析），请认真查阅专门的： 👉 完整 Webhook 验签图文教程与原理详注

Webhook 对接提示

1. 切勿使用解析后的 JSON 对象验签：参与验证签名的数据源必须是服务器接收到的 原始未被任何框架篡改的 HTTP Body 文本流。
2. 正确响应：Webhook 验签通过完成本地业务逻辑后，务必向系统返回 正文为空的 HTTP 200 状态码。若返回其他状态，系统将判定推送失败并触发后续的指数退避重试机制。
3. 防并发与幂等：网络抖动或重试会导致相同通知到达多次。请利用订单编号等字段实现本地逻辑的幂等更新，防止多次加款/扣款。

5. 上线前检查单

正式投产发布前，请开发与测试人员最后核对：

• [ ] API 请求的发起是否正常通过了证书或 API Key 验签？
• [ ] 异步 Webhook 的证书/Key 验签逻辑是否已经跑通并能拦截非法请求？
• [ ] HTTP 200 Webhook 正确回执是否已经设置到位？
• [ ] 对应业务的数据处理锁机制或防并发方案是否就绪？

6. 获取技术支持

如果您在调用期间遇到未知问题，请首先比对：👉 错误码参考手册 如因环境等其他复杂原因受阻，请记录您的商户号，并抓取请求头、响应报文等关键日志，联系我们的网站客服转技术支持部门，我们将迅速为您排查。