Create a Batch Payout

Create an empty batch payout container. The batch is created in INIT status with no items — use Add Items to a Batch Payout to populate it, then call calculate for an indicative total amount, fee and FX preview (for reference only, not the final settlement amount) and submit to dispatch. Retry the same requestId to obtain the same batch idempotently.
Request Parameters
requestIdstring
required
Idempotency key. Assign a unique value (e.g., UUID) per batch to safely retry without creating duplicates. Max length: 64 characters.
batchNamestring
Human-readable name for the batch (e.g., Payroll 2026-08). Not visible to beneficiaries. Max length: 128 characters.
businessSceneCodestring
Business scene code that applies to every item in the batch. Individual items may override this value when added. See BusinessSceneCode.
fvtPreferencestring
The full value transfer preference for the batch. If specified, it applies to all items in the batch Set NEED_FVT to request guaranteed full-amount delivery (payer covers intermediary fees). See FvtPreference.
oboPreferencestring
The On-Behalf-Of routing preference for the batch. If specified, it applies to all items in the batch. See OboPreference.
paymentTypestring
The payment channel type for the batch. If specified, it applies to all items in the batch. Required if paymentNetwork is specified. See PaymentType.
paymentNetworkstring
The payment clearing network for the batch. If specified, it applies to all items in the batch. Required ifpaymentType is specified. See PaymentNetwork.
transferMemostring
Internal memo attached to the batch for your own records. Not visible to beneficiaries. Max length: 256 characters.
Response Parameters
resultResult
See Result.
idstring
Unique identifier of the created batch payout. Use this value for every subsequent addItems/calculate/submit/query call on the batch.
statusstring
Current batch status. Newly created batches always return INIT. See BatchPayoutStatus.
requestIdstring
Echoes the requestId submitted in the request.
batchNamestring
Echoes the batchName submitted in the request, when provided.
businessSceneCodestring
Echoes the businessSceneCode submitted in the request, when provided. See BusinessSceneCode.
fvtPreferencestring
Echoes the fvtPreference submitted in the request, when provided. See FvtPreference.
oboPreferencestring
Echoes the oboPreference submitted in the request, when provided. See OboPreference.
paymentNetworkstring
Echoes the paymentNetwork submitted in the request, when provided. See PaymentNetwork.
paymentTypestring
Echoes the paymentType submitted in the request, when provided. See PaymentType.
transferMemostring
Echoes the transferMemo submitted in the request, when provided.
totalItemCountinteger
Total number of items currently in the batch. Zero at creation time; increases as items are added.
validItemCountinteger
Number of items that passed validation. Zero at creation time; updated as items are added and after calculate.
createdAtdatetime
Batch creation time. ISO 8601 extended format.
updatedAtdatetime
Last update time. ISO 8601 extended format.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
PARAM_ILLEGALFIllegal parameters exist.Verify required fields, string length limits, and enum values.
AUTHORIZATION_NOT_EXISTFThe authorization does not exist.Confirm the OAuth authorization is still active for the target account.
USER_NOT_EXISTFThe user does not exist.Verify the user identified by the request, then retry with correct user information.
USER_STATUS_ABNORMALFThe status of the user is abnormal.Contact WorldFirst technical support to check the user status.
USER_NO_PERMISSIONFUser does not have permission.Confirm the user has permission to manage batch payouts, or retry with a user that has the required permissions.
CONTRACT_NOT_EXISTFThe contract does not exist.Ensure the required payout contract is in place, then retry.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.Reuse the original payload for the same `requestId`, or assign a new `requestId`.
PROCESS_FAILFA general business failure occurred. Do not retry.Do not retry. Contact WorldFirst technical support with your `requestId`.
Definition
POST /api/open/v1/batchPayouts/create
Request
{
"requestId": "req_batch_20260808_0001",
"batchName": "Payroll 2026-08",
"transferMemo": "August payroll run"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "bp_20260808****",
"status": "INIT",
"requestId": "req_batch_20260808_0001",
"batchName": "Payroll 2026-08",
"transferMemo": "August payroll run",
"totalItemCount": 0,
"validItemCount": 0,
"createdAt": "2026-08-08T10:00:00+08:00",
"updatedAt": "2026-08-08T10:00:00+08:00"
}