Create Payout

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "currency": "USD",
  "amount": "1000.00",
  "purpose_code": "AUDIO_VISUAL_SERVICES",
  "payout_reference": "026073150",
  "fee_paid_by": "SHARED",
  "payout_date": "2024-03-01",
  "quote_id": "784832f7-1f8a-4b08-ac2a-8719b5b2a590",
  "payout_currency": "SGD",
  "payout_amount": 100,
  "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "beneficiary": {
    "entity_type": "COMPANY",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "payment_method": "LOCAL",
    "bank_details": {
      "bank_name": "Bank of America",
      "bank_address": "123 Main St",
      "bank_country_code": "SG",
      "account_holder": "John Doe",
      "account_currency_code": "USD",
      "swift_code": "WELGBE22",
      "clearing_system": "GIRO",
      "account_number": "12345678",
      "iban": "GB82 WEST 1234 5698 7654 32",
      "routing_code_type1": "aba",
      "routing_code_value1": "123456789",
      "routing_code_type2": "ach",
      "routing_code_value2": "123456789"
    },
    "address": {
      "country": "SG",
      "city": "Singapore",
      "street_address": "123 Main St",
      "postal_code": "123456",
      "state": "CA",
      "nationality": "SG"
    },
    "email": "example@uqpay.com",
    "nickname": "John Doe",
    "additional_info": {
      "organization_code": "91210106MA0P46BWXY",
      "proxy_id": "<string>",
      "id_type": "PASSPORT",
      "id_number": "AB1234567",
      "tax_id": "123456789",
      "msisdn": "+65111111"
    }
  },
  "is_payer": "N",
  "payer_id": "d36384c8-5df1-4ede-b054-804578601ae7",
  "documentation": [
    {
      "file": "data:image/png;base64,TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4=",
      "file_id": "5135e6cc-28b6-4889-81dc-3b86a09e1395"
    }
  ]
}
'

{
  "payout_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "short_reference_id": "P220406-LLCVLRM"
}

Payouts

Create Payout

Creates a new payout to a beneficiary. With development and support from SWIFT and local payment rails, you can make faster and more cost-effective international payments to your overseas corporate accounts, suppliers, and employees.

This API supports multiple payment modes, including standard payouts and Payment-On-Behalf-Of (POBO), enabling flexible and efficient fund management. Additionally, you can select the fee payment method to control how transaction fees are handled.

Usage Guidelines

Supports payouts to over 180 countries in 30+ currencies, including CNY payouts in Mainland China.
Sub-accounts for POBO transactions must be created in advance, and the account status must be active.
To enable POBO mode, include the x-on-behalf-of parameter in the request header and specify the sub-account ID used for the payout. The beneficiary will see the customized payer name instead of the actual paying entity.
Users can select the fee charge type by fee_paid_by parameter to determine who covers transaction costs:
1. SHARED – Transaction fees are split between payer and recipient; payer pays sending bank fees while recipient pays receiving bank fees.
2. OURS – All transaction fees, including intermediary bank charges, are paid by the payer.
There are two ways to specify the beneficiary:
1. Using beneficiary_id – If the beneficiary has already been created, provide the beneficiary_id to reference an existing beneficiary.
2. Providing full beneficiary details – If the beneficiary has not been created before, include the full beneficiary information in the request. In this case, do not pass beneficiary_id.
Note: A beneficiary will be created when full details are provided. For any future payouts to the same beneficiary, you should pass the corresponding beneficiary_id, not the full details of beneficiary.
If you intend to make cross-currency payouts, you can refer to the Cross-Currency Guide for details and examples.

POST

payouts

Create Payout

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "currency": "USD",
  "amount": "1000.00",
  "purpose_code": "AUDIO_VISUAL_SERVICES",
  "payout_reference": "026073150",
  "fee_paid_by": "SHARED",
  "payout_date": "2024-03-01",
  "quote_id": "784832f7-1f8a-4b08-ac2a-8719b5b2a590",
  "payout_currency": "SGD",
  "payout_amount": 100,
  "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "beneficiary": {
    "entity_type": "COMPANY",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "payment_method": "LOCAL",
    "bank_details": {
      "bank_name": "Bank of America",
      "bank_address": "123 Main St",
      "bank_country_code": "SG",
      "account_holder": "John Doe",
      "account_currency_code": "USD",
      "swift_code": "WELGBE22",
      "clearing_system": "GIRO",
      "account_number": "12345678",
      "iban": "GB82 WEST 1234 5698 7654 32",
      "routing_code_type1": "aba",
      "routing_code_value1": "123456789",
      "routing_code_type2": "ach",
      "routing_code_value2": "123456789"
    },
    "address": {
      "country": "SG",
      "city": "Singapore",
      "street_address": "123 Main St",
      "postal_code": "123456",
      "state": "CA",
      "nationality": "SG"
    },
    "email": "example@uqpay.com",
    "nickname": "John Doe",
    "additional_info": {
      "organization_code": "91210106MA0P46BWXY",
      "proxy_id": "<string>",
      "id_type": "PASSPORT",
      "id_number": "AB1234567",
      "tax_id": "123456789",
      "msisdn": "+65111111"
    }
  },
  "is_payer": "N",
  "payer_id": "d36384c8-5df1-4ede-b054-804578601ae7",
  "documentation": [
    {
      "file": "data:image/png;base64,TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4=",
      "file_id": "5135e6cc-28b6-4889-81dc-3b86a09e1395"
    }
  ]
}
'

{
  "payout_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "short_reference_id": "P220406-LLCVLRM"
}

Authorizations

x-auth-token

string

header

required

The API token for login provided by UQPay.

Headers

x-on-behalf-of

string

The value set to the connected account's ID. If the value is not empty, the request parameter is_payer will default to Y. More information at List Connected Accounts

x-idempotency-key

string<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.

Body

application/json

currency

string

required

The currency that the payer will send out.

Required string length: 3

Example:

"USD"

amount

string

required

The amount that the payer will send out, in currency.

Example:

"1000.00"

purpose_code

string

required

Purpose code of payout and must be one of:

AUDIO_VISUAL_SERVICES - Audiovisual services.
BILL_PAYMENT - Bill payment.
BUSINESS_EXPENSES - Business expenses.
CONSTRUCTION - Construction.
DONATION_CHARITABLE_CONTRIBUTION - Donation/charitable contribution.
EDUCATION_TRAINING - Education/training.
FAMILY_SUPPORT - Family support.
FREIGHT - Freight.
GOODS_PURCHASED - Goods purchased.
INVESTMENT_CAPITAL - Investment capital.
INVESTMENT_PROCEEDS - Investment proceeds.
LIVING_EXPENSES - Living expenses.
LOAN_CREDIT_REPAYMENT - Loan/credit repayment.
MEDICAL_SERVICES - Medical services.
PENSION - Pension.
PERSONAL_REMITTANCE - Personal remittance.
PROFESSIONAL_BUSINESS_SERVICES - Professional/business services.
REAL_ESTATE - Real estate.
TAXES - Taxes.
TECHNICAL_SERVICES - Technical services.
TRANSFER_TO_OWN_ACCOUNT - Transfer to own account.
TRAVEL - Travel.
WAGES_SALARY - Wages/salary.

Example:

"AUDIO_VISUAL_SERVICES"

payout_reference

string

required

Bank payment reference displayed in the beneficiary's bank transaction records. Sent to the recipient (e.g. For Further Credit, For Benefit of, or a custom message). aka Payment reference in Dashboard.

SWIFT payments: Must comply with the regex /^[a-zA-Z0-9/-?:().'+, ]+$/.
Allowed characters: English letters, digits, spaces, and the following special symbols: - / ? : ( ) . ' + ,.
LOCAL payments: When payment_method = LOCAL and account_currency_code is not CNH or SGD, no input format validation is applied.

Maximum string length: 100

Example:

"026073150"

fee_paid_by

enum<string>

required

The charge type of payment fee. Will only be effective and required when payment_method = SWIFT.

Available options:

SHARED,

OURS

Example:

"SHARED"

payout_date

string<date>

required

Date of when the system attempt to submit the payment to the beneficiary.

Example:

"2024-03-01"

quote_id

string

ID of the pre-created quote, obtained via Create Quote.

Required only for cross-currency payout scenarios. If provided, payout_currency and payout_amount must also be supplied.

Example:

"784832f7-1f8a-4b08-ac2a-8719b5b2a590"

payout_currency

string

The currency that the beneficiary will receive. Refer to Supported Currencies for the complete list of available currencies.

Required when quote_id is specified. Must match the buy_currency returned in the Create Quote response.

Example:

"SGD"

payout_amount

number<decimal>

The amount that the beneficiary will receive, in payout_currency.

Required when quote_id is specified. Must match the buy_amount returned in the Create Quote response.

Example:

100

beneficiary_id

string<uuid>

Universally unique identifier (UUID v4) of the beneficiary, This may be provided in place of the beneficiary section and should be empty if the beneficiary fields are provided, and vice versa.

Example:

"b3d9d2d5-4c12-4946-a09d-953e82sed2b0"

beneficiary

COMPANY · object

Details for the beneficiary in the payout request. If beneficiary_id provided in the payout request then beneficiary should be empty.

COMPANY
INDIVIDUAL

Show child attributes

is_payer

string

Important Notice: This field is scheduled to be deprecated in the next version. It is recommended to avoid using this field in new development. Whether the current user is a payer. One of Y, N

Example:

"N"

payer_id

string<uuid>

Important Notice: This field is scheduled to be deprecated in the next version. It is recommended to avoid using this field in new development. Unique identifier of the payer. If is_payer is Y, payer_id is empty, if is_payer is N, payer_id is queried from this interface Get list of payers.

Example:

"d36384c8-5df1-4ede-b054-804578601ae7"

documentation

object[]

Supporting documents related to this payout.

General: Optional field for attaching files relevant to the payout.
Mandatory case: When beneficiary.bank_details.account_currency_code = INR and clearing_system = IFSC, an invoice document must be uploaded via the documentation field.

Show child attributes

Response

200 - application/json

Payout creation successfully.

payout_id

string<uuid>

Unique identifier for the payout.

Example:

"b3d9d2d5-4c12-4946-a09d-953e82sed2b0"

short_reference_id

string

The reference generated by the system to identify the entity.

Example:

"P220406-LLCVLRM"

payout_status

enum<string>

The payout's status.

Available options:

READY_TO_SEND,

PENDING,

REJECTED,

FAILED,

COMPLETED

List payouts Retrieve payout

Documentation Index

Authorizations

Headers

Body

Response