Create Beneficiary

post

https://api-sandbox.uqpaytech.com/api/v1/beneficiaries

Create a new beneficiary for payout.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

string

Email address of the beneficiary.

entity_type

string

required

Defaults to INDIVIDUAL

payment_method

string

enum

required

The payment method needs to be specified to ensure that accurate banking details are captured and validated for the specified payment method.

Show Details

LOCAL	Payment processed through domestic payment networks with local clearing systems.
SWIFT	International payment processed through the SWIFT network for cross-border transfers.

Allowed:

nickname

string

length ≤ 120

Nickname of the beneficiary.

first_name

string

required

length ≤ 45

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_name

string

required

length ≤ 45

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_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

bank_details

object

required

address

object

required

Address of the beneficiary.

No need to pass this field when bank_details.bank_country_code = SG & bank_details.account_currency_code = SGD

additional_info

object

Additional information for beneficiaries.

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.

x-idempotency-key

uuid

required

A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures.

Responses

200Beneficiary creation successfully.

400Bad Request - The request was unacceptable, often due to missing a required parameter.

401Unauthorized - No valid API key or token provided.