Add Items to a Batch Payout

Append up to 10 payout items to an existing batch per call until the batch reaches its 100-item limit. The batch must be in INIT status; invalid items are returned with validation details without blocking other items in the request. Each item follows the same structure as a Create a Payout request for its payout scenario. fvtPreference, oboPreference, paymentType, and paymentNetwork are defined in Create a Batch Payout and applied to every item in the batch.
Request Parameters
idstring
required
Unique identifier of the target batch, returned by Create a Batch Payout.
itemsarray
required
Payout items to append to the batch. Provide 1 to 10 items per request. Build each item from the request of the matching payout scenario in Create a Payout. Items in the same batch can use different payout scenarios. Note: fvtPreference, oboPreference, paymentType, and paymentNetwork are defined in Create a Batch Payout and applied to every item in the batch. transferQuote is not applicable; call Calculate a Batch Payout to preview amounts, fees, and FX rates later.
Show child parametersShow child parameters
Response Parameters
resultResult
API call result. See Result.
idstring
Unique identifier of the batch payout.
statusstring
Current batch lifecycle status after the operation. See BatchPayoutStatus.
createdAtdatetime
Time the batch was created, in ISO 8601 extended format.
updatedAtdatetime
Time the batch was most recently updated, in ISO 8601 extended format.
requestIdstring
Idempotency key supplied when the batch was created.
batchNamestring
Human-readable batch name, if provided at creation.
transferMemostring
Internal memo attached to the batch, if provided at creation.
businessSceneCodestring
Business scene code set on the batch, if provided at creation. See BusinessSceneCode.
paymentNetworkstring
Payment clearing network set on the batch, if provided at creation. See PaymentNetwork.
paymentTypestring
Payment channel type set on the batch, if provided at creation. See PaymentType.
fvtPreferencestring
Full value transfer (FVT) preference set on the batch, if provided at creation. See FvtPreference.
oboPreferencestring
On-behalf-of (OBO) routing preference set on the batch, if provided at creation. See OboPreference.
totalItemCountinteger
Total number of payout items currently in the batch, from 0 to 100.
validItemCountinteger
Number of payout items in the batch that have passed validation, from 0 to 100.
calculationSummaryCalculationSummary
Latest reference pricing summary. Returned once calculate (or submit) has completed pricing. All totals and rates are indicative — final values are determined at payout processing.
Show child parametersShow child parameters
itemsarray
Results for the items submitted in this request.
Show child parametersShow child parameters
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
PARAM_ILLEGALFIllegal parameters existVerify that `items` contains 1–10 entries and that each field meets its documented constraints.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistentReuse the original payload for the same item `requestId`, or assign a new `requestId`.
CONTRACT_CHECK_FAILFThe contract check has failedCheck the contract status, then retry.
CONTRACT_NOT_EXISTFThe contract does not existEnsure the required payout contract is in place, then retry.
UN_SUPPORT_BUSINESSFUnsupported businessVerify each item's `businessSceneCode` value and ensure the currency combination is supported.
USER_NOT_EXISTFThe user does not existVerify the user identified by the request, then retry with correct user information.
ACCOUNT_NOT_EXISTFThe account does not existVerify the payer account exists, then retry.
ACCOUNT_STATUS_ABNORMALFThe account status is abnormalRetry with an account in a valid status, or contact WorldFirst technical support.
USER_ACCOUNT_ABNORMALFThe user account status is abnormalThe payer account is in an abnormal state. Retry with a valid account.
USER_NO_PERMISSIONFUser does not have permissionConfirm the user has permission to manage batch payouts, or retry with a user that has the required permissions.
AUTHORIZATION_NOT_EXISTFThe authorization does not existConfirm the OAuth authorization is still active for the target account.
CURRENCY_NOT_SUPPORTEDFThe specified currency is not supportedConfirm that the currency codes in each item's `sourceAmount` and `payoutAmount` are supported by your account.
CARD_STATUS_INVALIDFCard status is invalidCheck the card status and retry with a valid card.
CARD_INFO_ABNORMALFCard info abnormalCheck the item's `beneficiary.bankDetails` fields and retry with valid account information.
CARD_CERTIFICATE_INFO_MISSFCard certificate info is missingProvide the required certificate information in the item's `beneficiary.bankDetails`.
WALLET_INFO_ABNORMALFWallet info abnormalCheck the item's `beneficiary.walletDetails` fields and retry with valid wallet information.
WALLET_TEMPLATE_NOT_EXISTFWallet template does not existCheck the item's `beneficiary.walletDetails.walletBrandName`.
BALANCE_NOT_ENOUGHFInsufficient balanceEnsure the payer account has sufficient balance.
AMOUNT_EXCEED_LIMITFAmount exceeds limitReduce the item amount to within the allowed limit.
BATCH_PAYOUT_NOT_FOUNDFBatch payout not foundConfirm that `id` belongs to the current account context.
BATCH_ITEM_STATUS_NOT_SUPPORTEDFItem status does not support this operationDo not resubmit an item that has already advanced to an unsupported status.
BATCH_PAYOUT_STATUS_NOT_SUPPORTEDFBatch status does not support this operationAdd items only while the batch is in `INIT` status.
Definition
POST /api/open/v1/batchPayouts/addItems
Request
{
"id": "bp_20260808****",
"items": [
  {
    "requestId": "req_item_20260808_0001",
    "businessSceneCode": "THIRD_PARTY_PAYOUT",
    "beneficiary": {
      "accountType": "BANK_ACCOUNT",
      "beneficiaryId": "ben_9f7c****"
    },
    "payoutAmount": {
      "value": 500000,
      "currency": "USD"
    },
    "purposeCode": "SAL",
    "reference": "Salary August 2026",
    "transferMemo": "Employee ID E1001"
  }
]
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "bp_20260808****",
"status": "INIT",
"createdAt": "2026-08-08T10:00:00+08:00",
"updatedAt": "2026-08-08T10:05:00+08:00",
"requestId": "req_batch_20260808_0001",
"batchName": "Payroll 2026-08",
"transferMemo": "August payroll run",
"totalItemCount": 2,
"validItemCount": 0,
"items": [
  {
    "requestId": "req_item_20260808_0001",
    "itemId": "item_20260808_0001",
    "status": "INVALID",
    "failureCode": "BENEFICIARY_INACTIVE",
    "failureMessage": "The referenced beneficiary is not ACTIVE. Activate the beneficiary or use an active beneficiary."
  }
]
}