跳转到主要内容
GET
Retrieve Beneficiary

授权

x-auth-token
string
header
必填

由 UQPay 提供的登录 API Token。

请求头

x-on-behalf-of
string

指定代表哪个子账户发起请求。应设为 account_id,可通过查询关联账户列表获取。如果省略或留空,请求将使用主账户执行。 更多信息参见关联账户

路径参数

id
string<uuid>
必填

资源的通用唯一标识符(UUID v4)。

示例:

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

响应

200 - application/json

OK —— 成功获取受益人。

beneficiary_id
string<uuid>
必填

受益人的通用唯一标识符(UUID v4)。

示例:

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

short_reference_id
string
必填

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

示例:

"P220406-LLCVLRM"

entity_type
enum<string>
必填

指定用于筛选的受益人实体类型。有效值为:

  • COMPANY:企业实体
  • INDIVIDUAL:个人账户
可用选项:
COMPANY,
INDIVIDUAL
payment_method
enum<string>
必填

需要指定支付方式,以确保针对该支付方式采集并校验准确的银行信息。

  • LOCAL:通过本地清算系统的境内支付网络处理的付款。
  • SWIFT:通过 SWIFT 网络处理的跨境国际付款。
可用选项:
LOCAL,
SWIFT
示例:

"LOCAL"

email
string
必填

受益人的电子邮箱地址。

示例:

"example@uqpay.com"

beneficiary_status
enum<string>
必填

受益人的状态。

  • ACTIVE:受益人已完成验证,可以收款。
  • PENDING:受益人正在验证过程中,暂时无法收款。
可用选项:
ACTIVE,
PENDING
示例:

"ACTIVE"

nickname
string

受益人昵称。

Maximum string length: 120
示例:

"John Doe"

company_name
string

受益人的公司名称,仅当 entity_type 为 COMPANY 时存在。

  • payment_method = SWIFT 时:

    • 仅可包含英文字母、数字、特殊字符(半角格式)和空格。
    • 允许的特殊字符:-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • payment_method = LOCAL 时:

    • 不应用严格的校验规则,支持本地语言字符。
  • bank_details.bank_country_code = SGbank_details.account_currency_code = SGD 时无需传入此字段

  • bank_country_code = CNaccount_currency_code = CNHpayment_method = LOCALentity_type = COMPANY 时,支持中文字符和中文括号 ()

Maximum string length: 120
Pattern: ^[a-zA-Z0-9 -_().,@#~!$%^&*+={}\|:"'<>?/・……]*$
示例:

"UQPAY TECHNOLOGY SG PTE LTD"

summary
string

受益人的摘要。

示例:

"John Doe"

first_name
string

受益人的名字,仅当 entity_type 为 INDIVIDUAL 时存在。

  • payment_method = SWIFT 时:

    • 仅可包含英文字母、数字、特殊字符(半角格式)和空格。
    • 允许的特殊字符:-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • payment_method = LOCAL 时:

    • 不应用严格的校验规则,支持本地语言字符。
  • bank_details.bank_country_code = SGbank_details.account_currency_code = SGD 时无需传入此字段

Maximum string length: 45
Pattern: ^[a-zA-Z0-9 -_().,@#~!$%^&*+={}\|:"'<>?/・……]*$
示例:

"John"

last_name
string

受益人的姓氏,仅当 entity_type 为 INDIVIDUAL 时存在。

  • payment_method = SWIFT 时:

    • 仅可包含英文字母、数字、特殊字符(半角格式)和空格。
    • 允许的特殊字符:-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • payment_method = LOCAL 时:

    • 不应用严格的校验规则,支持本地语言字符。
  • bank_details.bank_country_code = SGbank_details.account_currency_code = SGD 时无需传入此字段

Maximum string length: 45
Pattern: ^[a-zA-Z0-9 -_().,@#~!$%^&*+={}\|:"'<>?/・……]*$
示例:

"Doe"

id_number
string

个人受益人的身份证件号码。 当受益人为中国大陆居民且满足以下条件时必填:

  • bank_details.account_currency_codeCNH
  • payment_methodLOCAL
示例:

"110101199001011234"

bank_details
object
address
object

受益人的地址。

  • bank_details.bank_country_code = SGbank_details.account_currency_code = SGD 时无需传入此字段
create_time
string<date/time>

受益人的创建时间。

示例:

"2024-03-01T00:00:00+08:00"

update_time
string<date/time>

受益人的更新时间。

示例:

"2024-03-01T00:00:00+08:00"

additional_info
object

受益人的附加信息。