POST
/api/payout
创建单笔代付订单。提交后系统将锁定汇率并调用银行/支付机构通道。
10 req/s · 100 req/min
需要鉴权
幂等性 (X-Idempotency-Key)
1. 签名机制 (RSA-SHA256)
所有 API 请求（除 /api/token 外）都需要在 Header 中携带签名。
签名采用 RSA-SHA256 非对称加密算法，使用商户的 RSA 私钥签名，平台使用公钥验签。
密钥对可在 安全中心 生成，支持 2048/4096 位。
签名步骤
- 1.生成密钥对：在 安全中心 → API 密钥 中创建 RSA 密钥对，平台生成 2048 位 RSA 公私钥，私钥由商户自行保管
- 2.收集参数：
method、path、timestamp、nonce、body - 3.将参数按
key=value格式拼接，以\n连接构造待签字符串 - 4.使用 RSA 私钥 对字符串进行
SHA256withRSA签名，输出 Base64 编码 - 5.将签名结果放入
X-Signature请求头，平台使用公钥验签
时间戳
X-Timestamp: 1717400000
Unix 秒级 · 偏差 ±5 分钟
随机数
X-Nonce: 7f3a...b2e1
UUID v4 · 防重放
签名
X-Signature: a93f...
RSA-SHA256 · Base64
2. 请求参数 (Request Body)
参数名
类型
必填
说明
order_id
string
是
商户订单号，最长 32 位，全局唯一
amount
decimal
是
代付金额，最多 2 位小数
currency
string
是
ISO 4217 币种代码，如 USD / EUR / GBP / JPY / INR / BRL / CNY
recipient.full_name
string
是
收款人姓名，需与银行账户一致
recipient.bank_account
string
是
银行账号，根据国家不同采用不同格式（ACH/SWIFT/IBAN/IFSC/PIX）
recipient.bank_code
string
否
银行代码：SWIFT/BIC、Routing Number、IFSC、Sort Code 等
recipient.country
string
是
ISO 3166-1 alpha-2 国家代码，如 US / GB / IN / DE / JP / BR
recipient.email
string
否
收款人邮箱，用于接收通知
purpose
string
否
代付用途：salary / bonus / refund / reimbursement / other
remark
string
否
商户自定义备注，最长 128 字符
metadata
object
否
商户自定义元数据，回调时原样返回
3. 响应参数 (Response)
字段
类型
说明
code
int
状态码，0 表示成功
message
string
描述信息
data.order_id
string
商户订单号
data.id
string
平台订单号 (PO- 前缀)
data.status
int
0 待处理 / 1 处理中 / 2 成功 / 3 失败 / 4 退汇
data.amount
decimal
代付金额
data.currency
string
币种
data.fee
decimal
手续费
data.rate
decimal
锁定的 USDT/法币汇率
data.created_at
datetime
订单创建时间 (ISO 8601)
4. 代码示例
# 1. 准备签名
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
METHOD="POST"
PATH_URL="/api/payout"
BODY='{"order_id":"PAY-20260603-001","amount":"4280.00","currency":"USD","recipient":{"full_name":"Sarah Kim","bank_account":"1234567890","bank_code":"021000021","country":"US","email":"sarah@acme.io"},"purpose":"salary","remark":"June salary"}'
PRIVATE_KEY_PATH="/etc/globepay/private.pem"
# 2. 拼接待签字符串
PAYLOAD="${METHOD}\n${PATH_URL}\n${TIMESTAMP}\n${NONCE}\n${BODY}"
# 3. 使用 RSA 私钥签名 (SHA256withRSA + Base64)
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -sign "${PRIVATE_KEY_PATH}" | openssl base64 -A)
# 4. 发起请求
curl -X POST "https://api.globepay.io/v1/api/payout" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "X-Nonce: ${NONCE}" \
-H "X-Signature: ${SIGNATURE}" \
-H "X-Idempotency-Key: ${NONCE}" \
-H "Content-Type: application/json" \
-d "${BODY}"成功响应 (HTTP 200)
{
"code": 0,
"message": "success",
"data": {
"order_id": "PAY-20260603-001",
"id": "PO-20260603-7821",
"status": 1,
"amount": "4280.00",
"currency": "USD",
"fee": "2.14",
"rate": "1.0002",
"estimated_arrival": "2026-06-03T17:00:00Z",
"created_at": "2026-06-03T09:42:18Z"
}
}5. 错误码
code
HTTP
含义
0
200
成功
10001
401
签名错误 · 检查 X-Signature 算法或时间戳
10002
401
Token 过期 · 调用 /api/token/refresh
10003
403
IP 不在白名单
20001
400
参数缺失
20002
400
银行账号格式错误 (按国家不同规则不同)
30001
429
触发限流 · 10 req/s
30002
429
重复请求 · 幂等键冲突
50001
500
系统异常 · 联系客服并提供 Request ID
6. IP 白名单
为提升 API 访问安全性，商户可在 安全中心 → API 密钥 中为每个 API Key 绑定 IP 白名单。 绑定后，只有来自白名单内 IP 的请求才会被放行。未绑定即默认对所有 IP 开放。
配置方式
安全中心 → API 密钥 → 编辑 → IP 白名单
支持 IPv4 单 IP 与 CIDR 网段
格式示例
203.0.113.0/24192.0.2.10
最多 50 个条目，用逗号或换行分隔
违反响应
HTTP 403
错误码
10003 · IP 不在白名单最佳实践：建议将公司办公出口 IP 和服务器 IP 加入白名单，避免使用动态 IP 配密钥
白名单变更后即时生效，无需重启服务或重新生成 Token
审计日志：所有被白名单拦截的请求均记录在安全中心 → 登录日志中，含时间、IP、请求路径
7. 回调通知 (Webhook)
当订单状态变更时，平台会主动向商户在 API 密钥 中配置的 Webhook URL 发送 POST 请求。
回调同样使用 RSA-SHA256 签名，Header 为
X-GlobePay-Signature回调超时 5 秒，需返回 HTTP 2xx 表示成功，否则按指数退避重试 5 次
可在控制台查看回调日志与重试历史
8. 查询订单 (GET /api/order/{id})
查询代付订单的最终状态。轮询建议间隔 ≥ 30 秒，最多 60 次后停止并改用 Webhook。
curl -X GET "https://api.globepay.io/v1/api/order/PO-20260603-7821" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "X-Nonce: ${NONCE}" \
-H "X-Signature: ${SIGNATURE}"