Skip to main content
POST
/
v1
/
beneficiaries
/
check
Check Beneficiary
curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --data '
{
  "entity_type": "COMPANY",
  "account_number": "12345678",
  "payment_method": "LOCAL",
  "currency": "USD",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
  "clearing_system": "SWIFT",
  "iban": "GB82 WEST 1234 5698 7654 32",
  "additional_info": {
    "proxy_id": "<string>"
  }
}
'
{
  "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "short_reference_id": "P220406-LLCVLRM",
  "entity_type": "COMPANY",
  "payment_method": "LOCAL",
  "email": "example@uqpay.com",
  "beneficiary_status": "ACTIVE",
  "nickname": "John Doe",
  "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
  "summary": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "id_number": "110101199001011234",
  "bank_details": {
    "bank_name": "Bank of America",
    "bank_address": "123 Main St",
    "bank_country_code": "SG",
    "account_holder": "John Doe",
    "account_currency_code": "USD",
    "swift_code": "WELGBE22",
    "clearing_system": "GIRO",
    "account_number": "12345678",
    "iban": "GB82 WEST 1234 5698 7654 32",
    "routing_code_type1": "aba",
    "routing_code_value1": "123456789",
    "routing_code_type2": "ach",
    "routing_code_value2": "123456789"
  },
  "address": {
    "country": "SG",
    "city": "Singapore",
    "street_address": "123 Main St",
    "postal_code": "123456",
    "state": "CA",
    "nationality": "SG"
  },
  "create_time": "2024-03-01T00:00:00+08:00",
  "update_time": "2024-03-01T00:00:00+08:00",
  "additional_info": {
    "organization_code": "91210106MA0P46BWXY",
    "proxy_id": "<string>",
    "id_type": "PASSPORT",
    "id_number": "AB1234567",
    "tax_id": "123456789",
    "msisdn": "+65111111"
  }
}

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.

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: NPP, Bank Transfer, BPAY, SWIFT
Available options:
LOCAL,
SWIFT,
ACH,
FAST,
MEPS,
GIRO,
Fedwire,
Faster Payments,
RTGS,
FPS,
EFT,
Interac e-Transfer,
Bill Payment,
CHAPS,
Bank Transfer,
NPP,
ACH,
Fedwire,
SWIFT,
FAST,
GIRO,
RTGS,
LOCAL,
FPS,
EFT,
Interac e-Transfer,
Bill Payment,
Faster Payments,
CHAPS,
Bank Transfer,
NPP,
BPAY,
BPAY
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

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.

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.

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.