Query a Payout

Retrieve the current status and full details of a payout by its ID. Use this endpoint to poll for payout completion or to inspect the final outcome of a submitted payout.
Request Parameters
idstring
WorldFirst-assigned payout ID. Obtained from the id field in the Create a Payout response.
Response Parameters
resultResult
See Result.
idstring
WorldFirst-assigned unique payout ID. Use this ID for subsequent query calls.
statusstring
Current payout status. See PayoutStatus.
failureCodestring
Failure reason code. Returned when status is FAILED. Inspect this field to determine the cause and whether to retry.
failureMessagestring
A plain-text description of the failure reason. Returned when status is FAILED.
businessSceneCodestring
Business scene code for this payout. See BusinessSceneCode.
purposeCodestring
Payment purpose code applied. See PurposeCode.
sourceAmountAmount
Source currency amount debited from the payer's account. See Data Types.
payoutAmountAmount
Target currency amount received (or to be received) by the beneficiary. See Data Types.
transferQuoteQuote
Exchange rate applied to this payout. Returned for cross-currency payouts.
Show child parametersShow child parameters
payerPayer
Payer information recorded for this payout.
Show child parametersShow child parameters
beneficiaryBeneficiary
Beneficiary information recorded for this payout.
Show child parametersShow child parameters
feeAmountAmount
Total service fee charged for this payout. See Data Types.
feeItemListarray
Itemized fee breakdown. Returned when multiple fee components apply.
Show child parametersShow child parameters
originalFeeRatestring
Original fee rate before any promotional discounts.
feeRatestring
Actual fee rate after promotional discounts are applied.
originalFeeAmountAmount
Original service fee before promotional discounts. See Data Types.
discountFeeAmountAmount
Promotional fee reduction amount. See Data Types.
returnedAmountAmount
Amount returned to the payer. Returned when status is RETURNED. See Data Types.
returnedAtdatetime
Timestamp when the funds were returned to the payer. Returned when status is RETURNED. ISO 8601 extended format. See Data Types.
promotionListarray
Active promotions applied to this payout.
Show child parametersShow child parameters
fvtPreferencestring
Full Value Transfer preference of the payout.

Valid Values:

NEED_FVT — Request Full Value Transfer.
oboPreferencestring
On-Behalf-Of routing preference of the payout.

Valid Values:

NEED_OBO — Route the payout on behalf of the specified payer.
NO_OBO — Do not use On-Behalf-Of routing.
paymentTypestring
Payment channel type used for this payout.

Valid Values:

LOCAL — Local clearing.
CROSS — Cross-border wire transfer via SWIFT.
paymentNetworkstring
Specific clearing network used. See PaymentNetwork.
referencestring
Bank transfer reference text.
transferMemostring
Internal transfer memo.
additionalInfoPayoutAdditionalInfo
Supplementary business fields for this payout.
Show child parametersShow child parameters
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
PARAM_ILLEGALFIllegal parameters.Verify the `id` field format.
CONTRACT_CHECK_FAILFThe contract check has failed.Check the contract status, then retry.
FEATURE_NOT_AVAILABLEFFunction not available.This feature is not available. Contact WorldFirst technical support.
PARTNER_INFO_NOT_EXISTFPartner information does not exist.Verify the merchant account configuration.
PARTNER_STATUS_INVALIDFPartner status is invalid.Merchant account is in an invalid status. Contact WorldFirst technical support.
FUND_ORDER_NOT_EXISTFFund order does not exist.The payout `id` does not exist or does not belong to your account. Verify the `id` value.
Definition
POST /api/open/v1/payouts/query
Request
{
"id": "20260401xxxxx"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "20260401xxxxx",
"status": "SUCCESS",
"businessSceneCode": "THIRD_PARTY_PAYOUT",
"purposeCode": "GDS",
"sourceAmount": {
  "currency": "HKD",
  "value": 78900
},
"payoutAmount": {
  "currency": "USD",
  "value": 10000
},
"feeAmount": {
  "currency": "USD",
  "value": 100
},
"transferQuote": {
  "quoteId": "12345678910xxx",
  "currencyPair": "HKD/USD",
  "clientRate": 7.892342342,
  "effectiveAt": "2025-04-19T13:08:56Z",
  "expiresAt": "2026-04-19T13:08:56Z"
},
"payer": {
  "region": "HK",
  "phone": "176xxxxxxxx",
  "email": "123@gmail.com",
  "name": {
    "firstName": "Lebron",
    "lastName": "James",
    "fullName": "Lebron James"
  },
  "address": {
    "address1": "xxxxxx",
    "address2": "xxxxx2",
    "zipCode": "4001001"
  }
},
"beneficiary": {
  "region": "HK",
  "phone": "176xxxxxxxx",
  "email": "123@gmail.com",
  "beneficiaryId": "xxxxxxxxxx"
},
"fvtPreference": "NEED_FVT",
"oboPreference": "NEED_OBO",
"paymentType": "LOCAL",
"paymentNetwork": "ACH",
"reference": "pay to xxx",
"transferMemo": "rest memo"
}