受益人（Recipient / Beneficiary）

Recipient 和 Beneficiary 指同一类对象：从出款中接收资金的个人或企业。控制台界面使用“Recipient”，API 的端点名称、请求字段和 Webhook payload 中使用“Beneficiary”。你可以通过控制台或 API 创建和管理受益人。当你的集成需要以编程方式维护受益人、检查受益人是否已存在，或为多个子账户管理受益人档案时，请使用 API 流程。

控制台流程

登录控制台 > 选择 Global Account

recipients beneficiary screenshot 2025 07 08 at 16.10.29

进入 Reference > Recipients 页面
点击右上角的 Create new recipients。

API 集成流程

通过 API 创建受益人时，建议按以下流程处理：

查询受益人银行所在国家和账户币种支持的支付方式。
检查是否已经存在匹配的受益人。
如果没有可复用的受益人，则创建新的受益人。
监听受益人 Webhook，并查询受益人状态。
创建出款时使用 beneficiary_id。
通过列表、详情、更新和删除 API 持续维护受益人档案。

如果你为子账户管理受益人，请在受益人相关 API 中通过 x-on-behalf-of header 传入子账户的 account_id。如果省略 x-on-behalf-of，请求会作用于当前认证的主账户。

步骤1：查询支付方式

在向用户收集银行信息之前，先使用受益人银行所在国家和账户币种调用 List Payment Methods。

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/paymentmethods?country=SG&currency=SGD' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'

响应会按该国家和币种支持的 clearing_systems 与 payment_method 组合逐条返回记录。

{
  "data": [
    {
      "clearing_systems": "FAST",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "GIRO",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "LOCAL",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "MEPS",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "PAYNOW",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "RTGS",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "SWIFT",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "SWIFT",
      "validation_field": []
    }
  ]
}

请根据该响应决定受益人创建表单中需要展示哪些字段。

字段	使用方式
`payment_method`	使用 `LOCAL` 表示本地通道，使用 `SWIFT` 表示跨境银行转账。
`clearing_systems`	将用户选择的值传入 `bank_details.clearing_system`，例如 `FAST`、`Fedwire`、`Faster Payments` 或 `SWIFT`。
`country`	将两位国家代码传入 `bank_details.bank_country_code`。
`currency`	将三位币种代码传入 `bank_details.account_currency_code`。

步骤2：准备受益人信息

Create Beneficiary 支持企业受益人和个人受益人。企业受益人需要收集：

entity_type = COMPANY
company_name
选填的 email 和 nickname
payment_method
bank_details
address
特定出款国家或币种要求的 additional_info

个人受益人需要收集：

entity_type = INDIVIDUAL
first_name 和 last_name
选填的 email、nickname 和 id_number
payment_method
bank_details
特定出款国家或币种要求的 additional_info

最重要的 bank_details 字段包括：

字段	说明
`bank_country_code`	受益人银行所在国家的两位国家代码。
`account_currency_code`	受益人银行账户币种。
`account_holder`	受益人银行账户持有人名称。
`account_number`	很多本地通道要求传入账号。
`iban`	很多 IBAN 国家要求传入 IBAN。
`swift_code`	SWIFT 转账和部分本地通道要求传入 SWIFT 代码。
`clearing_system`	使用 List Payment Methods 返回的值。
`routing_code_type1` 和 `routing_code_value1`	部分通道要求传入，例如 `aba`、`ach`、`sort_code`、`bsb_code`、`bank_code`、`ifsc` 或 `cnaps_number`。
`routing_code_type2` 和 `routing_code_value2`	部分通道要求传入，例如某些 CAD EFT 出款需要 branch code。

部分币种需要 additional_info。例如，COP 出款要求传入 msisdn，个人受益人可能还需要 id_type 和 id_number，企业受益人可能还需要 tax_id。HKD 本地出款也要求传入 msisdn。

步骤3：检查是否已有受益人

创建新受益人之前，请调用 Check Beneficiary。这可以避免同一个银行账户被重复保存。

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --data '{
    "entity_type": "COMPANY",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "account_number": "1234567890",
    "payment_method": "LOCAL",
    "currency": "SGD",
    "bank_country_code": "SG",
    "clearing_system": "FAST"
  }'

如果存在匹配受益人，响应会包含 beneficiary_id。创建出款时请复用该 ID。如果未找到匹配受益人，响应会返回空的 beneficiary_id。

{
  "beneficiary_id": ""
}

步骤4：创建受益人

只有在没有可复用 beneficiary_id 时，才调用 Create Beneficiary。

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --header 'x-idempotency-key: d75238ce-7e56-474f-a242-77cb100bafc1' \
  --data '{
    "entity_type": "COMPANY",
    "email": "finance@example.com",
    "nickname": "Singapore supplier",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "payment_method": "LOCAL",
    "bank_details": {
      "bank_name": "DBS Bank Ltd",
      "bank_address": "12 Marina Boulevard, Singapore",
      "bank_country_code": "SG",
      "account_holder": "UQPAY TECHNOLOGY SG PTE LTD",
      "account_currency_code": "SGD",
      "account_number": "1234567890",
      "clearing_system": "FAST",
      "swift_code": "DBSSSGSG"
    },
    "address": {
      "country": "SG",
      "city": "Singapore",
      "street_address": "12 Marina Boulevard",
      "postal_code": "018982",
      "state": "Singapore",
      "nationality": "SG"
    },
    "additional_info": {}
  }'

响应会返回受益人标识：

{
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
  "short_reference_id": "BF250917-WQEQ2D7Q"
}

请保存 beneficiary_id。创建出款时，你应将该值传入 beneficiary_id。

步骤5：处理受益人 Webhook

请订阅 Beneficiary Created 事件。

事件类型	含义	建议操作
`beneficiary.successful`	受益人创建成功。	在你的系统中保存或激活该受益人。
`beneficiary.failed`	受益人创建失败。	将受益人标记为失败，并提示用户修正信息。

收到 Webhook 后，你可以调用 Retrieve Beneficiary 确认最新的 beneficiary_status。

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/e15436e2-35e8-4680-920d-4852940c18ba' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'

只有 ACTIVE 状态的受益人才应被用于出款。如果受益人仍为 PENDING，请等待最终结果后再发起出款。

步骤6：在出款中使用受益人

创建出款时，传入已保存的 beneficiary_id，无需重复提交完整受益人信息。

{
  "currency": "SGD",
  "amount": "1000.00",
  "purpose_code": "PROFESSIONAL_SERVICES",
  "payout_reference": "INV-2026-001",
  "fee_paid_by": "OURS",
  "payout_date": "2026-07-10",
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba"
}

使用 beneficiary_id 可以让出款请求更简洁，并降低提交不一致银行信息的风险。

管理受益人

使用以下 API 维护已保存的受益人档案：

API	使用场景
List Beneficiaries	搜索和展示已保存的受益人。
Retrieve Beneficiary	在出款前或 Webhook 事件后展示完整受益人详情。
Update Beneficiary	修正银行信息、地址、昵称或其他可编辑字段。Entity type 不可变更。
Delete Beneficiary	移除不应再用于新出款的受益人。

集成建议

为新的国家和币种设计输入表单前，始终先调用 List Payment Methods。
创建受益人前先使用 Check Beneficiary，避免重复创建。
同时保存 beneficiary_id 和 short_reference_id。
在你的系统中维护客户或供应商 ID 与 UQPAY beneficiary_id 的映射。
为子账户管理受益人时，始终一致地使用 x-on-behalf-of。
不要使用未达到 ACTIVE 状态的受益人创建出款。
对同一银行账户的重复出款，应复用已有受益人。
创建和更新请求请使用幂等键。

概览

虚拟账户

出款与充值

外汇

参考

受益人（Recipient / Beneficiary）

控制台流程

API 集成流程

步骤1：查询支付方式

步骤2：准备受益人信息

步骤3：检查是否已有受益人

步骤4：创建受益人

步骤5：处理受益人 Webhook

步骤6：在出款中使用受益人

管理受益人

集成建议

API Doc

​控制台流程

​API 集成流程

​步骤1：查询支付方式

​步骤2：准备受益人信息

​步骤3：检查是否已有受益人

​步骤4：创建受益人

​步骤5：处理受益人 Webhook

​步骤6：在出款中使用受益人

​管理受益人

​集成建议

​API Doc

控制台流程

API 集成流程

步骤1：查询支付方式

步骤2：准备受益人信息

步骤3：检查是否已有受益人

步骤4：创建受益人

步骤5：处理受益人 Webhook

步骤6：在出款中使用受益人

管理受益人

集成建议

API Doc