> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # 受益人（Recipient / Beneficiary） > 通过控制台或 API 创建、校验和管理出款受益人。 Recipient 和 Beneficiary 指同一类对象：从出款中接收资金的个人或企业。控制台界面使用“Recipient”，API 的端点名称、请求字段和 Webhook payload 中使用“Beneficiary”。 你可以通过控制台或 API 创建和管理受益人。当你的集成需要以编程方式维护受益人、检查受益人是否已存在，或为多个子账户管理受益人档案时，请使用 API 流程。

控制台流程

1. 登录控制台 > 选择 **Global Account** recipients beneficiary screenshot 2025 07 08 at 16.10.29 2. 进入 **Reference** > **Recipients** 页面 3. 点击右上角的 **Create new recipients**。 recipients beneficiary output

API 集成流程

通过 API 创建受益人时，建议按以下流程处理： 1. 查询受益人银行所在国家和账户币种支持的支付方式。 2. 检查是否已经存在匹配的受益人。 3. 如果没有可复用的受益人，则创建新的受益人。 4. 监听受益人 Webhook，并查询受益人状态。 5. 创建出款时使用 `beneficiary_id`。 6. 通过列表、详情、更新和删除 API 持续维护受益人档案。 如果你为子账户管理受益人，请在受益人相关 API 中通过 `x-on-behalf-of` header 传入子账户的 `account_id`。如果省略 `x-on-behalf-of`，请求会作用于当前认证的主账户。

步骤1：查询支付方式

在向用户收集银行信息之前，先使用受益人银行所在国家和账户币种调用 [List Payment Methods](/zh/global-account/v1.6/api-reference/list-payment-methods)。 ```bash theme={null} curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/paymentmethods?country=SG¤cy=SGD' \ --header 'Accept: application/json' \ --header 'x-auth-token: {{token}}' ``` 响应会按该国家和币种支持的 `clearing_systems` 与 `payment_method` 组合逐条返回记录。 ```json theme={null} { "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](/zh/global-account/v1.6/api-reference/check-beneficiary)。这可以避免同一个银行账户被重复保存。 ```bash theme={null} 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`。 ```json theme={null} { "beneficiary_id": "" } ```

步骤4：创建受益人

只有在没有可复用 `beneficiary_id` 时，才调用 [Create Beneficiary](/zh/global-account/v1.6/api-reference/create-beneficiary)。 ```bash theme={null} 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": {} }' ``` 响应会返回受益人标识： ```json theme={null} { "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba", "short_reference_id": "BF250917-WQEQ2D7Q" } ``` 请保存 `beneficiary_id`。创建出款时，你应将该值传入 `beneficiary_id`。

步骤5：处理受益人 Webhook

请订阅 [Beneficiary Created](/zh/global-account/v1.6/webhooks/beneficiary-created) 事件。 | 事件类型 | 含义 | 建议操作 | | ------------------------ | -------- | -------------------- | | `beneficiary.successful` | 受益人创建成功。 | 在你的系统中保存或激活该受益人。 | | `beneficiary.failed` | 受益人创建失败。 | 将受益人标记为失败，并提示用户修正信息。 | 收到 Webhook 后，你可以调用 [Retrieve Beneficiary](/zh/global-account/v1.6/api-reference/retrieve-beneficiary) 确认最新的 `beneficiary_status`。 ```bash theme={null} 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`，无需重复提交完整受益人信息。 ```json theme={null} { "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](/zh/global-account/v1.6/api-reference/list-beneficiaries) | 搜索和展示已保存的受益人。 | | [Retrieve Beneficiary](/zh/global-account/v1.6/api-reference/retrieve-beneficiary) | 在出款前或 Webhook 事件后展示完整受益人详情。 | | [Update Beneficiary](/zh/global-account/v1.6/api-reference/update-beneficiary) | 修正银行信息、地址、昵称或其他可编辑字段。Entity type 不可变更。 | | [Delete Beneficiary](/zh/global-account/v1.6/api-reference/delete-beneficiary) | 移除不应再用于新出款的受益人。 |

集成建议

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

API Doc

* [List Payment Methods](/zh/global-account/v1.6/api-reference/list-payment-methods) * [Check Beneficiary](/zh/global-account/v1.6/api-reference/check-beneficiary) * [Create Beneficiary](/zh/global-account/v1.6/api-reference/create-beneficiary) * [List Beneficiaries](/zh/global-account/v1.6/api-reference/list-beneficiaries) * [Retrieve Beneficiary](/zh/global-account/v1.6/api-reference/retrieve-beneficiary) * [Update Beneficiary](/zh/global-account/v1.6/api-reference/update-beneficiary) * [Delete Beneficiary](/zh/global-account/v1.6/api-reference/delete-beneficiary)