跳转到主要内容
POST
创建内部出款

授权

x-auth-token
string
header
必填

由 UQPAY 提供的登录 API Token。

请求头

x-on-behalf-of
string<uuid>

指定代表哪个已授权的直属子账户发起请求。填写该子账户的 account_id(小写 UUID),可通过查询关联账户列表获取。省略时使用 Token 对应账户。 更多信息参见关联账户。

x-idempotency-key
string<uuid>
必填

用于保证请求幂等性的唯一标识符(小写 UUID)。同一操作重试时使用相同标识符,避免重复出款。

请求体

application/json
account_id
string
必填

收款目标账户的 UUID 或短号。目标须已激活、具有账户短号,且不能是实际付款账户自身。不支持邮箱。

Maximum string length: 36
currency
string
必填

出款币种,使用三位字母 ISO 4217 币种代码。须为收付双方账户支持的同一法币币种。

Required string length: 3
amount
string
必填

出款金额,不含手续费,须大于零。IDR、JPY 和 KRW 的出款金额须为整数。

Pattern: ^[0-9]+(\.[0-9]{1,2})?$
purpose_code
string
必填

出款用途,不区分大小写,不应带首尾空白。请按实际业务选择以下支持的用途码:

Maximum string length: 200
nickname
string

收款人昵称。

Maximum string length: 120
payout_reason
string

出款用途的补充说明。

Maximum string length: 200
payout_reference
string

用于关联业务的出款附言。

Maximum string length: 100
with_transfer
enum<string>

是否在子账户付款前,先由其主账户划入本次付款所需资金。

使用主账户 Token 时,默认由主账户付款;携带 x-on-behalf-of 时,由指定的子账户付款。account_id 始终填写最终收款账户。

  • N 或省略:直接使用付款账户余额。 资金流向为 付款账户 → 收款账户。付款账户可用余额须覆盖 amount 和出款手续费;余额不足时失败,不会自动从主账户划款。
  • Y,由子账户付款:先从主账户划款,再由子账户付款。 资金流向为 主账户 → 付款子账户 → 收款账户。主账户先向子账户划入 amount 加出款手续费,再由子账户完成付款。即使子账户已有足够余额,也会划入这笔全额资金。

使用 Y 为子账户付款时,主账户总扣款 = amount + 出款手续费 + 主子账户划转手续费。主账户可用余额不足时失败,不会改用子账户已有余额。

如果实际付款账户是主账户,Y 与 N 的处理相同:直接使用该主账户的余额付款。

使用主账户供资时,付款子账户须直属于该主账户,并已开通此能力;出款币种的余额账户须有效,且可用余额不能为负。开通请联系 UQPAY。

可用选项:
Y,
N
documentation
object[]

证明材料,每项使用 file_id 或 file 提供。

响应

出款已受理,请查询出款详情确认完成状态。

payout_id
string<uuid>

出款的唯一标识。

short_reference_id
string

出款短流水号。

payout_status
enum<string>
  • READY_TO_SEND: 已受理,等待处理。
  • PENDING: 处理中。
  • COMPLETED: 已完成。
  • FAILED: 失败或取消。
  • REJECTED: 审核拒绝。
可用选项:
READY_TO_SEND,
PENDING,
COMPLETED,
FAILED,
REJECTED