Sign in
支付与提现/Payout API

提现 API

通过编程方式将商户余额提现到任意区块链地址。

提现 API 让您可以通过编程方式将商户余额发送到任意区块链地址。

所有提现端点必须使用单独的 Payout API key 来生成 sign 签名。该密钥与常规 API key 不同,需在项目设置中单独生成。

创建提现

从商户余额创建一笔提现请求。

POST/v1/payout

请求参数

字段类型必需描述
currencystring提现币种(详见 References
networkstring网络代码(详见 References
amountstring提现金额
to_addressstring收款方区块链地址
order_idstring幂等性键——在项目内唯一。携带相同 order_id 的重复 POST 不会创建新提现,而是返回已存在的提现
url_callbackstring提现 webhook URL。不传则不发送任何 webhook
memostring | nulldestination tag / memo。目前仅 TONSOL 网络使用;最大 255 字符
from_currencystring提现时从该源余额扣款并自动兑换为 currency。允许您以波动性资产(BTCETH、…)发起提现,同时将余额保留为稳定币 USDT —— 您无需自己持有波动性加密货币。传入 "USDT" 即可从 USDT 余额扣款
fee_optionstring手续费扣除方式。deduct(默认)——网络与平台手续费从 amount 中扣除,收款方收到 amount - feesadd——手续费在 amount 之外加收,从商户余额扣除 amount + fees,收款方恰好收到 amount

幂等性。 在同一项目内,提现按 order_id 唯一。携带相同 order_id 的重复 POST安全的——API 会返回已存在的提现而不会创建副本。生产环境务必传入 order_id

请求示例

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

响应示例

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

手续费。 默认 fee_option: deduct —— 网络与平台手续费从 amount 中扣除(收款方收到 amount - fees)。传 fee_option: add 则手续费在 amount 之外加收 —— 收款方恰好收到 amount,商户被扣 amount + fees

计算提现

不创建提现 也不扣除余额的情况下,估算提现金额与手续费。可在用户确认之前展示其将实际收到(或支付)的精确金额。

POST/v1/payout/calc

请求参数

创建提现 完全一致 —— 字段相同,签名相同。order_idurl_callbackto_addressmemo 也会被接受但被忽略:不会持久化任何提现,也不会发送 callback。

请求示例

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

响应示例

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

仅预览。 该接口是只读的 —— 不会扣除任何余额,也不会创建提现记录。可以随意调用,在你的界面中渲染手续费明细。

提现状态

获取一笔提现请求的当前状态。

GET/v1/payout/status/{uuid}

路径参数

字段类型必需描述
uuidstring提现 UUID(创建时来自 result.uuid

响应示例

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

该 GET 请求使用空请求体计算签名: hash_hmac('sha256', base64_encode(''), $apiKey)

响应字段

POST /v1/payoutGET /v1/payout/status/{uuid} 返回的 result 包含以下字段:

字段类型描述
uuidstring系统分配的提现 UUID
order_idstring您提供的提现标识符(项目内唯一)
statusstring当前提现状态(详见下文)
currencystring提现币种
networkstring网络代码
amountstring请求的提现金额
merchant_amountstring从商户余额扣除的金额
network_amountstring实际链上发送的金额(扣除网络与平台手续费后)
amount_usdstring提现金额的美元等值
to_addressstring收款方区块链地址
memostring | nulldestination tag / memo(TON、SOL)。其他网络为 null
txidstring | null链上交易哈希。提交链上前为 null
block_numberint | null交易所在区块高度。包含进区块前为 null
error_typestring | nullstatus = failed 时的失败原因(详见下文 Error types);其他情况为 null
created_atstring (ISO 8601)提现创建时间
updated_atstring (ISO 8601)状态最近一次更新时间
from_currencystring | null使用自动兑换时,提现实际扣款的源余额(例如 BTC 提现的 USDT)。未发生兑换时为 null
debited_amountstring | null转换后实际从源余额扣除的金额。仅在使用自动转换时存在
debited_currencystring | nulldebited_amount 对应的扣款币种

提现状态值

status 字段可取以下值:

状态描述
pending已创建,等待处理
completed已成功完成 — txid 已设置
failed发送失败 — 详情见 error_type
cancelled已取消

错误类型

status = failed 时,error_type 字段说明失败原因:

代码描述
aml_risk提现被 AML 风控拦截(收款地址被标记为高风险)

Webhook 通知

当提现的 status 发生变化时,系统会向创建提现时传入的 url_callback 发送 POST webhook。如果未提供 url_callback,则不会为该笔提现发送任何 webhook。

  • 方法: POST
  • Content-Type: application/json
  • 签名: 请求体中的 sign 字段,使用 Payout API key(与签名提现请求时使用的密钥相同)计算。

载荷与 GET /v1/payout/status/{uuid}result 对象一致,并额外包含一个 sign 字段用于校验。

载荷

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

校验签名:支付 webhook 算法相同,但使用 Payout API key 而不是普通 API key。移除 sign 字段,将剩余载荷转为 JSON、Base64 编码,再计算 hash_hmac('sha256', $base64, $payoutApiKey) 与收到的 sign 比较。