Skip to main content
POST
Check Beneficiary

Authorizations

x-auth-token
string
header
required

The API token for login provided by UQPay.

Headers

x-on-behalf-of
string

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

Body

application/json
entity_type
enum<string>
required

Specifies the type of beneficiary entity to filter by. Valid values are:

  • COMPANY : corporate entities
  • INDIVIDUAL : personal accounts
Available options:
COMPANY,
INDIVIDUAL
account_number
string
required

Account number, mostly for non-european countries, either account_number or iban should be filled.

Only English letters (uppercase and lowercase) and digits are allowed; dashes or other special characters are not permitted.

Maximum string length: 60
Pattern: ^[a-zA-Z0-9]*$
Example:

"12345678"

payment_method
enum<string>
required

The payment method needs to be specified to ensure that accurate banking details are captured and validated for the specified payment method.

  • LOCAL: Payment processed through domestic payment networks with local clearing systems.
  • SWIFT: International payment processed through the SWIFT network for cross-border transfers.
Available options:
LOCAL,
SWIFT
Example:

"LOCAL"

currency
string
required

Currency in which money is held in the beneficiary's bank account. Three-letter ISO 4217 currency code.

Required string length: 3
Example:

"USD"

first_name
string

First name of the beneficiary, only exist when the entity_type is INDIVIDUAL.

  • When payment_method = SWIFT:

    • Only English letters, numbers, special characters (half-width format), and spaces can be included.
    • Allowed special characters: -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • When payment_method = LOCAL:

    • No strict validation rules apply, local language characters are supported.
  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

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

"John"

last_name
string

Last name of the beneficiary, only exist when the entity_type is INDIVIDUAL.

  • When payment_method = SWIFT:

    • Only English letters, numbers, special characters (half-width format), and spaces can be included.
    • Allowed special characters: -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • When payment_method = LOCAL:

    • No strict validation rules apply, local language characters are supported.
  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

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

"Doe"

company_name
string

Company name of the beneficiary, only exist when the entity_type is COMPANY.

  • When payment_method = SWIFT:

    • Only English letters, numbers, special characters (half-width format), and spaces can be included.
    • Allowed special characters: -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • When payment_method = LOCAL:

    • No strict validation rules apply, local language characters are supported.
  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

  • When bank_country_code = CN & account_currency_code = CNH & payment_method = LOCAL & entity_type = COMPANY, Chinese characters and Chinese parentheses () are supported.

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

"UQPAY TECHNOLOGY SG PTE LTD"

clearing_system
enum<string>

Specifies the clearing system to be used for the transaction. The available options vary by currency and correspond to the local payment infrastructure.

  • USD: ACH, Fedwire, SWIFT
  • SGD: FAST, GIRO, RTGS, SWIFT, PayNow
  • CNH: LOCAL, SWIFT
  • HKD: ACH, FPS, RTGS, SWIFT
  • EUR: LOCAL, SWIFT
  • CAD: EFT, Interac e-Transfer, SWIFT, Bill Payment
  • MYR: LOCAL
  • GBP: Faster Payments, CHAPS, SWIFT
  • IDR: LOCAL
  • JPY: LOCAL, SWIFT
  • NZD: Bank Transfer, SWIFT
  • AUD: Bank Transfer, SWIFT
Available options:
LOCAL,
SWIFT,
ACH,
FAST,
MEPS,
GIRO,
Fedwire,
Faster Payments,
RTGS,
FPS,
EFT,
Interac e-Transfer,
Bill Payment,
CHAPS,
Bank Transfer,
ACH,
Fedwire,
SWIFT,
FAST,
GIRO,
RTGS,
LOCAL,
FPS,
EFT,
Interac e-Transfer,
Bill Payment,
Faster Payments,
CHAPS,
Bank Transfer
Example:

"SWIFT"

iban
string

For the following countries/regions, IBAN is mandatory (mostly applicable to European and some other countries):

Country Codes: AL, AD, AT, AZ, BH, BY, BE, BA, BR, BG, CR, HR, CY, CZ, DK, DO, EG, SV, EE, FO, FI, FR, GE, DE, GI, GR, GL, GT, VA, HU, IS, IQ, IE, IL, IT, JO, KZ, XK, KW, LV, LB, LY, LI, LT, LU, MT, MR, MU, MD, MC, ME, NL, MK, NO, PK, PS, PL, PT, QA, RO, LC, SM, ST, SA, RS, SC, SK, SI, ES, SD, SE, CH, TL, TN, TR, UA, AE, GB, VG.

If the beneficiary bank is located in any of the above-listed countries/regions, IBAN must be provided.

Maximum string length: 36
Example:

"GB82 WEST 1234 5698 7654 32"

additional_info
object

Additional information for beneficiaries.

Response

200 - application/json

Beneficiary check successfully.

beneficiary_id
string<uuid>
required

Universally unique identifier (UUID v4) of the beneficiary.

Example:

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

short_reference_id
string
required

The reference generated by the system to identify the entity.

Example:

"P220406-LLCVLRM"

entity_type
enum<string>
required

Specifies the type of beneficiary entity to filter by. Valid values are:

  • COMPANY : corporate entities
  • INDIVIDUAL : personal accounts
Available options:
COMPANY,
INDIVIDUAL
payment_method
enum<string>
required

The payment method needs to be specified to ensure that accurate banking details are captured and validated for the specified payment method.

  • LOCAL: Payment processed through domestic payment networks with local clearing systems.
  • SWIFT: International payment processed through the SWIFT network for cross-border transfers.
Available options:
LOCAL,
SWIFT
Example:

"LOCAL"

email
string
required

Email address of the beneficiary.

Example:

"example@uqpay.com"

beneficiary_status
enum<string>
required

Status of the beneficiary.

  • ACTIVE: The beneficiary has been fully verified and is eligible to receive payments.
  • PENDING: The beneficiary is undergoing verification process and cannot yet receive payments.
Available options:
ACTIVE,
PENDING
Example:

"ACTIVE"

nickname
string

Nickname of the beneficiary.

Maximum string length: 120
Example:

"John Doe"

company_name
string

Company name of the beneficiary, only exist when the entity_type is COMPANY.

  • When payment_method = SWIFT:

    • Only English letters, numbers, special characters (half-width format), and spaces can be included.
    • Allowed special characters: -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • When payment_method = LOCAL:

    • No strict validation rules apply, local language characters are supported.
  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

  • When bank_country_code = CN & account_currency_code = CNH & payment_method = LOCAL & entity_type = COMPANY, Chinese characters and Chinese parentheses () are supported.

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

"UQPAY TECHNOLOGY SG PTE LTD"

summary
string

Summary of the beneficiary.

Example:

"John Doe"

first_name
string

First name of the beneficiary, only exist when the entity_type is INDIVIDUAL.

  • When payment_method = SWIFT:

    • Only English letters, numbers, special characters (half-width format), and spaces can be included.
    • Allowed special characters: -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • When payment_method = LOCAL:

    • No strict validation rules apply, local language characters are supported.
  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

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

"John"

last_name
string

Last name of the beneficiary, only exist when the entity_type is INDIVIDUAL.

  • When payment_method = SWIFT:

    • Only English letters, numbers, special characters (half-width format), and spaces can be included.
    • Allowed special characters: -_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……
  • When payment_method = LOCAL:

    • No strict validation rules apply, local language characters are supported.
  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

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

"Doe"

id_number
string

The identification number of the individual beneficiary.
Mandatory when the beneficiary is a Mainland China resident and the following conditions are met:

  • bank_details.account_currency_code is CNH
  • payment_method is LOCAL
Example:

"110101199001011234"

bank_details
object
address
object

Address of the beneficiary.

  • No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD
create_time
string<date/time>

Create time of the beneficiary.

Example:

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

update_time
string<date/time>

Update time of the beneficiary.

Example:

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

additional_info
object

Additional information for beneficiaries.