> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Cross-Currency Payout Guide > Send funds from your UQPAY account in one currency to a beneficiary who receives payment in a different currency. ## 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](/global-account/v1.6/guide/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](/global-account/v1.6/api-reference/create-beneficiary) **Request:** ```json theme={null} { "email": "crosscurrencyTHB@uqpay.com", "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:** ```json theme={null} { "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. If you pass `conversion_date`, call [List Conversion Dates](/global-account/v1.6/api-reference/list-conversion-dates) first to confirm that today's date is available for the currency pair. The current API does not support scheduling a future conversion date. Available dates already exclude weekends and relevant public holidays for the currency pair. **API Reference:** [Create Quote](/global-account/v1.6/api-reference/create-quote) **Request:** ```json theme={null} { "sell_currency": "USD", "sell_amount": "100", "buy_currency": "THB", "conversion_date": "2025-09-17", "transaction_type": "payout" } ``` **Response:** ```json theme={null} { "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](/global-account/v1.6/api-reference/create-payout) **Request:** ```json theme={null} { "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:** ```json theme={null} { "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](/global-account/v1.6/webhooks/payout-status) ### Payout Ready to Send When the payout is accepted by UQPAY, you'll receive this webhook: ```json theme={null} { "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: ```json theme={null} { "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` | ## Related Documentation * [Create Beneficiary API](/global-account/v1.6/api-reference/create-beneficiary) * [Create Quote API](/global-account/v1.6/api-reference/create-quote) * [Create Payout API](/global-account/v1.6/api-reference/create-payout) * [Payout Status Webhook](/global-account/v1.6/webhooks/payout-status) * [Cross-Currency Payout Supported Currency Pairs](/global-account/v1.6/guide/cross-currency-payout-supported-currency-pairs)