如何发起数字货币提现（Coin Withdrawal）：API 全流程实操指南

想让你的用户在区块链上 30 秒内完成提现？本文将以开发者视角，手把手拆解 Cryptopay API 中最常见的提现接口调用。全文包含参数差异、手续费策略、XRP/XLM 特殊字段、以及可直接上手的 curl 模板，帮助你用最少代码实现最安全的币种转出。

提现前的 5 个必备字段

发起任何一笔数字货币提现，都必须一次性准备好以下信息：

参数示例	解释
支付金额（`charged_amount_to_send/charged_amount`）	欧元 100
支付币种（`charged_currency`）	默认 EUR
加密货币类型（`received_currency` + `network`）	BTC-Bitcoin
接收地址（`address`）	例如 `3QJ...`
可选唯一识别码（`custom_id`）	订单 113562013

特殊币种：XRP 与 XLM 的附加字段

XRP 与 XLM 属于托管钱包模式，同一地址服务多位用户；为了区分是谁的转账，需要额外在地址后拼一个参数：

XRP：在地址后追加 ?dt=<destination_tag>
XLM：在地址后追加 ?memo=<memo_id>

注意：如果收款方使用 独立地址（仅服务一个人），把 destination_tag 或 memo_id 填 0，但千万别漏填，以免资金永远无法到账。

错误示例
把 destination_tag 留空→区块链网络拒绝交易。

正确示例
[email protected]?dt=12345

两种金额字段的本质区别：如何节省手续费

charged_amount 与 charged_amount_to_send 常被误用，一句话分清：

字段	谁付手续费	实际到账	推荐场景
`charged_amount_to_send`	平台库存扣除	收款人足额 100 EUR 等价 BTC	商户想“补贴”矿工费，提升体验
`charged_amount`	从指定金额内扣除	可能 <100 EUR，减去各种费	商户希望“所见即所得”到账金额

多数钱包或交易所 更偏好 charged_amount_to_send，避免用户抱怨“到账缩水”。但如果你是 SaaS 系统，采用 charged_amount 可以把成本透传给付款用户，利润更可预测。

👉 提前锁定手续费快照，避免汇率波动

完整 `curl` 请求模板（可直接粘贴测试）

curl -X POST \
https://business-sandbox.cryptopay.me/api/coin_withdrawals \
-H 'Authorization: HMAC ***' \
-H 'Content-Type: application/json' \
-H 'Date: '$(date -u +"%a, %d %b %Y %H:%M:%S GMT") \
-d '{
  "charged_currency":"EUR",
  "charged_amount_to_send":"100",
  "address":"3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC",
  "received_currency":"BTC",
  "network":"bitcoin",
  "custom_id":"113562013",
  "force_commit":false
}'

关键提示：

Sandbox 域名不含签名验证，仅供功能测试；上线时切换到生产域名并换成真实 HMAC 密钥。
若设置 "force_commit":false，30 秒内未显式 commit，请求会自动撤销，资产原路退回。

API 返回示例与未来状态流转

成功创建提现后，JSON 响应核心字段：

{
  "data": {
    "id": "c7969faa-a080-4c4d-aeaf-d631b687cc5f",
    "status": "pending",
    "txid": null,
    "charged_amount": "101.19",
    "network_fee": "0.0000054",
    "exchange": {
      "pair": "BTCEUR",
      "rate": "30797.564"
    }
  }
}

状态说明：

状态	含义
pending	平台已受理，等待签名广播
in_progress	交易已广播，未被区块确认
completed	交易已上链，不等于对方钱包到账
failed	超时、余额不足或地址格式错误，资金将在数小时内退回

常见问题（FAQ）

Q1：怎么确认网络费用足够？

调用 /api/fees 接口抓取实时矿工费区间，自定义 network_fee_level, 可以避免 网络费用过低 导致卡块。

Q2： Blockchain 浏览器未查到 txid，可能被节点延迟？

最高纪录 8 分钟 延迟属于正常；超过 1 小时请到 API 重试重发。

Q3：资金失败退款一般多久到账？

若因风控失败，原则上 2 小时内 退回；若矿工打包失败，视网络拥堵情况而定，最多 24 小时。

Q4：必须监听回调吗？

⚠️ 不保证，生产环境一定使用 轮询 + 回调双保险 来同步订单状态，避免漏单。

Q5： custom_id 重传会报错吗？

不会，平台允许重复；但若想 保证幂等，可在 custom_id 前加 YYYYMMDD 前缀。

Q6：可以同时提交多个地址批量提现吗？

不支持，API 唯一支持 单地址单笔。逻辑层可循环调用接口或通过 CSV 批量脚本自行处理。

👉 随时监控提现状态，开发者必备工具合集

结语：3 分钟上线数字货币提现的 3 步小抄

准备字段：金额、地址、币种类型无误。
选对金额参数：charged_amount_to_send 或 charged_amount 决定谁来付矿工费。
再次确认：XRP/XLM 的 destination_tag / memo_id，填 0 也需写上“0”。

只要把以上步骤装进 try-catch，你的商户后端就能在 30 秒 内稳定吐出成功的提现请求。祝你代码无 bug、到账无丢单！