v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB

Beneficiaries

Retrieve Beneficiary

Get a specific beneficiary by specifying the beneficiary_id.

get/v1/beneficiaries/{id}

Path parameters

idstring uuid required

Example:b3d9d2d5-4c12-4946-a09d-953e82sed2b0

Universally unique identifier (UUID v4) of a resource.

Headers

x-on-behalf-ofstring

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 API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

Response

OK - Successfully retrieved a beneficiary.

beneficiary_idstring uuid required

Universally unique identifier (UUID v4) of the beneficiary.

short_reference_idstring required

The reference generated by the system to identify the entity.

entity_type'COMPANY' | 'INDIVIDUAL' required

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

COMPANY : corporate entities
INDIVIDUAL : personal accounts

emailstring required

Email address of the beneficiary.

nicknamestring

Nickname of the beneficiary.

beneficiary_status'ACTIVE' | 'PENDING' 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.

company_namestring

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.

summarystring required

Summary of the beneficiary.

first_namestring

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

last_namestring

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

id_numberstring

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

create_timestring date/time

The timestamp when the record was created in the system. Timestamp follows the ISO 8601 standard.

update_timestring date/time

Example response

{
  "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "short_reference_id": "P220406-LLCVLRM",
  "payment_method": {
    "card": {
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "12025550123",
        "address": {
          "country_code": "SG",
          "city": "Singapore",
          "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
          "postcode": "924011"
        }
      }
    }
  },
  "email": "example@uqpay.com",
  "nickname": "John Doe",
  "beneficiary_status": "ACTIVE",
  "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_number": "12345678",
    "iban": "GB82 WEST 1234 5698 7654 32",
    "swift_code": "WELGBE22",
    "clearing_system": "GIRO",
    "routing_code_type1": "aba",
    "routing_code_value1": "123456789",
    "routing_code_type2": "ach",
    "routing_code_value2": "123456789"
  },
  "address": {
    "country": "SG",
    "nationality": "SG",
    "city": "Singapore",
    "street_address": "123 Main St",
    "postal_code": "123456",
    "state": "CA"
  },
  "create_time": "2024-03-01T00:00:00+08:00",
  "update_time": "2024-03-01T00:00:00+08:00",
  "additional_info": {
    "organization_code": "91210106MA0P46BWXY",
    "id_type": "PASSPORT",
    "id_number": "AB1234567",
    "tax_id": "123456789",
    "msisdn": "+65111111"
  }
}