● 出款 · /v1

出款

向收款人付钱。签名要求比收款高一级(L2 非对称签名),收款账号字段必须加密传输。

出款列表

GET /v1/payouts

Query 参数

status string
cursor string 上一页返回的 page.next_cursor
limit integer

响应 200

data object[]
└uid string
└reference_id string
└amount integer
└currency string
└currency_exponent integer
└status created | processing | paid | failed | returned
└connector_code string
└failure_code string
└created_at string<date-time>
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx"

发起出款

POST /v1/payouts

出款是资损敞口最大的接口,签名要求比收款高一级:必须用 Ed25519 非对称签名(L2), 收款账号走数字信封加密字段,不接受明文。超过配置阈值的金额会进双人复核,此时返回 status=created 并等待审批。

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

reference_id必填 string
amount必填 integer
currency必填 string
beneficiary必填 object 账号字段必须放在 encrypted 信封里,明文提交直接 400。
└name string
└country string
└encrypted object
└key_id string
└enc_key string
└nonce string
└ciphertext string
└tag string

响应 201

uid string
reference_id string
amount integer
currency string
currency_exponent integer
status created | processing | paid | failed | returned
connector_code string
failure_code string
created_at string<date-time>

错误

400参数不合法
请求
curl -X POST https://api.baton.example/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "reference_id": "PO-10240",
  "amount": 150000,
  "currency": "USD",
  "beneficiary": {
    "name": "Ada Lovelace",
    "country": "US",
    "encrypted": {
      "key_id": "pk_2026q4",
      "enc_key": "base64...",
      "nonce": "base64...",
      "ciphertext": "base64...",
      "tag": "base64..."
    }
  }
}'

查询出款

GET /v1/payouts/{uid}

路径参数

uid必填 string

响应 200

uid string
reference_id string
amount integer
currency string
currency_exponent integer
status created | processing | paid | failed | returned
connector_code string
failure_code string
created_at string<date-time>
请求
curl -X GET https://api.baton.example/v1/payouts/{uid} \
  -H "Authorization: Bearer sk_live_xxx"

撤销出款

POST /v1/payouts/{uid}/cancel

只有 created(等双人复核)状态能撤。已提交渠道的撤不回来—— 那时只能等结果,失败会自动退回余额。填错金额发现得越早越好。

路径参数

uid必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

响应 200

uid string
reference_id string
amount integer
currency string
currency_exponent integer
status created | processing | paid | failed | returned
connector_code string
failure_code string
created_at string<date-time>

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/payouts/{uid}/cancel \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."