TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"currency":"USDT","description":"October contractor payouts","items":[{"real_name":"Example Recipient","network":"trc20","address":"TExampleAddressReplaceBeforeUse","amount":"125.00"}]}'
IDEMPOTENCY_KEY='payout-create-example-001'
SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')
curl --request POST "https://api.stablepay.co/api/v1/payout-batches" \
-H "Authorization: Bearer ${API_KEY}" \
-H "X-StablePay-Timestamp: ${TIMESTAMP}" \
-H "X-StablePay-Nonce: ${NONCE}" \
-H "X-StablePay-Signature: ${SIGNATURE}" \
-H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
-H "Content-Type: application/json" \
--data-raw "${BODY}"
{
"code": 400,
"message": "Idempotency-Key header is required",
"errorCode": "invalid_request",
"data": null
}
{
"code": 401,
"message": "authenticated merchant is required",
"errorCode": "authentication_required",
"data": null
}
{
"code": 403,
"message": "access denied",
"errorCode": "forbidden",
"data": null
}
{
"code": 500,
"message": "payout request failed",
"errorCode": "payout_error",
"data": null
}
{
"code": 503,
"message": "payout service is temporarily unavailable",
"errorCode": "service_unavailable",
"data": null
}
付款 API
创建付款批次
创建包含 1 至 200 条明细的付款批次。
POST
/
api
/
v1
/
payout-batches
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"currency":"USDT","description":"October contractor payouts","items":[{"real_name":"Example Recipient","network":"trc20","address":"TExampleAddressReplaceBeforeUse","amount":"125.00"}]}'
IDEMPOTENCY_KEY='payout-create-example-001'
SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')
curl --request POST "https://api.stablepay.co/api/v1/payout-batches" \
-H "Authorization: Bearer ${API_KEY}" \
-H "X-StablePay-Timestamp: ${TIMESTAMP}" \
-H "X-StablePay-Nonce: ${NONCE}" \
-H "X-StablePay-Signature: ${SIGNATURE}" \
-H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
-H "Content-Type: application/json" \
--data-raw "${BODY}"
{
"code": 400,
"message": "Idempotency-Key header is required",
"errorCode": "invalid_request",
"data": null
}
{
"code": 401,
"message": "authenticated merchant is required",
"errorCode": "authentication_required",
"data": null
}
{
"code": 403,
"message": "access denied",
"errorCode": "forbidden",
"data": null
}
{
"code": 500,
"message": "payout request failed",
"errorCode": "payout_error",
"data": null
}
{
"code": 503,
"message": "payout service is temporarily unavailable",
"errorCode": "service_unavailable",
"data": null
}
请求必须携带
对象仅允许包含下列已定义字段。
Idempotency-Key。同一商户重复使用相同 key 时返回已创建的批次；请确保相同 key 对应相同请求内容。
创建 draft 状态的付款批次。同一商户重复使用相同的 Idempotency-Key 时返回已创建的批次。
商户身份由 stablepay-auth 的认证结果确定，请求参数不得传入 merchant_id。批次状态和业务规则以 StablePay Payout 服务为准。
认证与请求头
使用 Bearer API Key 和以下三个签名请求头。使用 API Secret 对{timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，并转换为小写 hex。签名使用实际发送的原始请求体；不发送请求体时使用空字符串。详见认证与签名。
string
必填
Bearer API Key:
Bearer sk_live_xxx.string
必填
Unix 时间戳（秒），与服务器时间相差不超过 5 分钟。
string
必填
防重放随机字符串，每次请求使用新的 nonce。 最短字符数：16。 最长字符数：64。
string
必填
请求签名，使用小写十六进制编码。
string
必填
商户范围内的创建请求幂等键，最长 128 个字符。 最短字符数：1。 最长字符数：128。
请求体
application/json（必填）。
对象仅允许包含下列已定义字段。
string
必填
可选值：
USDT、USDC。string
object[]
必填
成功响应
HTTP200, application/json. 创建成功。
对象仅允许包含下列已定义字段。
string
必填
string
必填
可选值：
draft、needs_fix、pending、pending_approval、processing、partially_completed、completed、failed、canceled、rejected。string
必填
可选值：
USDT、USDC。string
必填
可选值：
erc20、trc20、spl。integer
必填
最小值：0。
integer
必填
最小值：0。
integer
必填
最小值：0。
integer
必填
最小值：0。
integer
必填
最小值：0。
string
必填
非负十进制金额字符串，最多两位小数。 匹配规则：
^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$。string
必填
非负十进制金额字符串，最多两位小数。 匹配规则：
^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$。string
必填
非负十进制金额字符串，最多两位小数。 匹配规则：
^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$。string
必填
非负十进制金额字符串，最多两位小数。 匹配规则：
^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$。string
必填
非负十进制金额字符串，最多两位小数。 匹配规则：
^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$。boolean
批次当前是否可以提交；status 为 canceled 时不返回。
string | null
integer
必填
格式：
int64。integer | null
格式：
int64。integer | null
格式：
int64。响应头
| 响应头 | 说明 |
|---|---|
X-Request-ID | 请求追踪 ID。 |
Cache-Control | 响应不得缓存。 可选值：no-store。 |
错误响应
| HTTP | 说明 |
|---|---|
| 400 | HTTP 请求格式、参数无效，或付款请求不满足业务校验。可能的业务错误码包括 address_risk_rejected、batch_amount_limit_exceeded、batch_amount_too_low、batch_cannot_submit、batch_empty_items、custody_balance_insufficient、insufficient_balance 和 quota_blocked。 |
| 401 | 鉴权失败或缺少可信商户身份。 |
| 403 | 当前商户无权访问或操作该资源。 |
| 500 | 当前未细分的付款业务错误。 |
| 503 | 付款服务超时或暂时不可用。写请求发生此错误时应先查询资源状态。 |
integer
必填
string
必填
string
必填
null
必填
相关接口
运行示例前设置
API_KEY 和 SECRET_KEY，并按接口路径设置 BATCH_ID 或 ITEM_ID。调用前替换示例收款地址。重试同一次创建请求时，复用相同幂等键和请求内容。
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"currency":"USDT","description":"October contractor payouts","items":[{"real_name":"Example Recipient","network":"trc20","address":"TExampleAddressReplaceBeforeUse","amount":"125.00"}]}'
IDEMPOTENCY_KEY='payout-create-example-001'
SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')
curl --request POST "https://api.stablepay.co/api/v1/payout-batches" \
-H "Authorization: Bearer ${API_KEY}" \
-H "X-StablePay-Timestamp: ${TIMESTAMP}" \
-H "X-StablePay-Nonce: ${NONCE}" \
-H "X-StablePay-Signature: ${SIGNATURE}" \
-H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
-H "Content-Type: application/json" \
--data-raw "${BODY}"
{
"code": 400,
"message": "Idempotency-Key header is required",
"errorCode": "invalid_request",
"data": null
}
{
"code": 401,
"message": "authenticated merchant is required",
"errorCode": "authentication_required",
"data": null
}
{
"code": 403,
"message": "access denied",
"errorCode": "forbidden",
"data": null
}
{
"code": 500,
"message": "payout request failed",
"errorCode": "payout_error",
"data": null
}
{
"code": 503,
"message": "payout service is temporarily unavailable",
"errorCode": "service_unavailable",
"data": null
}
最后修改于 2026年10月19日
此页面对您有帮助吗？