Create a Payout
Send funds to a beneficiary's bank account or e-wallet. Use this endpoint to pay suppliers, employees, contractors, or your own accounts across supported regions and currencies.
Request Parameters
When payout = PAY_INTO_BANK_ACCOUNT
requestIdstring
required
Idempotency key. Assign a unique value (e.g., UUID) per payout to safely retry without creating duplicates.
businessSceneCodestring
Business scene code that identifies the payout type. See BusinessSceneCode.
purposeCodestring
required
Payment purpose code. See PurposeCode.
Valid Values:
GDS — Payment for goods.
GST — General service trade.
ACM — Payment for goods.
COM — Commission payment.
TOA — Transfer to own account, same-name withdrawal.
SAL — Salary/payroll.
TXS — Government-imposed charges including income tax, customs duties, and transfer payments.
sourceAmountAmount conditional
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. Provide bank details.
payerPayer conditional
Payer (sender) information. Defaults to the onboarded account details. Required when the On-Behalf-Of payment preference is specified.
transferQuoteQuote
Exchange rate quote for this payout. Omit for same-currency payouts. For cross-currency payouts, omit to use the live market rate, or pass quoteId from Consult a Payout to lock in a specific rate.
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 rather than WorldFirst. Only applicable to OBO-supported channels.
NO_OBO — Do not apply any On-Behalf-Of routing; the payout is routed under WorldFirst by default.
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.
idstring
Unique payout ID assigned by the system. Use this ID to subsequent status updates.
statusstring
Current payout status. Payouts are processed asynchronously; the initial status is typically PROCESSING. See PayoutStatus.
createdAtdatetime
Timestamp when the task was created. ISO 8601 extended format (e.g., 2026-04-27T12:08:56+08:00).
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.
payerPayer
Payer information as recorded for this payout.
beneficiaryBeneficiary
Beneficiary information as recorded for this payout.
sourceAmountAmount
Source currency amount debited from the payer's account. See Data Types.
payoutAmountAmount
Target currency amount received by the beneficiary. See Data Types.
businessSceneCodestring
Business scene code applied to this payout. See BusinessSceneCode.
purposeCodestring
Payment purpose code applied. See PurposeCode.
transferQuoteQuote
Exchange rate applied to this payout. Returned for cross-currency payouts.
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.
additionalInfoPayoutAdditionalInfo
Supplementary business fields echoed from the request.
Error Codes
Definition
POST /api/open/v1/payouts/createRequest
{
"requestId": "CTS123456",
"businessSceneCode": "THIRD_PARTY_PAYOUT",
"purposeCode": "GDS",
"payer": {
"region": "HK",
"phone": "176xxxxxxxx",
"email": "123@gmail.com",
"name": {
"firstName": "First",
"lastName": "World",
"fullName": "First World"
},
"address": {
"address1": "xxxxxx",
"address2": "xxxxx2",
"zipCode": "4001001"
}
},
"beneficiary": {
"accountType": "BANK_ACCOUNT",
"entityType": "COMPANY",
"region": "HK",
"phone": "176xxxxxxxx",
"email": "123@gmail.com",
"address": "xxxxxx",
"bankDetails": {
"bankBIC": "HSBCHKHHHKH",
"accountNumber": "23******3452",
"accountHolderName": {
"fullName": "TestName"
}
},
"relationType": "THIRD_PARTY",
"classificationCode": "0001"
},
"sourceAmount": {
"currency": "HKD"
},
"payoutAmount": {
"currency": "USD",
"value": 10000
},
"transferQuote": {
"quoteId": "12345678910xxx"
},
"fvtPreference": "NEED_FVT",
"oboPreference": "NEED_OBO",
"reference": "pay to xxx",
"transferMemo": "test memo"
}Response
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultStatus": "S"
},
"id": "20260401xxxxx",
"createdAt": "2026-08-08T23:12:13Z",
"businessSceneCode": "THIRD_PARTY_PAYOUT",
"purposeCode": "GDS",
"payer": {
"region": "HK",
"phone": "176xxxxxxxx",
"email": "123@gmail.com",
"name": {
"firstName": "First",
"lastName": "World",
"fullName": "First World"
},
"address": {
"address1": "xxxxxx",
"address2": "xxxxx2",
"zipCode": "4001001"
}
},
"beneficiary": {
"accountType": "BANK_ACCOUNT",
"entityType": "COMPANY",
"region": "HK",
"phone": "176xxxxxxxx",
"email": "123@gmail.com",
"address": "xxxxxx",
"bankDetails": {
"bankBIC": "HSBCHKHHHKH",
"accountNumber": "23******3452",
"accountHolderName": {
"fullName": "TestName"
}
},
"relationType": "THIRD_PARTY",
"classificationCode": "0001"
},
"sourceAmount": {
"currency": "HKD"
},
"payoutAmount": {
"currency": "USD",
"value": 10000
},
"feeAmount": {
"currency": "USD",
"value": 100
},
"transferQuote": {
"quoteId": "12345678910xxx",
"currencyPair": "HKD/USD",
"clientRate": 7.892342342,
"effectiveAt": "2026-04-19T13:08:26Z",
"expiresAt": "2026-04-19T13:08:56Z"
},
"fvtPreference": "NEED_FVT",
"oboPreference": "NEED_OBO",
"paymentType": "LOCAL",
"paymentNetwork": "ACH",
"reference": "pay to xxx",
"transferMemo": "test memo"
}