Skip to main content
POST
/
v1
/
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",
  "payout_status": "READY_TO_SEND"
}

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.

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

Response

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