Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
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/v1/payouts

Headers

x-on-behalf-ofstring

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-keystring uuid

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.

Request body

currencystring required

The currency that the payer will send out.

amountstring required
quote_idstring

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.

payout_currencystring

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.

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

purpose_codestring 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.
payout_referencestring 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.
fee_paid_by'SHARED' | 'OURS' required

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

  • SHARED: Transaction fees are split between payer and recipient; payer pays sending bank fees while recipient pays receiving bank fees. Available for SWIFT payouts when the payer is a company and the payer's country is one of the following: SG, VN, HK, or AU.
  • OURS: All transaction fees, including intermediary bank charges, are paid by the payer.
payout_datestring date required

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

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

is_payerstring

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

payer_idstring 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 request

{
  "currency": "USD",
  "quote_id": "784832f7-1f8a-4b08-ac2a-8719b5b2a590",
  "payout_currency": "SGD",
  "payout_amount": "100.00",
  "purpose_code": "AUDIO_VISUAL_SERVICES",
  "payout_reference": "026073150",
  "fee_paid_by": "SHARED",
  "payout_date": "2024-03-01",
  "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "beneficiary": {
    "entity_type": "COMPANY",
    "email": "example@uqpay.com",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "payment_method": {
      "card": {
        "billing": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone_number": "12025550123",
          "address": {
            "country_code": "SG",
            "city": "Singapore",
            "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
            "postcode": "924011"
          }
        }
      }
    },
    "nickname": "John Doe",
    "bank_details": {
      "bank_name": "Bank of America",
      "bank_address": "123 Main St",
      "bank_country_code": "SG",
      "account_holder": "John Doe",
      "account_number": "12345678",
      "iban": "GB82 WEST 1234 5698 7654 32",
      "swift_code": "WELGBE22",
      "clearing_system": "GIRO",
      "routing_code_type1": "aba",
      "routing_code_value1": "123456789",
      "routing_code_type2": "ach",
      "routing_code_value2": "123456789"
    },
    "address": {
      "country": "SG",
      "nationality": "SG",
      "city": "Singapore",
      "street_address": "123 Main St",
      "postal_code": "123456",
      "state": "CA"
    },
    "additional_info": {
      "organization_code": "91210106MA0P46BWXY",
      "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"
    }
  ]
}

Response

Payout creation successfully.

payout_idstring uuid

Unique identifier for the payout.

short_reference_idstring

The reference generated by the system to identify the entity.

payout_status'READY_TO_SEND' | 'PENDING' | 'REJECTED' | 'FAILED' | 'COMPLETED'

The payout's status.

  • READY_TO_SEND: The payout has been validated and is ready for processing.
  • PENDING: The payout is currently being processed by the system.
  • REJECTED: The payout was rejected due to validation or compliance requirements not being met.
  • FAILED: The payout process encountered an error and could not be completed.
  • COMPLETED: The payout has been successfully processed and funds have been transferred.

Example response

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