受益人（Recipient / Beneficiary）

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

控制台流程

在商户后台打开 Transfer，然后选择 Recipients。
选择 Add recipient。
选择收款方是 UQPAY 账户还是银行收款方。对于银行收款方，请先选择银行所在国家、币种和可用的付款方式，再填写所需银行信息。
检查并保存收款方。验证状态会显示在 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：准备受益人信息

以下为 LOCAL/SWIFT 银行受益人的资料要求。卡受益人请使用Mastercard Send 规则。 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 状态的受益人创建出款。
对同一银行账户的重复出款，应复用已有受益人。
创建和更新请求请使用幂等键。

API Doc

Mastercard Send 卡受益人

采集卡资料前，请使用 country、currency 和明确的 entity_type 查询支付方式。支持的国家和币种以该账户返回的方式为准；银行出款覆盖列表不代表卡出款覆盖范围。

字段	要求
`payment_method`	使用 `CARD`。
`bank_details.clearing_system`	填写 `MASTERCARD SEND`。
`bank_details.account_number`	仅数字，不含空格或连字符。同时满足 11–19 位基础校验及支付方式查询返回的长度规则。
`bank_details.card_expiry`	使用 `YYYY-MM`，允许当前月份，不允许过去月份。
`bank_details.account_holder`	必填。个人名称最后一个单词作为姓，其余作为名；公司名称也从此值派生。
`bank_details.account_currency_code`、`bank_details.bank_country_code`	国家、币种及收款实体组合须有有效配置。
`address.country`、`address.city`、`address.street_address`	公司必填，州/省和邮编可选。个人不套用银行转账的地址必填规则。

Mastercard 不要求银行名称、银行地址、SWIFT 代码、IBAN 或路由代码，仍须满足支付方式查询返回的附加字段规则。查询响应使用复数字段 clearing_systems，Mastercard 的 validation_field 为规则对象数组。配置路径 beneficiary.beneficiary_bank_details.card_expiry 对应 Gateway 字段 bank_details.card_expiry，不能将配置路径直接作为请求结构。查重使用卡号、国家、币种、收款实体和清算方式，不需要 card_expiry。匹配仅表示存在已保存受益人，不代表卡片可收款。创建和更新使用同一完整卡对象；更新不是 PATCH。创建出款前请保持有效期资料有效。参见卡受益人实测示例。

概览

虚拟账户

出款与充值

外汇

参考

受益人（Recipient / Beneficiary）

控制台流程

API 集成流程

步骤1：查询支付方式

步骤2：准备受益人信息

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

步骤4：创建受益人

步骤5：处理受益人 Webhook

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

管理受益人

集成建议

API Doc

Mastercard Send 卡受益人

​控制台流程

​API 集成流程

​步骤1：查询支付方式

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

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

​步骤4：创建受益人

​步骤5：处理受益人 Webhook

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

​管理受益人

​集成建议

​API Doc

​Mastercard Send 卡受益人

控制台流程

API 集成流程

步骤1：查询支付方式

步骤2：准备受益人信息

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

步骤4：创建受益人

步骤5：处理受益人 Webhook

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

管理受益人

集成建议

API Doc

Mastercard Send 卡受益人