v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB

Beneficiaries

List Beneficiaries

Get list of beneficiaries.

get/v1/beneficiaries

Query parameters

page_sizeinteger required

Example:10

The maximum number of items to return per page. This number can be between 1 - 100

page_numberinteger required

Example:1

The page number to retrieve the next set of items. The number has to be greater than 1.

entity_type'COMPANY' | 'INDIVIDUAL'

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

COMPANY : corporate entities
INDIVIDUAL : personal accounts

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

COMPANY : corporate entities
INDIVIDUAL : personal accounts

nicknamestring

Nickname of the beneficiary.

Example:John Doe

Nickname of the beneficiary

currencystring

Example:USD

Specifies the currency for which transactions are retrieved. Currency codes follow the ISO 4217 standard.

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.

Example:UQPAY TECHNOLOGY SG PTE LTD

Company of the beneficiary

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 list of beneficiaries.

total_pagesinteger

The total pages of available items.

total_itemsinteger

The total counts of available items.

Example response

{
  "total_pages": 10,
  "total_items": 105,
  "data": [
    {
      "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"
      }
    }
  ]
}