Cross-Currency Payout Guide

Overview

Cross-currency payout enables you to send funds from your UQPAY account in one currency to a beneficiary who receives the funds in a different currency. This eliminates the need for a separate currency conversion step, streamlining your international payment process.

For a complete list of supported currency pairs, refer to Cross-Currency Payout Supported Currency Pairs.

Key Benefits

Simplified Process: No need to create a separate conversion before payout
Real-time Exchange Rates: Lock in competitive rates with instant quotes

Step-by-Step Implementation

This guide shows an example of sending 100 USD, with the beneficiary receiving the equivalent value in THB.

Step 1: Create Beneficiary (Optional)

If you haven't already created a beneficiary for the target currency(THB), create one first.

API Reference: Create Beneficiary

Request:

{
  "email": "[email protected]",
  "nickname": "THB beneficiary",
  "entity_type": "COMPANY",
  "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
  "payment_method": "LOCAL",
  "bank_details": {
    "bank_name": "The Currency Cloud Limited",
    "bank_address": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
    "bank_country_code": "TH",
    "account_holder": "UQPAY PTE. LTD.",
    "account_currency_code": "THB",
    "clearing_system": "LOCAL",
    "swift_code": "BKKBTHBKXXX",
    "account_number": "123456789012",
    "iban": "123456789012"  
  },
  "address": {
    "country": "TH",
    "city": "th",
    "street_address": "123 Main St",
    "postal_code": "123456",
    "state": "thqwe",
    "nationality": "TH"
  },
  "additional_info": {}
}

Response:

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

Step 2: Create Quote

Create a quote to lock in the current exchange rate. The quote must be used within its validity period.

API Reference: Create Quote

Request:

{
  "sell_currency": "USD",
  "sell_amount": "100",
  "buy_currency": "THB",
  "conversion_date": "2025-09-17",
  "transaction_type": "payout"
}

Response:

{
  "buy_amount": "3160.3",
  "buy_currency": "THB",
  "quote_price": {
    "currency_pair": "USDTHB",
    "direct_rate": "31.60308",
    "inverse_rate": "0.031642",
    "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
    "validity": {
      "valid_from": 1758102115087,
      "valid_to": 1758102415093
    }
  },
  "sell_amount": "100",
  "sell_currency": "USD"
}

Key Parameters:

sell_currency: The currency in your account (USD)
sell_amount: The amount you want to send (100)
buy_currency: The currency the beneficiary will receive (THB)
transaction_type: Must be set to "payout" for cross-currency payouts

Note: You can also specify a fixed buy_amount instead of sell_amount if you want the recipient to receive a specific amount (e.g., 1000 THB), and the system will calculate the required sell_amount based on the current exchange rate.

Extract these values from the response:

buy_amount: "3160.3"
buy_currency: "THB"
sell_amount: "100"
sell_currency: "USD"
quote_id: "a202824c-2f93-4561-b298-b5bba76d8a10"

Step 3: Create Payout

Within the quote validity period, create the payout using the quote details.

API Reference: Create Payout

Request:

{
  "currency": "USD",
  "amount": "100",
  "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
  "payout_currency": "THB",
  "payout_amount": "3160.3",
  "purpose_code": "AUDIO_VISUAL_SERVICES",
  "payout_reference": "cross currency INR test",
  "fee_paid_by": "OURS",
  "payout_date": "2025-09-17",
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba"
}

Response:

{
  "payout_id": "3357f314-14bd-477a-bdf8-12245e863f98",
  "short_reference_id": "P250917-VKVAKHWQ",
  "payout_status": "READY_TO_SEND"
}

Parameter Mapping:

Payout Parameter	Quote Response	Description
`currency`	`sell_currency`	Source currency from your account
`amount`	`sell_amount`	Amount to be sent
`payout_currency`	`buy_currency`	Currency beneficiary receives
`payout_amount`	`buy_amount`	Amount beneficiary receives
`quote_id`	`quote_id`	Quote identifier for rate locking

Webhook Notifications

API Reference: Payout Status Webhook

Payout Ready to Send

When the payout is accepted by UQPAY, you'll receive this webhook:

{
  "version": "V1.6.0",
  "event_name": "PAYOUT",
  "event_type": "payout.ready.send",
  "event_id": "ecefbe35-e1a6-42da-a780-8687e0842dd4",
  "source_id": "3357f314-14bd-477a-bdf8-12245e863f98",
  "data": {
    "account_id": "44fb810d-6bca-411c-964a-3013de34b798",
    "amount": "100",
    "authorisation_steps_required": "0",
    "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
    "conversion": {
      "client_rate": "31.60308",
      "currency_pair": "USDTHB"
    },
    "currency": "USD",
    "direct_id": "0",
    "failure_reason": "",
    "failure_returned_amount": "",
    "fee_amount": "0.4",
    "fee_currency": "USD",
    "fee_paid_by": "OURS",
    "payment_date": "2025-09-17",
    "payment_type": "LOCAL",
    "payout_amount": "3160.3",
    "payout_currency": "THB",
    "payout_id": "3357f314-14bd-477a-bdf8-12245e863f98",
    "payout_way": "API",
    "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
    "reason": "audiovisual services",
    "reference": "cross currency INR test",
    "short_reference": "P250917-VKVAKHWQ",
    "short_reference_id": "P250917-VKVAKHWQ",
    "status": "READY_TO_SEND",
    "unique_request_id": ""
  }
}

Payout Completed

When the payout is successfully processed:

{
  "version": "V1.6.0",
  "event_name": "PAYOUT",
  "event_type": "payout.completed",
  "event_id": "58b82ca4-7196-47b8-9ddb-5d7c26a1920f",
  "source_id": "3357f314-14bd-477a-bdf8-12245e863f98",
  "data": {
    "account_id": "44fb810d-6bca-411c-964a-3013de34b798",
    "amount": "100",
    "authorisation_steps_required": "0",
    "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
    "conversion": {
      "client_rate": "31.60308",
      "currency_pair": "USDTHB"
    },
    "currency": "USD",
    "direct_id": "0",
    "failure_reason": "",
    "failure_returned_amount": "",
    "fee_amount": "0.4",
    "fee_currency": "USD",
    "fee_paid_by": "OURS",
    "payment_date": "2025-09-17",
    "payment_type": "LOCAL",
    "payout_amount": "3160.3",
    "payout_currency": "THB",
    "payout_id": "3357f314-14bd-477a-bdf8-12245e863f98",
    "payout_way": "API",
    "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
    "reason": "audiovisual services",
    "reference": "cross currency INR test",
    "short_reference": "P250917-VKVAKHWQ",
    "short_reference_id": "P250917-VKVAKHWQ",
    "status": "COMPLETED",
    "unique_request_id": ""
  }
}

Additional Considerations

Different payout currencies may have specific parameter requirements:

INR Payouts

Upload invoice files in the documentation field of the payout request

COP Payouts

Include additional information in the beneficiary's additional_info:

Field	Type	Required For	Description	Example
`id_type`	string	Individual beneficiaries	ID type	`PASSPORT`, `NATIONAL_ID`, `DRIVERS_LICENSE`
`id_number`	string	Individual beneficiaries	ID number	`A1234567`
`tax_id`	string	Company beneficiaries	Tax ID	`123456`
`msisdn`	string	All beneficiaries	Mobile number in format `+[country code][phone number]`	`+65111111`

Overview

Key Benefits

Step-by-Step Implementation

Step 1: Create Beneficiary (Optional)

Step 2: Create Quote

Step 3: Create Payout

Webhook Notifications

Payout Ready to Send

Payout Completed

Additional Considerations

INR Payouts

COP Payouts

Related Documentation