Recipients (Beneficiary)

Recipients and beneficiaries refer to the same party: the person or company that receives funds from a payout. The Dashboard uses “Recipient” in the user interface, while the API uses “Beneficiary” in endpoint names, request fields, and webhook payloads. You can create and manage beneficiaries from the Dashboard or through the API. Use the API flow when your integration needs to onboard beneficiaries programmatically, validate whether a beneficiary already exists, or maintain beneficiary records for multiple sub-accounts.

Dashboard flow

Open Transfer in the merchant portal, then select Recipients.
Select Add recipient.
Choose whether the recipient is a UQPAY account or a bank recipient. For bank recipients, select the bank country, currency, and available payment method before entering the required bank details.
Review and save the recipient. Its verification status appears in the Recipients list; recipients that require updated regulatory information are marked in the list.

API integration flow

Use this flow when creating beneficiaries through API:

Get supported payment methods for the beneficiary’s bank country and currency.
Check whether a matching beneficiary already exists.
Create the beneficiary if no reusable beneficiary is found.
Listen for the beneficiary webhook and retrieve the beneficiary status.
Use the beneficiary_id when creating payouts.
Keep beneficiary records up to date with list, retrieve, update, and delete APIs.

If you manage beneficiaries for a sub-account, pass the sub-account’s account_id in the x-on-behalf-of header for beneficiary APIs. If x-on-behalf-of is omitted, the request is executed for the authenticated master account.

Step 1: List payment methods

Before collecting bank details from your user, call List Payment Methods with the beneficiary bank country and account currency.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/paymentmethods?country=SG&currency=SGD' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'

The response returns one record per supported clearing_systems and payment_method combination for that country and currency.

{
  "data": [
    {
      "clearing_systems": "FAST",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "GIRO",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "LOCAL",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "MEPS",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "PAYNOW",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "RTGS",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "LOCAL",
      "validation_field": []
    },
    {
      "clearing_systems": "SWIFT",
      "country": "SG",
      "currency": "SGD",
      "payment_method": "SWIFT",
      "validation_field": []
    }
  ]
}

Use this response to decide which fields to show in your beneficiary creation form.

Field	How to use it
`payment_method`	Use `LOCAL` for domestic rails or `SWIFT` for international bank transfers.
`clearing_systems`	Put the selected value in `bank_details.clearing_system`, for example `FAST`, `Fedwire`, `Faster Payments`, or `SWIFT`.
`country`	Use the two-letter country code as `bank_details.bank_country_code`.
`currency`	Use the three-letter currency code as `bank_details.account_currency_code`.

Step 2: Prepare beneficiary details

The requirements below apply to LOCAL/SWIFT bank beneficiaries. For card recipients, use the Mastercard Send requirements. Create Beneficiary supports company and individual beneficiaries. For a company beneficiary, collect:

entity_type = COMPANY
company_name
Optional email and nickname
payment_method
bank_details
address
additional_info, when required by the payout country or currency

For an individual beneficiary, collect:

entity_type = INDIVIDUAL
first_name and last_name
Optional email, nickname, and id_number
payment_method
bank_details
address
additional_info, when required by the payout country or currency

The most important bank_details fields are:

Field	Notes
`bank_country_code`	Two-letter country code of the beneficiary bank.
`account_currency_code`	Currency of the beneficiary bank account.
`account_holder`	Name on the beneficiary bank account.
`account_number`	Required for many local rails.
`iban`	Required for many IBAN countries.
`swift_code`	Required for SWIFT transfers and some local rails.
`clearing_system`	Use a value returned by List Payment Methods.
`routing_code_type1` and `routing_code_value1`	Required for some rails, such as `aba`, `ach`, `sort_code`, `bsb_code`, `bank_code`, `ifsc`, or `cnaps_number`.
`routing_code_type2` and `routing_code_value2`	Required for some rails, such as branch code for certain CAD EFT payouts.

Some currencies require additional_info. For example, COP payouts require msisdn, and may require id_type and id_number for individual beneficiaries or tax_id for company beneficiaries. HKD local payouts also require msisdn.

Step 3: Check for an existing beneficiary

Before creating a new beneficiary, call Check Beneficiary. This helps avoid duplicate records when the same bank account has already been saved.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/check' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --data '{
    "entity_type": "COMPANY",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "account_number": "1234567890",
    "payment_method": "LOCAL",
    "currency": "SGD",
    "bank_country_code": "SG",
    "clearing_system": "FAST"
  }'

If a matching beneficiary exists, the response includes beneficiary_id. Reuse that ID when creating a payout. If no match is found, the response returns an empty beneficiary_id.

{
  "beneficiary_id": ""
}

Step 4: Create the beneficiary

Call Create Beneficiary only when you do not already have a reusable beneficiary_id.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --header 'x-idempotency-key: d75238ce-7e56-474f-a242-77cb100bafc1' \
  --data '{
    "entity_type": "COMPANY",
    "email": "finance@example.com",
    "nickname": "Singapore supplier",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "payment_method": "LOCAL",
    "bank_details": {
      "bank_name": "DBS Bank Ltd",
      "bank_address": "12 Marina Boulevard, Singapore",
      "bank_country_code": "SG",
      "account_holder": "UQPAY TECHNOLOGY SG PTE LTD",
      "account_currency_code": "SGD",
      "account_number": "1234567890",
      "clearing_system": "FAST",
      "swift_code": "DBSSSGSG"
    },
    "address": {
      "country": "SG",
      "city": "Singapore",
      "street_address": "12 Marina Boulevard",
      "postal_code": "018982",
      "state": "Singapore",
      "nationality": "SG"
    },
    "additional_info": {}
  }'

The response returns the beneficiary identifiers:

{
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
  "short_reference_id": "BF250917-WQEQ2D7Q"
}

Store the beneficiary_id. This is the value you should pass in beneficiary_id when creating a payout.

Step 5: Handle the beneficiary webhook

Subscribe to Beneficiary Created events.

Event type	Meaning	Recommended action
`beneficiary.successful`	The beneficiary was created successfully.	Store or activate the beneficiary in your system.
`beneficiary.failed`	Beneficiary creation failed.	Mark the beneficiary as failed and ask the user to correct the details.

After receiving the webhook, you can call Retrieve Beneficiary to confirm the latest beneficiary_status.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/beneficiaries/e15436e2-35e8-4680-920d-4852940c18ba' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'

Only use an ACTIVE beneficiary for payouts. If the beneficiary remains PENDING, wait for the final result before initiating payout.

Step 6: Use the beneficiary in a payout

When creating a payout, pass the saved beneficiary_id instead of repeating all beneficiary details.

{
  "currency": "SGD",
  "amount": "1000.00",
  "purpose_code": "PROFESSIONAL_SERVICES",
  "payout_reference": "INV-2026-001",
  "fee_paid_by": "OURS",
  "payout_date": "2026-07-10",
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba"
}

Using beneficiary_id keeps payout requests smaller and reduces the risk of sending inconsistent bank details.

Managing beneficiaries

Use these APIs to keep your saved beneficiary records in sync:

API	When to use it
List Beneficiaries	Search and display saved beneficiaries.
Retrieve Beneficiary	Show full beneficiary details before payout or after webhook events.
Update Beneficiary	Correct bank details, address, nickname, or other editable fields. Entity type cannot be changed.
Delete Beneficiary	Remove a beneficiary that should no longer be used for new payouts.

Integration recommendations

Always call List Payment Methods before designing the input form for a new country and currency.
Use Check Beneficiary before Create Beneficiary to avoid duplicates.
Store both beneficiary_id and short_reference_id.
Keep a local mapping between your customer or vendor ID and UQPAY beneficiary_id.
Use x-on-behalf-of consistently when managing beneficiaries for sub-accounts.
Do not create payouts until the beneficiary is ACTIVE.
Reuse existing beneficiaries for repeat payouts to the same bank account.
Use idempotency keys for create and update requests.

API Doc

Mastercard Send card recipients

Before collecting card details, query List Payment Methods with country, currency, and an explicit entity_type. Supported countries and currencies depend on the methods returned for your account; the bank payout coverage list does not establish card coverage.

Field	Requirement
`payment_method`	Use `CARD`.
`bank_details.clearing_system`	Use `MASTERCARD SEND`.
`bank_details.account_number`	Digits only, no spaces or hyphens. Satisfy both the 11–19 digit base check and the length rule returned by List Payment Methods.
`bank_details.card_expiry`	Use `YYYY-MM`. The current month is accepted; past months are rejected.
`bank_details.account_holder`	Required. Names are derived from this value: the last word is the individual last name, preceding words are the first name; for companies it supplies the company name.
`bank_details.account_currency_code`, `bank_details.bank_country_code`	Use a configured currency, country, and recipient type combination.
`address.country`, `address.city`, `address.street_address`	Required for companies; state and postal code are optional. Individuals do not inherit bank-transfer address requirements.

Bank name, bank address, SWIFT code, IBAN, and routing codes are not Mastercard requirements. Additional field rules returned by List Payment Methods still apply. Its clearing_systems field is plural, and validation_field contains rule objects for Mastercard. A metadata path such as beneficiary.beneficiary_bank_details.card_expiry maps to the Gateway field bank_details.card_expiry; do not copy that metadata path into the request. Check Beneficiary uses the card number, country, currency, entity type, and clearing system without card_expiry. A match means that a saved beneficiary exists, not that a card can receive funds. Create and update use the same complete card object; update is not PATCH. Keep the expiry current before creating a payout. See the captured card recipient examples.

Overview

Virtual Account

Payout & Deposit

Foreign Exchange

Reference

Dashboard flow

API integration flow

Step 1: List payment methods

Step 2: Prepare beneficiary details

Step 3: Check for an existing beneficiary

Step 4: Create the beneficiary

Step 5: Handle the beneficiary webhook

Step 6: Use the beneficiary in a payout

Managing beneficiaries

Integration recommendations

API Doc

Mastercard Send card recipients

​Dashboard flow

​API integration flow

​Step 1: List payment methods

​Step 2: Prepare beneficiary details

​Step 3: Check for an existing beneficiary

​Step 4: Create the beneficiary

​Step 5: Handle the beneficiary webhook

​Step 6: Use the beneficiary in a payout

​Managing beneficiaries

​Integration recommendations

​API Doc

​Mastercard Send card recipients

Dashboard flow

API integration flow

Step 1: List payment methods

Step 2: Prepare beneficiary details

Step 3: Check for an existing beneficiary

Step 4: Create the beneficiary

Step 5: Handle the beneficiary webhook

Step 6: Use the beneficiary in a payout

Managing beneficiaries

Integration recommendations

API Doc

Mastercard Send card recipients