Consult a Payout
Pre-validate a payout and retrieve a fee and exchange rate estimate before initiating the actual transfer. No funds are moved. Use this endpoint to verify routing feasibility, preview costs, and obtain a quote ID to lock in the exchange rate for a subsequent Create a Payout call.
Request Parameters
businessSceneCodestring
Business scene code that identifies the payout type. See BusinessSceneCode.
purposeCodestring
required
Payment purpose code. See PurposeCode.
sourceAmountAmount
Source currency amount debited from the payer's account. currency is required on both sourceAmount and payoutAmount, but only one value may be specified. See Data Types.
payoutAmountAmount
Target currency amount received by the beneficiary. currency is required on both sourceAmount and payoutAmount, but only one value may be specified. See Data Types.
beneficiaryBeneficiary
required
Beneficiary (recipient) information.
payerPayer
Payer (sender) information. Defaults to the onboarded account details.
fvtPreferencestring
Full Value Transfer preference. Specify to request guaranteed full-amount delivery to the beneficiary (payer covers all intermediary fees).
Valid Values:
NEED_FVT — Request full value transfer.
oboPreferencestring
On-Behalf-Of routing preference. When set to NEED_OBO, WorldFirst forwards the specified payer details to the receiving bank. Note that WorldFirst cannot control how payer information appears on bank statements and is not liable for any discrepancies.
Valid Values:
NEED_OBO — Route the payout on behalf of the specified payer. Only applicable to OBO-supported channels.
NO_OBO — No On-Behalf-Of routing preference.
paymentTypestring
Payment channel type. Use together with paymentNetwork.
Valid Values:
LOCAL — Local clearing (e.g., ACH, SEPA, Faster Payments).
CROSS — Cross-border wire transfer via SWIFT.
paymentNetworkstring
Specific clearing network. Use together with paymentType. See PaymentNetwork.
referencestring
Bank transfer reference text. May appear on the beneficiary's bank statement, depending on the local clearing system and receiving bank.
transferMemostring
Internal transfer memo for your own records. Not visible to the beneficiary.
Response Parameters
resultResult
See Result.
businessSceneCodestring
Business scene code applied to 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 by the beneficiary. See Data Types.
transferQuoteQuote
Exchange rate quote for cross-currency payouts. Returned when currency conversion is required. Pass quoteId to Create a Payout to lock in this rate.
payerPayer
Payer information.
beneficiaryBeneficiary
Beneficiary information.
feeAmountAmount
Total service fee for this payout. See Data Types.
feeItemListarray
Itemized fee breakdown. Returned when multiple fee components apply.
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. Returned when a promotion is applied. See Data Types.
availableQuotaAmount
Remaining FX settlement quota. Returned when the payout involves currency settlement. See Data Types.
promotionListarray
Active promotions applied to this payout.
fvtPreferencestring
Full Value Transfer preference applied.
oboPreferencestring
On-Behalf-Of routing preference applied.
paymentTypestring
Payment channel type resolved for this payout.
Valid Values:
LOCAL — Local clearing.
CROSS — Cross-border wire transfer via SWIFT.
paymentNetworkstring
Specific clearing network resolved for this payout. See PaymentNetwork.
referencestring
Bank transfer reference text.
transferMemostring
Internal transfer memo.
Error Codes
Definition
POST /api/open/v1/payouts/consultRequest
{
"businessSceneCode": "THIRD_PARTY_PAYOUT",
"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",
"entityType": "COMPANY",
"accountType": "BANK_ACCOUNT"
},
"sourceAmount": {
"currency": "HKD"
},
"payoutAmount": {
"currency": "USD",
"value": 10000
},
"purposeCode": "GDS",
"fvtPreference": "NEED_FVT",
"oboPreference": "NEED_OBO",
"reference": "pay to xxx",
"transferMemo": "test memo"
}Response
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultStatus": "S"
},
"businessSceneCode": "THIRD_PARTY_PAYOUT",
"transferQuote": {
"quoteId": "12345678910xxx",
"currencyPair": "HKD/USD",
"clientRate": 7.892342342,
"effectiveAt": "2026-04-19T13:08:56Z",
"expiresAt": "2026-04-19T13:09:26Z"
},
"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"
},
"sourceAmount": {
"currency": "HKD",
"value": 78900
},
"payoutAmount": {
"currency": "USD",
"value": 10000
},
"feeAmount": {
"currency": "USD",
"value": 100
},
"purposeCode": "GDS",
"fvtPreference": "NEED_FVT",
"oboPreference": "NEED_OBO",
"paymentType": "LOCAL",
"paymentNetwork": "ACH",
"reference": "pay to xxx",
"transferMemo": "test memo"
}