跳到正文

API

本页内容

创建

从代币余额向白名单钱包创建转出,选择付款网络,签名请求,并跟踪其状态。

POST/v1/withdrawals

API 密钥: Payout

交易签名并广播上链后,转出不可逆。发送前核对 destination_addressnetwork——请求落入 created 后只能在执行开始前取消,而执行可能片刻之后就开始。广播之后没有追回途径,地址错了就意味着资金损失。

转出不会排进批次:请求受理后立即开始执行。之后转账多久到账,取决于付款网络当时的速度和拥堵情况。

请求体

参数 类型 必填 说明
amount string 转出金额,十进制字符串(如 "100.00"
currency string 加密资产符号。凡是持有余额的资产都可转出,可选网络随资产而定(见 支持的币种
network string 转出网络代码——TRC20ERC20BEP20POLYGONARBITRUMOPTIMISMBASETONAVAXSOLPLASMA。这是收款所用 13 个网络里的 11 个:NEARSUI 只收不转,它们的地址进不了白名单(见 支持的币种
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 转出达到终态(completedfailedcancelled)后为 true
is_test boolean 沙箱转出为 true
amount string 转出金额
fee string? 按代币的固定转出手续费,从平台代币目录解析,与 amount 同币种。按代币固定,而非实时 gas 报价:有补贴,低于该路线的链上成本,不含 Paymos 佣金。无手续费时省略
currency string 加密资产符号
network string 区块链网络代码
destination_address string 目标地址
tx_hash string? 完成该付款的转账的链上哈希。仅当 statuscompleted 时设置
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 直接链接到对应条目。