掌握加密货币收款：使用 Cryptopay API 创建与管理 Invoice 的完整指南

Invoice 的本质：加密支付的“账单”

Invoice 是告知用户应支付多少加密货币、向哪个地址支付，并且指定有效时间的完整订单。通过接口生成的每一条记录都关联一个 唯一收款地址、预设金额（可用法币或数字资产计价）与 10 分钟 的汇率锁定期。

在近一年 加密货币支付 激增 300% 的背景下，快速、无错地判定交易状态成为刚需；Invoice 正好扮演了这一角色：

依靠链上地址提示用户支付
通过回调驱动售后流程
10 分钟锁价避免币价波动导致账不对款

👉 想了解如何零代码对接并立即看到收款实时推送？

Invoice 生命周期：从生成到完结

使用 Cryptopay 创建 Invoice，生命周期则清晰如下：

new：接口返回新地址与金额，用户尚未付款。
transaction_created：监听到第一笔链上付款，但未确认。
transaction_confirmed：获得足够网络确认，正式 completed。
expired：超过 10 分钟，回到 expired（仍可收后续付款但需补差价）。
unresolved：因 late、overpaid、underpaid 等异常进入人工审核或自动规则处理，最终可为 completed 或 refunded。

回调机制：让业务逻辑闭环

每笔交易触发以下两次典型回调，Webhook 地址需提前配置：

transaction_created —— 网络发现付款广播
transaction_confirmed —— 区块确认深度合规

当 Invoice 状态发生改变，服务器即可自动发货、开卡或解锁服务。

金额与币种：法币计价 & 自动兑换

Invoice 支持法币: 编码传 USD、EUR 等；也支持直接传 BTC、USDT(ERC-20) 等币名。设值法币时，系统按创建瞬间锁定的汇率返回需支付的 加密货币 数量，避免下单至付款的 10 分钟内市价差造成争议。

示例场景：

用户结账 100 USD ⇒ 系统根据 BTC 市价扣回 0.0036 BTC；10 分钟后付款到账，BTC 价格暴跌 3%，钱包收到的仍是 0.0036 BTC，商户风险锁定。

超时与异常处理：late、overpaid、underpaid 轻松治理

支付延迟或转账手动输错金额会触发 unresolved。

late：用户超时付款 → 地址失效，可在后台配置“继续接收”或“自动退款”。
overpaid：多付 0.00001 BTC 亦会报错，需生成退款地址；
underpaid：少付会拉成待补足状态，可结合余额差价再推一次新 Invoice。

路径：Integration > API > 处理 unresolved invoices → 可选“自动确认零头”或“一律退款”。

三步生成 Invoice

POST /invoices 发送金额、币种、回调地址、元数据。
取得 response 中的 收款地址 与 invoice_id；将其包装成二维码或粘贴到结账页。
等待 Webhook：首次收到 transaction_created，二次收到 transaction_confirmed 即发货。

Python 示例（已脱敏）：

import requests
headers = {"Authorization": "Token YOUR_API_TOKEN"}
data = {
    "price_amount": 100,
    "price_currency": "USD",
    "pay_currency": "BTC",
    "callback_url": "https://your.site/webhook"
}
resp = requests.post("https://cryptopay.io/api/v1/invoices/", json=data, headers=headers)
invoice = resp.json()
print(invoice["address"])  # 用户需向该地址支付

👉 要是不懂前端集成？一文教你 30 分钟把「支付宝、微信」替换成「加密支付」

监控与调试：让每一分钱都有迹可循

开发者在沙盒环境（sandbox.cryptopay.io）可模拟 late、overpaid 等状态，真实付款前验证回调逻辑。
提示：沙盒会自动生成虚假区块确认，3 秒即可走完确认流程，方便单元测试。

常见问题（FAQ）

Q1：10 分钟太短，可否延长锁价时间？
A：目前固定 10 分钟。如需更长锁价，可与商务洽谈开通定制费率（需高交易量背书）。

Q2：用户用闪电网络付款会被识别吗？
A：当前仅支持主网 L1 及指定 ERC-20 代币；闪电网络归集会暂挂 unresolved-late，建议引导到链上地址。

Q3：如何自行标记 order_id，避免重复(webhook)订单？
A：可在创建时通过 metadata 字段透传商户内部订单号，回调原样返回，方便你 SQL 惟一索引删重。

Q4：生成的地址反复收到多笔交易怎么办？
A：Invoice 走哈希匹配，一笔 Invoice 仅关注 首次入账；同一地址二次打款即视作 unresolved-overpaid。

Q5：已过期 Invoice 能否手动作废？
A：可调用 PATCH /invoices/{invoice_id} 设置 cancelled 状态；若用户仍汇款，则按 unresolved 规则处理。

Q6：多长区块确认才变成 completed？
A：BTC 与 ETH 默认 2 确认，USDT(ERC-20) 需 12 个确认。高风险币或自定义确认数可在 Dashboard 调整。

结语

通过 Invoice 与回调，把 加密货币支付 这一看似复杂的流程拆成轻量 API：

2 分钟 生成收款地址
10 分钟 内锁价防波动
2 条 Webhook 驱动商单完成

只要掌握以上规则，就能让传统电商、SaaS、游戏服务器计费、NFT 预售场景无缝融入全球加密经济。