文档 / 参考

客户端与示例

每个客户端都是一个无外部依赖的单文件。复制到项目中，即可获得请求签名、账单创建与查询以及 Webhook 校验功能。

Node.js

Node 22+。提供 CoineticClient、CoineticError 类和 verifyWebhook 函数。

下载 cryptopay.js ↓

PHP

PHP 8.1+，需要 curl 和 json 扩展。提供 \Cryptopay\Client、\Cryptopay\verify_webhook。

下载 Cryptopay.php ↓

Python

Python 3.9+，仅使用标准库。提供 CoineticClient、verify_webhook。

下载 cryptopay.py ↓

Go

Go 1.22+，仅使用标准库。包名 cryptopayclient。

下载 cryptopay.go ↓

包含哪些功能

功能	Node.js	PHP	Python	Go
请求签名	`signRequest`	`sign_request`	`sign_request`	`SignRequest`
创建账单	`createInvoice`	`createInvoice`	`create_invoice`	`CreateInvoice`
查询账单	`getInvoice`	`getInvoice`	`get_invoice`	`GetInvoice`
校验 Webhook	`verifyWebhook`	`verify_webhook`	`verify_webhook`	`VerifyWebhook`
“可以发货”的状态	`PAID_STATUSES`	`PAID_STATUSES`	`PAID_STATUSES`	`PaidStatuses`

文件名和类名等技术名称（cryptopay.*、CryptopayClient）属于历史遗留，不会更改；Node.js 和 Python 中另提供别名 CoineticClient 和 CoineticError。

四个客户端均通过同一套参考值验证

所有客户端生成的请求签名和 Webhook 签名都与参考值一致。如果您要用其他语言编写客户端，请先确保结果与参考值一致：这是排查签名错误最快的办法。

最简流程

伪代码

invoice = client.createInvoice({order_id, price_amount: "3.00", price_currency: "USD",
                                return_url: "https://shop.example/orders/42"},
                               idempotencyKey = "order-42")
redirect(invoice.checkout_url)

on POST /webhooks/coinetic (raw body!):
    event = verifyWebhook(WEBHOOK_SECRET, headers, rawBody)   # 否则返回 400/401
    if seen(event.id): return 200                             # 重复投递
    inv = client.getInvoice(event.data.invoice_id)            # 再次核实
    if inv.status in PAID_STATUSES: grantOnce(inv.order_id)
    return 200

客户端不负责的事情

不保存密钥：API 密钥和签名密钥从外部传入，例如环境变量或密钥管理服务。
不保存已处理的 X-Webhook-Id：这由您的数据库负责。
不把金额转换为数字：所有金额都是字符串。
不自动重试请求：遇到 429、5xx 和网络错误时，请使用相同的 Idempotency-Key 重试。
不能在浏览器或移动应用中使用，只能在服务器端运行：签名密钥只应保存在服务器上。