Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Beneficiaries

Check Beneficiary

Check if a beneficiary is exists or not.

post/v1/beneficiaries/check

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.

Request body

entity_type'COMPANY' | 'INDIVIDUAL' required

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

  • COMPANY : corporate entities
  • INDIVIDUAL : personal accounts
account_numberstring 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.

currencystring required

Three-letter currency code

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

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.

clearing_system'LOCAL' | 'SWIFT' | 'ACH' | 'FAST' | 'MEPS' | 'GIRO' | 'Fedwire' | 'Faster Payments' | 'RTGS' | 'FPS' | 'EFT' | 'Interac e-Transfer' | 'Bill Payment' | 'CHAPS' | 'Bank Transfer' | 'PAYNOW'

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
ibanstring

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.

Example request

{
  "account_number": "12345678",
  "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"
        }
      }
    }
  },
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
  "clearing_system": "SWIFT",
  "iban": "GB82 WEST 1234 5698 7654 32"
}

Response

Beneficiary check successfully.

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"
  }
}