Skip to main content
GET
/
v1
/
beneficiaries
/
{id}
Retrieve Beneficiary
curl --request GET \
  --url https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/{id} \
  --header 'x-auth-token: <api-key>'
{
  "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "short_reference_id": "P220406-LLCVLRM",
  "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"
  }
}

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.

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.

Path Parameters

​
id
string<uuid>
required

Universally unique identifier (UUID v4) of a resource.

Example:

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

Response

200 - application/json

OK - Successfully retrieved a beneficiary.

​
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.