v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB

Payouts

Retrieve Payout

Get a specific payout by specifying the payout_id.

get/v1/payouts/{id}

Path parameters

idstring uuid required

Example:b3d9d2d5-4c12-4946-a09d-953e82sed2b0

Universally unique identifier (UUID v4) of a resource.

Headers

x-on-behalf-ofstring

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

Response

OK - Successfully retrieved a payout.

payout_idstring uuid required

Unique identifier for the payout.

amount_payer_paysstring required

The amount actually paid by the payer for the payout.

payout_currencystring required

Three-letter currency code

payout_amountstring required

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.

source_currencystring required

The currency that the payer will send out.

source_amountstring required

The amount paid by the payer for the payout.

amount_beneficiary_receivesstring required

The amount received by the beneficiary.

fee_paid_by'SHARED' | 'OURS' | '' required

The charge type of payment fee. Only effective when payment_method = SWIFT.

SHARED: Transaction fees are split between payer and recipient; payer pays sending bank fees while recipient pays receiving bank fees.
OURS: All transaction fees, including intermediary bank charges, are paid by the payer.

An empty string may be returned for records where the fee allocation mode is unavailable or not applicable.

fee_currencystring required

Currency used to pay fees. Three-letter ISO 4217 currency code.

fee_amountstring required

The fee amount.

payout_datestring date required

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

short_reference_idstring required

The reference generated by the system to identify the payout.

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.

payout_reasonstring required

The custom reason for the payout which displayed in the beneficiary's bank transaction records.

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

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.

create_timestring date/time required

The timestamp when the record was created in the system. Timestamp follows the ISO 8601 standard.

update_timestring date/time required

complete_timestring date/time nullable required

The timestamp when the request was successfully processed and marked as COMPLETED. Returns null while the request is still in progress.

failure_returned_amountstring

The amount of the failed payout to be returned.

failure_reasonstring

The reason why the payout failed.

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.

Example response

{
  "payout_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
  "amount_payer_pays": "1000.00",
  "purpose_code": "AUDIO_VISUAL_SERVICES",
  "source_currency": "USD",
  "source_amount": "1000.00",
  "amount_beneficiary_receives": "1000.00",
  "fee_paid_by": "SHARED",
  "fee_currency": "USD",
  "payout_date": "2024-03-01",
  "short_reference_id": "P220406-LLCVLRM",
  "payout_reference": "026073150",
  "payout_reason": "Audiovisual services",
  "create_time": "2024-03-01T00:00:00+08:00",
  "update_time": "2024-03-01T00:00:00+08:00",
  "complete_time": "2024-03-01T00:00:00+08:00",
  "payout_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"
        }
      }
    }
  },
  "payer": {
    "payer_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
    "country": "SG",
    "company_name": "UQPAY",
    "first_name": "John",
    "last_name": "Doe",
    "city": "Singapore",
    "address": "123 Main St",
    "state": "CA",
    "postal_code": "123456",
    "date_birth": "2001-01-28",
    "identification_type": "PASSPORT",
    "identification_value": "12345678"
  },
  "beneficiary": {
    "beneficiary_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
    "short_reference_id": "P220406-LLCVLRM",
    "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"
          }
        }
      }
    },
    "email": "example@uqpay.com",
    "nickname": "John Doe",
    "beneficiary_status": "ACTIVE",
    "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
    "summary": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "id_number": "110101199001011234",
    "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"
    },
    "create_time": "2024-03-01T00:00:00+08:00",
    "update_time": "2024-03-01T00:00:00+08:00",
    "additional_info": {
      "organization_code": "91210106MA0P46BWXY",
      "id_type": "PASSPORT",
      "id_number": "AB1234567",
      "tax_id": "123456789",
      "msisdn": "+65111111"
    }
  },
  "failure_returned_amount": "1000.00",
  "quote_id": "784832f7-1f8a-4b08-ac2a-8719b5b2a590",
  "conversion": {
    "currency_pair": "USDEUR",
    "client_rate": "1.355957"
  }
}