跳转到主要内容
POST
Check Beneficiary

授权

x-auth-token
string
header
必填

由 UQPAY 提供的登录 API Token。

请求头

x-on-behalf-of
string

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

请求体

application/json

Mastercard Send 查重须提供 CARD、account_number、bank_country_code、currency、entity_type 和 clearing_system,不需要 card_expiry。匹配仅表示已有受益人,不代表卡验证或收款资格验证。

account_number
string
必填

要检查的账号。必须提供非空的 account_number 或 iban;也可同时提供,此时优先使用 account_number。账号仅允许英文字母和数字。

Required string length: 1 - 60
Pattern: ^[a-zA-Z0-9]*$
示例:

"12345678"

entity_type
enum<string>
必填

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

  • COMPANY:企业实体
  • INDIVIDUAL:个人账户
可用选项:
COMPANY,
INDIVIDUAL
示例:

"COMPANY"

payment_method
enum<string>
必填

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

  • LOCAL:通过本地清算系统的境内支付网络处理的付款。
  • SWIFT:通过 SWIFT 网络处理的跨境国际付款。
  • CARD:通过 Mastercard Send 向卡受益人付款。可用性取决于账户授权,以及支付方式查询返回的国家、币种和收款实体配置。
可用选项:
LOCAL,
SWIFT,
CARD
示例:

"LOCAL"

currency
string
必填

受益人银行账户中持有资金的币种。三位字母 ISO 4217 币种代码。

Required string length: 3
示例:

"USD"

bank_country_code
string

银行所在国家或地区的 ISO 3166-1 alpha-2 代码。使用 LOCAL 支付方式时,请同时提供此字段与 clearing_system,指定银行所在国家及币种支持的组合。币种没有默认清算系统时,这两个字段均为必填;仅 USD、GBP、EUR、SGD、CAD、AUD、HKD、MYR、IDR、PHP、INR 有默认清算系统。

Required string length: 2
示例:

"SG"

first_name
string

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

  • 当 payment_method = SWIFT 时:

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

    • 不应用严格的校验规则,支持本地语言字符。
  • 当 bank_details.bank_country_code = SG 且 bank_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 = SG 且 bank_details.account_currency_code = SGD 时无需传入此字段

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

"Doe"

company_name
string

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

  • 当 payment_method = SWIFT 时:

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

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

  • 当 bank_country_code = CN 且 account_currency_code = CNH 且 payment_method = LOCAL 且 entity_type = COMPANY 时,支持中文字符和中文括号 ()。

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

"UQPAY TECHNOLOGY SG PTE LTD"

clearing_system
enum<string>

使用 LOCAL 支付方式时,请提供 bank_country_code 和 currency 支持的清算系统。对于 CNH 等没有默认清算系统的币种,必须同时提供 bank_country_code 与 clearing_system。使用 SWIFT 支付方式时,请填写 SWIFT。

可用选项:
LOCAL,
SWIFT,
ACH,
FAST,
MEPS,
GIRO,
Fedwire,
Faster Payments,
RTGS,
FPS,
EFT,
Interac e-Transfer,
Bill Payment,
CHAPS,
Bank Transfer,
PAYNOW,
MASTERCARD SEND
示例:

"SWIFT"

iban
string

要检查的 IBAN。当 account_number 未提供或为空时使用;两者至少提供一个非空值。

Maximum string length: 36
示例:

"GB82 WEST 1234 5698 7654 32"

additional_info
object

受益人的附加信息。

响应

200 - application/json

受益人校验成功。

payment_method
enum<string>
必填

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

  • LOCAL:通过本地清算系统的境内支付网络处理的付款。
  • SWIFT:通过 SWIFT 网络处理的跨境国际付款。
  • CARD:通过 Mastercard Send 向卡受益人付款。可用性取决于账户授权,以及支付方式查询返回的国家、币种和收款实体配置。
可用选项:
LOCAL
示例:

"LOCAL"

bank_details
object
必填
address
Bank beneficiary address · object
必填

当支付方式为 LOCAL、银行国家为 SG 且账户币种为 SGD 时,未提供的 city、state 和 street_address 可返回空字符串。非空值仍须符合对应字段约束;其他路由须返回完整地址。

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
示例:

"COMPANY"

email
string
必填

受益人的电子邮箱地址。

示例:

"example@uqpay.com"

beneficiary_status
enum<string>
必填

受益人的状态。

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

"ACTIVE"

summary
string
必填

受益人的摘要。

示例:

"John Doe"

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 = SG 且 bank_details.account_currency_code = SGD 时无需传入此字段

  • 当 bank_country_code = CN 且 account_currency_code = CNH 且 payment_method = LOCAL 且 entity_type = COMPANY 时,支持中文字符和中文括号 ()。

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

"UQPAY TECHNOLOGY SG PTE LTD"

first_name
string

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

  • 当 payment_method = SWIFT 时:

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

    • 不应用严格的校验规则,支持本地语言字符。
  • 当 bank_details.bank_country_code = SG 且 bank_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 = SG 且 bank_details.account_currency_code = SGD 时无需传入此字段

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

"Doe"

id_number
string

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

  • bank_details.account_currency_code 为 CNH
  • payment_method 为 LOCAL
示例:

"110101199001011234"

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

受益人的附加信息。