Skip to main content
POST
Create internal payout

Authorizations

x-auth-token
string
header
required

The API token for login provided by UQPAY.

Headers

x-on-behalf-of
string<uuid>

Specifies the authorized direct sub-account on whose behalf the request is made. Set this to its account_id (a lowercase UUID), available from List Connected Accounts. If omitted, the request uses the token account. For more information, see Connected Accounts.

x-idempotency-key
string<uuid>
required

A unique identifier (lowercase UUID) used to ensure request idempotency. Use the same identifier when retrying an operation to avoid duplicate payouts.

Body

application/json
account_id
string
required

Recipient account UUID or short account ID. The recipient must be active, have a short account ID, and differ from the payer. Email addresses are not supported.

Maximum string length: 36
currency
string
required

Currency of the payout, specified as a three-letter ISO 4217 currency code. Both accounts must support the same fiat currency.

Required string length: 3
amount
string
required

Payout amount, excluding fees. Must be greater than zero. IDR, JPY, and KRW require a whole-number amount.

Pattern: ^[0-9]+(\.[0-9]{1,2})?$
purpose_code
string
required

Purpose of the payout, case-insensitive. Do not add surrounding whitespace. Choose a supported code that matches the business purpose:

Maximum string length: 200
nickname
string

Recipient nickname.

Maximum string length: 120
payout_reason
string

Additional explanation of the payout purpose.

Maximum string length: 200
payout_reference
string

Your business reference for the payout.

Maximum string length: 100
with_transfer
enum<string>

Whether to transfer funds from the master account to the paying sub-account before making the payout.

With a master-account token, the master pays by default. Include x-on-behalf-of to pay from the specified sub-account. account_id always identifies the final recipient.

  • N or omitted: pay directly from the payer's balance. Funds move from payer → recipient. The payer must have enough available balance for amount plus the payout fee. Insufficient funds cause the request to fail; no funds are automatically transferred from the master.
  • Y, when a sub-account pays: fund the sub-account first, then make the payout. Funds move from master → paying sub-account → recipient. The master first transfers amount plus the payout fee to the sub-account, which then makes the payout. This full amount is transferred even if the sub-account already has sufficient funds.

When using Y for a sub-account payout, total master-account debit = amount + payout fee + master-to-sub-account transfer fee. If the master has insufficient available balance, the request fails; it does not use the sub-account's existing balance instead.

If the payer is the master account, Y behaves the same as N: the payout uses that master's balance directly.

For sub-account funding, the payer must be a direct sub-account of the funding master, with this capability enabled. Its balance account for the payout currency must be valid, with a non-negative available balance. Contact UQPAY to enable this capability.

Available options:
Y,
N
documentation
object[]

Supporting documents. Use file_id or file to provide a document.

Response

Payout accepted. Query the payout to confirm completion.

payout_id
string<uuid>

Unique identifier of the payout.

short_reference_id
string

Short reference of the payout.

payout_status
enum<string>
  • READY_TO_SEND: Accepted and awaiting processing.
  • PENDING: Processing.
  • COMPLETED: Completed.
  • FAILED: Failed or cancelled.
  • REJECTED: Rejected during review.
Available options:
READY_TO_SEND,
PENDING,
COMPLETED,
FAILED,
REJECTED