本页内容
创建
从代币余额向白名单钱包创建转出,选择付款网络,签名请求,并跟踪其状态。
POST/v1/withdrawals
API 密钥: Payout
交易签名并广播上链后,转出不可逆。发送前核对 destination_address 和 network——请求落入 created 后只能在执行开始前取消,而执行可能片刻之后就开始。广播之后没有追回途径,地址错了就意味着资金损失。
转出不会排进批次:请求受理后立即开始执行。之后转账多久到账,取决于付款网络当时的速度和拥堵情况。
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount |
string | 是 | 转出金额,十进制字符串(如 "100.00") |
currency |
string | 是 | 加密资产符号。凡是持有余额的资产都可转出,可选网络随资产而定(见 支持的币种) |
network |
string | 是 | 转出网络代码——TRC20、ERC20、BEP20、POLYGON、ARBITRUM、OPTIMISM、BASE、TON、AVAX、SOL 或 PLASMA。这是收款所用 13 个网络里的 11 个:NEAR 和 SUI 只收不转,它们的地址进不了白名单(见 支持的币种) |
destination_address |
string | 是 | 目标钱包地址。必须已在该商户的转出白名单上 |
external_order_id |
string | 是 | 你的付款标识(最长 200 字符),同一商户内唯一。用于幂等——同值重复调用返回已有转出,而不是再次发送 |
请求示例
{
"amount": "100.00",
"currency": "USDT",
"network": "TRC20",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"external_order_id": "payout-001"
}
代码示例
每个标签页使用配 Payout key 的官方 SDK。签名、序列化、安全重试和类型化错误都由 SDK 处理。
API_KEY_ID="rk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
BODY='{"destination_address":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9","network":"TRC20","currency":"USDT","amount":"50.00","external_order_id":"payout-123"}'
TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/withdrawals '' "$BODY_HASH" \
| openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)
curl -sS https://api.paymos.io/v1/withdrawals \
-H "Authorization: HMAC-SHA256 $API_KEY_ID:$SIGNATURE" \
-H "X-Request-Timestamp: $TS" \
-H "Content-Type: application/json" \
-d "$BODY"
import { Paymos, externalOrderId } from '@paymos/sdk';
const paymos = new Paymos({
apiKey: process.env.PAYMOS_PAYOUT_KEY,
apiSecret: process.env.PAYMOS_API_SECRET,
});
const withdrawal = await paymos.withdrawals.create({
destinationAddress: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
network: 'TRC20',
currency: 'USDT',
amount: '50.00',
externalOrderId: externalOrderId('payout'),
});
console.log(withdrawal.withdrawalId, withdrawal.status);
import os
from paymos import Paymos
paymos = Paymos(
api_key=os.environ["PAYMOS_PAYOUT_KEY"],
api_secret=os.environ["PAYMOS_API_SECRET"],
)
withdrawal = paymos.withdrawals.create(
destination_address="TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
network="TRC20",
currency="USDT",
amount="50.00",
external_order_id="payout-001",
)
print(withdrawal["withdrawal_id"], withdrawal["status"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;
use Paymos\IdempotencyKey;
$paymos = new Client(new ClientConfig(
getenv('PAYMOS_PAYOUT_KEY'),
getenv('PAYMOS_API_SECRET')
));
$withdrawal = $paymos->withdrawals()->create(array(
'destination_address' => 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
'network' => 'TRC20',
'currency' => 'USDT',
'amount' => '50.00',
'external_order_id' => IdempotencyKey::externalOrderId('payout'),
));
echo $withdrawal['withdrawal_id'] . ' ' . $withdrawal['status'];
package main
import (
"context"
"fmt"
"os"
paymos "github.com/Paymos-labs/go-sdk/v2"
)
func main() {
client, err := paymos.NewClient(os.Getenv("PAYMOS_PAYOUT_KEY"), os.Getenv("PAYMOS_API_SECRET"))
if err != nil {
panic(err)
}
withdrawal, err := client.Withdrawals.Create(context.Background(), paymos.CreateWithdrawalParams{
DestinationAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
Network: "TRC20",
Currency: "USDT",
Amount: "50.00",
ExternalOrderID: "payout-001",
})
if err != nil {
panic(err)
}
fmt.Println(withdrawal.WithdrawalID, withdrawal.Status)
}
using Paymos;
using var paymos = new PaymosClient(
Environment.GetEnvironmentVariable("PAYMOS_PAYOUT_KEY")!,
Environment.GetEnvironmentVariable("PAYMOS_API_SECRET")!);
var withdrawal = await paymos.Withdrawals.CreateAsync(new CreateWithdrawalRequest(
DestinationAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
Network: "TRC20",
Currency: "USDT",
Amount: "50.00",
ExternalOrderId: "payout-001"));
Console.WriteLine($"{withdrawal.WithdrawalId} {withdrawal.Status}");
import io.paymos.CreateWithdrawalRequest;
import io.paymos.PaymosClient;
import io.paymos.Withdrawal;
PaymosClient paymos = new PaymosClient(
System.getenv("PAYMOS_PAYOUT_KEY"),
System.getenv("PAYMOS_API_SECRET"));
Withdrawal withdrawal = paymos.withdrawals.create(new CreateWithdrawalRequest(
"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"TRC20",
"USDT",
"50.00",
"payout-001"));
System.out.println(withdrawal.withdrawalId() + " " + withdrawal.status());
require 'paymos'
paymos = Paymos::Client.new(
api_key: ENV.fetch('PAYMOS_PAYOUT_KEY'),
api_secret: ENV.fetch('PAYMOS_API_SECRET')
)
withdrawal = paymos.withdrawals.create(
destination_address: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
network: 'TRC20',
currency: 'USDT',
amount: '50.00',
external_order_id: 'payout-001'
)
puts "#{withdrawal.withdrawal_id} #{withdrawal.status}"
use paymos::{CreateWithdrawalRequest, PaymosClient};
let paymos = PaymosClient::new(
std::env::var("PAYMOS_PAYOUT_KEY")?,
std::env::var("PAYMOS_API_SECRET")?,
)?;
let withdrawal = paymos
.withdrawals()
.create(&CreateWithdrawalRequest {
destination_address: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9".to_owned(),
network: "TRC20".to_owned(),
currency: "USDT".to_owned(),
amount: "50.00".to_owned(),
external_order_id: "payout-001".to_owned(),
})
.await?;
println!("{} {}", withdrawal.withdrawal_id, withdrawal.status);
响应 (201 Created / 幂等命中为 200)
{
"withdrawal_id": "wdr_2M8K6Q4P9X1Z7A3B",
"external_order_id": "payout-001",
"status": "created",
"is_final": false,
"is_test": true,
"amount": "100.00",
"currency": "USDT",
"network": "TRC20",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"created_at": 1739289600
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
withdrawal_id |
string | 带前缀的转出标识(wdr_...) |
external_order_id |
string | 你自己的付款引用,从创建请求原样回显 |
status |
string | 转出状态(snake_case——见 转出状态) |
is_final |
boolean | 转出达到终态(completed、failed、cancelled)后为 true |
is_test |
boolean | 沙箱转出为 true |
amount |
string | 转出金额 |
fee |
string? | 按代币的固定转出手续费,从平台代币目录解析,与 amount 同币种。按代币固定,而非实时 gas 报价:有补贴,低于该路线的链上成本,不含 Paymos 佣金。无手续费时省略 |
currency |
string | 加密资产符号 |
network |
string | 区块链网络代码 |
destination_address |
string | 目标地址 |
tx_hash |
string? | 完成该付款的转账的链上哈希。仅当 status 为 completed 时设置 |
explorer_url |
string? | 该 tx_hash 在网络区块浏览器中的直接链接(如 Tronscan、Etherscan)。仅当 tx_hash 已设置且该网络配置了浏览器时设置。原样渲染为可点击链接即可 |
created_at |
integer | Unix 时间戳,秒 |
completed_at |
integer? | Unix 时间戳,秒。付款完成时设置 |
failed_at |
integer? | Unix 时间戳,秒。付款失败时设置 |
cancelled_at |
integer? | Unix 时间戳,秒。转出被取消时设置 |
幂等
转出请求始终带 external_order_id。用同一个 external_order_id 重试同一调用,返回已有转出——绝不产生第二笔转账。幂等命中时响应状态为 200 OK(不带 Location 请求头),新建转出为 201 Created。
这是你对抗网络抖动、工作进程崩溃和重试循环的安全网。同一笔付款用同一个 ID;新的付款换新 ID。
错误
完整目录见 错误码。每个错误响应中的 type URI 直接链接到对应条目。