curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "currency": "SGD",
  "amount": "1.00",
  "purpose_code": "BUSINESS_EXPENSES",
  "payout_reference": "contract-44c07172-0363-42c1-a0a9-2a0c45aa3e00",
  "fee_paid_by": "SHARED",
  "payout_date": "2026-09-10",
  "beneficiary_id": "84ae9e5a-5d33-42c5-97e8-ae089027b1ed"
}
'

{
  "payout_id": "93775b87-dd00-4bb5-be7b-e3a3c048ff5b",
  "payout_status": "READY_TO_SEND",
  "short_reference_id": "P260910-UGZ16W43"
}

Payouts

Create Payout

向受益人创建一笔新的 payout。依托 SWIFT 与本地支付通道的能力支持，你可以更快、更具成本效益地向海外企业账户、供应商和员工发起国际付款。

此 API 支持多种付款模式，包括标准 payout 和代付（POBO），实现灵活高效的资金管理。此外，你还可以选择费用承担方式，以控制交易手续费的处理方式。

使用说明

支持以 30+ 种币种向 180 多个国家/地区发起 payout，包括向中国大陆发起的 CNY payout。
用于 POBO 交易的子账户必须提前创建，且账户状态必须为已激活。
要启用 POBO 模式，请在请求头中加入 x-on-behalf-of 参数，并指定用于该 payout 的子账户 ID。受益人将看到自定义的付款人名称，而非实际付款实体。
用户可通过 fee_paid_by 参数选择费用承担类型，以确定由谁承担交易费用：
1. SHARED —— 交易手续费由付款人与收款方分担；付款人承担汇出行费用，收款方承担收款行费用。
2. OURS —— 所有交易手续费（含中间行费用）均由付款人承担。
有两种方式指定受益人：
1. 使用 beneficiary_id —— 如果受益人已创建，提供 beneficiary_id 以引用现有受益人。
2. 提供完整的受益人信息 —— 如果受益人此前未创建，在请求中包含完整的受益人信息。此时不要传入 beneficiary_id。
注意：提供完整信息时会创建一个受益人。后续向同一受益人发起的任何 payout，都应传入对应的 beneficiary_id，而非完整的受益人信息。
如果你打算发起跨币种 payout，可参阅跨币种指南了解详情与示例。

Mastercard Send 可使用已保存的 CARD beneficiary_id，或提供完整 CARD beneficiary 对象，两者不能同时提供。卡字段位于 beneficiary.bank_details，不在出款顶层。创建成功表示受理，不代表付款完成。

POST

payouts

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "currency": "SGD",
  "amount": "1.00",
  "purpose_code": "BUSINESS_EXPENSES",
  "payout_reference": "contract-44c07172-0363-42c1-a0a9-2a0c45aa3e00",
  "fee_paid_by": "SHARED",
  "payout_date": "2026-09-10",
  "beneficiary_id": "84ae9e5a-5d33-42c5-97e8-ae089027b1ed"
}
'

{
  "payout_id": "93775b87-dd00-4bb5-be7b-e3a3c048ff5b",
  "payout_status": "READY_TO_SEND",
  "short_reference_id": "P260910-UGZ16W43"
}

授权

x-auth-token

string

header

必填

由 UQPAY 提供的登录 API Token。

请求头

x-on-behalf-of

string

设为关联账户的 ID。若该值非空，请求参数 is_payer 将默认为 Y。更多信息参见查询关联账户列表

x-idempotency-key

string<uuid>

必填

用于保持操作幂等性的唯一标识符（UUID），确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败时保持数据一致性。

请求体

application/json

currency

string

必填

付款人将汇出的币种。

Required string length: 3

示例:

"USD"

amount

string

必填

付款人将汇出的金额，以 currency 计。

示例:

"1000.00"

purpose_code

string

必填

payout 的用途代码，必须为以下之一：

AUDIO_VISUAL_SERVICES - 视听服务。
BILL_PAYMENT - 账单支付。
BUSINESS_EXPENSES - 企业开支。
CONSTRUCTION - 建筑。
DONATION_CHARITABLE_CONTRIBUTION - 捐赠/慈善捐赠。
EDUCATION_TRAINING - 教育/培训。
FAMILY_SUPPORT - 家庭赡养。
FREIGHT - 运费。
GOODS_PURCHASED - 购买商品。
INVESTMENT_CAPITAL - 投资本金。
INVESTMENT_PROCEEDS - 投资收益。
LIVING_EXPENSES - 生活开支。
LOAN_CREDIT_REPAYMENT - 贷款/信贷还款。
MEDICAL_SERVICES - 医疗服务。
PENSION - 养老金。
PERSONAL_REMITTANCE - 个人汇款。
PROFESSIONAL_BUSINESS_SERVICES - 专业/商业服务。
REAL_ESTATE - 房地产。
TAXES - 税费。
TECHNICAL_SERVICES - 技术服务。
TRANSFER_TO_OWN_ACCOUNT - 转账至本人账户。
TRAVEL - 旅行。
WAGES_SALARY - 工资/薪酬。

示例:

"AUDIO_VISUAL_SERVICES"

quote_id

string

预先创建的报价的 ID，通过创建报价获取。

仅在跨币种 payout 场景下需要。如果提供，还必须同时提供 payout_currency 和 payout_amount。

示例:

"784832f7-1f8a-4b08-ac2a-8719b5b2a590"

payout_currency

string

受益人将收到的币种。完整的可用币种列表请参阅支持的币种。

当指定 quote_id 时必填。必须与创建报价响应中返回的 buy_currency 一致。

示例:

"SGD"

payout_amount

string<decimal>

受益人将收到的金额，以 payout_currency 计。

当指定 quote_id 时必填。必须与创建报价响应中返回的 buy_amount 一致。

示例:

"100.00"

payout_reference

string

显示在受益人银行交易记录中的银行付款附言。会发送给收款方（如 For Further Credit、For Benefit of 或自定义信息）。在控制台中亦称 Payment reference。

SWIFT 付款：必须符合正则 /^[a-zA-Z0-9/-?:().'+, ]+$/。允许的字符：英文字母、数字、空格，以及以下特殊符号：- / ? : ( ) . ' + ,。
LOCAL 付款：当 payment_method = LOCAL 且 account_currency_code 不是 CNH 或 SGD 时，不应用输入格式校验。

Maximum string length: 100

示例:

"026073150"

fee_paid_by

enum<string>

付款手续费的承担类型。仅在 payment_method = SWIFT 时生效并必填。

SHARED：交易手续费由付款人与收款方分担；付款人承担汇出行费用，收款方承担收款行费用。当付款人为企业且付款人所在国家/地区为 SG、VN、HK 或 AU 之一时，SWIFT payout 可使用此项。
OURS：所有交易手续费（含中间行费用）均由付款人承担。

可用选项:

SHARED,

OURS

示例:

"SHARED"

payout_date

string<date>

系统尝试向受益人提交付款的日期。

示例:

"2024-03-01"

beneficiary_id

string<uuid>

受益人的通用唯一标识符（UUID v4）。可用它替代 beneficiary 部分；如果已提供 beneficiary 各字段，则此项应留空，反之亦然。

示例:

"b3d9d2d5-4c12-4946-a09d-953e82sed2b0"

beneficiary

Company bank beneficiary · object

payout 请求中受益人的信息。如果 payout 请求中提供了 beneficiary_id，则 beneficiary 应留空。

Company bank beneficiary
Individual bank beneficiary
Company Mastercard beneficiary
Individual Mastercard beneficiary

Show child attributes

is_payer

string

重要提示：此字段计划在下一版本中弃用。建议在新开发中避免使用此字段。当前用户是否为付款人。取值为 Y 或 N

示例:

"N"

payer_id

string<uuid>

重要提示：此字段计划在下一版本中弃用。建议在新开发中避免使用此字段。付款人的唯一标识符。如果 is_payer 为 Y，payer_id 为空；如果 is_payer 为 N，则通过查询付款人列表接口获取 payer_id。

示例:

"d36384c8-5df1-4ede-b054-804578601ae7"

documentation

object[]

与该 payout 相关的证明文件。

一般情况：可选字段，用于附加与该 payout 相关的文件。
必填情况：当 beneficiary.bank_details.account_currency_code = INR 且 clearing_system = IFSC 时，必须通过 documentation 字段上传发票文件。

Show child attributes

响应

200 - application/json

Payout 创建成功。

payout_id

string<uuid>

该 payout 的唯一标识符。

示例:

"b3d9d2d5-4c12-4946-a09d-953e82sed2b0"

short_reference_id

string

系统生成的用于标识该实体的编号。

示例:

"P220406-LLCVLRM"

payout_status

enum<string>

该 payout 的状态。

READY_TO_SEND：payout 已通过校验，准备处理。
PENDING：payout 正在由系统处理中。
REJECTED：payout 因未满足校验或合规要求而被拒绝。
FAILED：payout 处理过程中发生错误，无法完成。
COMPLETED：payout 已成功处理，资金已转出。

可用选项:

READY_TO_SEND,

PENDING,

REJECTED,

FAILED,

COMPLETED

示例:

"COMPLETED"