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": "11020075767",
  "payment_method": "SWIFT",
  "currency": "SGD",
  "bank_country_code": "SG",
  "company_name": "UQPAY PTE. LTD."
}
'

import requests

url = "https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check"

payload = {
    "entity_type": "COMPANY",
    "account_number": "11020075767",
    "payment_method": "SWIFT",
    "currency": "SGD",
    "bank_country_code": "SG",
    "company_name": "UQPAY PTE. LTD."
}
headers = {
    "x-auth-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-auth-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity_type: 'COMPANY',
    account_number: '11020075767',
    payment_method: 'SWIFT',
    currency: 'SGD',
    bank_country_code: 'SG',
    company_name: 'UQPAY PTE. LTD.'
  })
};

fetch('https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entity_type' => 'COMPANY',
    'account_number' => '11020075767',
    'payment_method' => 'SWIFT',
    'currency' => 'SGD',
    'bank_country_code' => 'SG',
    'company_name' => 'UQPAY PTE. LTD.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-auth-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check"

	payload := strings.NewReader("{\n  \"entity_type\": \"COMPANY\",\n  \"account_number\": \"11020075767\",\n  \"payment_method\": \"SWIFT\",\n  \"currency\": \"SGD\",\n  \"bank_country_code\": \"SG\",\n  \"company_name\": \"UQPAY PTE. LTD.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-auth-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check")
  .header("x-auth-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entity_type\": \"COMPANY\",\n  \"account_number\": \"11020075767\",\n  \"payment_method\": \"SWIFT\",\n  \"currency\": \"SGD\",\n  \"bank_country_code\": \"SG\",\n  \"company_name\": \"UQPAY PTE. LTD.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-auth-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entity_type\": \"COMPANY\",\n  \"account_number\": \"11020075767\",\n  \"payment_method\": \"SWIFT\",\n  \"currency\": \"SGD\",\n  \"bank_country_code\": \"SG\",\n  \"company_name\": \"UQPAY PTE. LTD.\"\n}"

response = http.request(request)
puts response.read_body

{
  "beneficiary_id": "caf351ff-be40-4caa-9288-133ba6d6d4b1",
  "short_reference_id": "BF260910-E9MJ2KHL",
  "entity_type": "COMPANY",
  "payment_method": "SWIFT",
  "email": "contract-452d7f6f-4ef2-4751-8af5-38760b977a22@example.com",
  "nickname": "Updated 452d7f6f",
  "company_name": "UQPAY PTE. LTD.",
  "summary": "",
  "id_number": "",
  "first_name": "",
  "last_name": "",
  "bank_details": {
    "bank_name": "GREEN LINK DIGITAL BANK",
    "bank_address": "MAPLETREE BUSINESS CITY 20 PASIR PANJANG ROAD 07-25/28 SINGAPORE",
    "bank_country_code": "SG",
    "account_holder": "UQPAY PTE. LTD.",
    "account_currency_code": "SGD",
    "account_number": "11020075767",
    "iban": "",
    "swift_code": "GLDTSGSGXXX",
    "clearing_system": "SWIFT",
    "routing_code_type1": "",
    "routing_code_value1": "",
    "routing_code_type2": "",
    "routing_code_value2": ""
  },
  "address": {
    "nationality": "",
    "country": "SG",
    "city": "Singapore",
    "street_address": "Sandbox Contract Test",
    "postal_code": 18989,
    "state": "Singapore"
  },
  "beneficiary_status": "ACTIVE",
  "additional_info": {
    "organization_code": "",
    "proxy_id": "",
    "msisdn": "",
    "id_type": "",
    "id_number": "",
    "tax_id": ""
  }
}

POST

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": "11020075767",
  "payment_method": "SWIFT",
  "currency": "SGD",
  "bank_country_code": "SG",
  "company_name": "UQPAY PTE. LTD."
}
'

import requests

url = "https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check"

payload = {
    "entity_type": "COMPANY",
    "account_number": "11020075767",
    "payment_method": "SWIFT",
    "currency": "SGD",
    "bank_country_code": "SG",
    "company_name": "UQPAY PTE. LTD."
}
headers = {
    "x-auth-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-auth-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity_type: 'COMPANY',
    account_number: '11020075767',
    payment_method: 'SWIFT',
    currency: 'SGD',
    bank_country_code: 'SG',
    company_name: 'UQPAY PTE. LTD.'
  })
};

fetch('https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entity_type' => 'COMPANY',
    'account_number' => '11020075767',
    'payment_method' => 'SWIFT',
    'currency' => 'SGD',
    'bank_country_code' => 'SG',
    'company_name' => 'UQPAY PTE. LTD.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-auth-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check"

	payload := strings.NewReader("{\n  \"entity_type\": \"COMPANY\",\n  \"account_number\": \"11020075767\",\n  \"payment_method\": \"SWIFT\",\n  \"currency\": \"SGD\",\n  \"bank_country_code\": \"SG\",\n  \"company_name\": \"UQPAY PTE. LTD.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-auth-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check")
  .header("x-auth-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entity_type\": \"COMPANY\",\n  \"account_number\": \"11020075767\",\n  \"payment_method\": \"SWIFT\",\n  \"currency\": \"SGD\",\n  \"bank_country_code\": \"SG\",\n  \"company_name\": \"UQPAY PTE. LTD.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-auth-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entity_type\": \"COMPANY\",\n  \"account_number\": \"11020075767\",\n  \"payment_method\": \"SWIFT\",\n  \"currency\": \"SGD\",\n  \"bank_country_code\": \"SG\",\n  \"company_name\": \"UQPAY PTE. LTD.\"\n}"

response = http.request(request)
puts response.read_body

{
  "beneficiary_id": "caf351ff-be40-4caa-9288-133ba6d6d4b1",
  "short_reference_id": "BF260910-E9MJ2KHL",
  "entity_type": "COMPANY",
  "payment_method": "SWIFT",
  "email": "contract-452d7f6f-4ef2-4751-8af5-38760b977a22@example.com",
  "nickname": "Updated 452d7f6f",
  "company_name": "UQPAY PTE. LTD.",
  "summary": "",
  "id_number": "",
  "first_name": "",
  "last_name": "",
  "bank_details": {
    "bank_name": "GREEN LINK DIGITAL BANK",
    "bank_address": "MAPLETREE BUSINESS CITY 20 PASIR PANJANG ROAD 07-25/28 SINGAPORE",
    "bank_country_code": "SG",
    "account_holder": "UQPAY PTE. LTD.",
    "account_currency_code": "SGD",
    "account_number": "11020075767",
    "iban": "",
    "swift_code": "GLDTSGSGXXX",
    "clearing_system": "SWIFT",
    "routing_code_type1": "",
    "routing_code_value1": "",
    "routing_code_type2": "",
    "routing_code_value2": ""
  },
  "address": {
    "nationality": "",
    "country": "SG",
    "city": "Singapore",
    "street_address": "Sandbox Contract Test",
    "postal_code": 18989,
    "state": "Singapore"
  },
  "beneficiary_status": "ACTIVE",
  "additional_info": {
    "organization_code": "",
    "proxy_id": "",
    "msisdn": "",
    "id_type": "",
    "id_number": "",
    "tax_id": ""
  }
}

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

Account number provided
IBAN provided

For Mastercard Send, provide CARD, account_number, bank_country_code, currency, entity_type, and clearing_system. No card_expiry is required. A match identifies a saved beneficiary; it does not verify the card or its ability to receive funds.

account_number

string

required

Account number to check. Provide a non-empty account_number or iban; both may be provided, in which case account_number takes precedence. Only English letters and digits are allowed in the account number.

Required string length: 1 - 60

Pattern: ^[a-zA-Z0-9]*$

Example:

"12345678"

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

Example:

"COMPANY"

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.

LOCAL: Payment processed through domestic payment networks with local clearing systems.
SWIFT: International payment processed through the SWIFT network for cross-border transfers.
CARD: Payment to card recipients through Mastercard Send. Availability depends on your account authorization and the country, currency, and recipient entity type returned by List Payment Methods.

Available options:

LOCAL,

SWIFT,

CARD

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"

bank_country_code

string

Bank country or region, using its ISO 3166-1 alpha-2 code. For LOCAL payments, provide this field together with clearing_system to select a supported combination for the bank country and currency. Both fields are required when the currency has no default clearing system: defaults are available only for USD, GBP, EUR, SGD, CAD, AUD, HKD, MYR, IDR, PHP, and INR.

Required string length: 2

Example:

"SG"

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>

For LOCAL payments, provide a clearing system supported for bank_country_code and currency. For currencies without a default clearing system, including CNH, both bank_country_code and clearing_system are required. For SWIFT payments, use SWIFT.

Available options:

LOCAL,

SWIFT,

ACH,

FAST,

MEPS,

GIRO,

Fedwire,

Faster Payments,

RTGS,

FPS,

EFT,

Interac e-Transfer,

Bill Payment,

CHAPS,

Bank Transfer,

PAYNOW,

MASTERCARD SEND

Example:

"SWIFT"

iban

string

IBAN to check. Used when account_number is omitted or empty; at least one of the two must be non-empty.

Maximum string length: 36

Example:

"GB82 WEST 1234 5698 7654 32"

additional_info

object

Additional information for beneficiaries.

Show child attributes

Response

200 - application/json

Beneficiary check successfully.

BeneficiaryCheckResponse
BeneficiaryCheckResponse
BeneficiaryCheckResponse

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.

LOCAL: Payment processed through domestic payment networks with local clearing systems.
SWIFT: International payment processed through the SWIFT network for cross-border transfers.
CARD: Payment to card recipients through Mastercard Send. Availability depends on your account authorization and the country, currency, and recipient entity type returned by List Payment Methods.

Available options:

LOCAL

Example:

"LOCAL"

bank_details

object

required

Show child attributes

address

Bank beneficiary address · object

required

For LOCAL payments to a bank in SG with account currency SGD, city, state, and street_address may be empty strings when not provided. Non-empty values follow the corresponding field constraints. Other routes require a complete address.

Bank beneficiary address
Mastercard beneficiary address

Show child attributes

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

Example:

"COMPANY"

string

required

Email address of the beneficiary.

Example:

"example@uqpay.com"

beneficiary_status

enum<string>

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.

Available options:

ACTIVE,

PENDING

Example:

"ACTIVE"

summary

string

required

Summary of the beneficiary.

Example:

"John Doe"

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"

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"

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.

Show child attributes