Submit a Batch Payout

Submits a fully validated batch payout for execution. All items must pass validation via Calculate a Batch Payout before submission. Depending on the approval policy configured for your WorldFirst account, the batch either enters PENDING_APPROVAL and waits for a reviewer to approve or reject it, or transitions directly to PROCESSING so WorldFirst can begin funding and dispatching each item. Once submitted, items can no longer be added, removed, or modified.
Request Parameters
idstring
required
Unique identifier of the batch payout to submit. The batch must be in INIT status with at least one item that passes validation.
Response Parameters
resultResult
See Result.
idstring
Unique identifier of the batch payout.
statusstring
Batch status after submission. PENDING_APPROVAL when manual review and approval is required; PROCESSING when the batch is dispatched immediately. 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.
submittedAtdatetime
Time the batch was submitted, 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 items currently in the batch. Range: 0 - 100.
validItemCountinteger
Number of items that passed validation. Range: 0 - 100.
calculationSummaryCalculationSummary
Latest reference pricing summary. All totals and rates are indicative — final values are determined at payout processing.
Show child parametersShow child parameters
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
PARAM_ILLEGALFIllegal parameters exist.Verify `id` is present and no longer than 64 characters.
PROCESS_FAILFA general business failure occurred. Do not retry.Do not retry. Contact WorldFirst technical support.
BATCH_NOT_EXISTFThe batch payout does not exist.Confirm `id` matches a batch returned by [Create a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/create_a_batch_payout).
BATCH_STATUS_INVALIDFOnly a batch payout in INIT status can be submitted.Check the batch `status` via [Query a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/query_a_batch_payout); already-submitted batches cannot be resubmitted.
BATCH_EMPTYFThe batch payout contains no items.Call [Add Items to a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/add_items_to_a_batch_payout) to attach at least one item before submitting.
NO_VALID_ITEMFNo item passed validation.Call [List Batch Payout Items](https://docs.worldfirst.com/wfdocs/api-sdk/list_batch_payout_items) with `status=INVALID` to inspect the failures; correct or remove them and re-run [Calculate a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/calculate_a_batch_payout).
BALANCE_NOT_ENOUGHFInsufficient balance to fund the batch payout.Top up the funding wallet or reduce the payout amount and resubmit.
AMOUNT_EXCEED_LIMITFThe batch payout amount exceeds the maximum limit or is below the minimum limit.Adjust the item amounts so the batch total is within the allowed limits, then retry.
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 to submit batch payouts.Retry with a user that has permission to submit batch payouts.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.Check the batch `status` via [Query a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/query_a_batch_payout) before submitting again.
Definition
POST /api/open/v1/batchPayouts/submit
Request
{
"id": "20260808BATCH00001"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"id": "20260808BATCH00001",
"status": "PENDING_APPROVAL",
"createdAt": "2026-08-08T09:15:00+08:00",
"updatedAt": "2026-08-08T14:00:00+08:00",
"submittedAt": "2026-08-08T14:00:00+08:00",
"requestId": "req_batch_20260808_0001",
"batchName": "Aug 8 supplier payouts",
"totalItemCount": 2,
"validItemCount": 2,
"calculationSummary": {
  "lastCalculatedAt": "2026-08-08T13:55:00+08:00",
  "currencyPairs": [
    {
      "currencyPair": "USD/USD",
      "clientRate": "1.000000",
      "sourceAmount": {
        "currency": "USD",
        "value": "5000.00"
      },
      "payoutAmount": {
        "currency": "USD",
        "value": "5000.00"
      },
      "feeRate": "0.001",
      "feeAmount": {
        "currency": "USD",
        "value": "5.00"
      },
      "feeItemList": [
        {
          "feeItemType": "PAYOUT_SERVICE_FEE",
          "feeItemAmount": {
            "currency": "USD",
            "value": "5.00"
          }
        }
      ]
    },
    {
      "currencyPair": "USD/EUR",
      "clientRate": "0.923400",
      "sourceAmount": {
        "currency": "USD",
        "value": "3000.00"
      },
      "payoutAmount": {
        "currency": "EUR",
        "value": "2770.20"
      },
      "feeRate": "0.0005",
      "feeAmount": {
        "currency": "USD",
        "value": "1.50"
      },
      "feeItemList": [
        {
          "feeItemType": "PAYOUT_SERVICE_FEE",
          "feeItemAmount": {
            "currency": "USD",
            "value": "1.50"
          }
        }
      ],
      "originalFeeRate": "0.001",
      "originalFeeAmount": {
        "currency": "USD",
        "value": "3.00"
      },
      "promotionList": [
        {
          "promotionName": "August Fee Discount",
          "promotionType": "FEE_DISCOUNT",
          "activeTime": "2026-08-01T00:00:00+08:00",
          "expiredTime": "2026-08-31T23:59:59+08:00"
        }
      ]
    }
  ]
}
}