Calculate a Batch Payout

Runs validation and pricing across every item in a batch payout and returns the aggregated FX quote. Call this endpoint on a batch in INIT status to preview indicative totals per currency pair and confirm that all items are valid before calling Submit a Batch Payout. The returned totals, fees, and rates are for reference only — final amounts and exchange rates are calculated at real payout processing. Items flagged as INVALID must be corrected via Remove Items from a Batch Payout plus Add Items to a Batch Payout before submission.
Request Parameters
idstring
required
Unique identifier of the target batch payout.
Response Parameters
resultResult
See Result.
idstring
Unique identifier of the batch payout.
statusstring
Current batch status. Remains INIT after calculation. 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 items currently in the batch. Range: 0 - 100.
validItemCountinteger
Number of items that passed validation and are eligible for submission. Range: 0 - 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
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
SYSTEM_ERRORUA system error occurred.Retry after a short delay. If the issue persists, contact WorldFirst technical support.
PARAM_ILLEGALFIllegal parameters exist.Verify `id` is present and no longer than 64 characters.
UN_SUPPORT_BUSINESSFUnsupported business.Verify the `businessSceneCode` value and ensure the currency combination is supported.
CONTRACT_NOT_EXISTFThe contract does not exist.Ensure the required payout contract is in place, then retry.
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.
ACCOUNT_NOT_EXISTFThe account does not exist.Verify the payer account exists, then retry.
ACCOUNT_STATUS_ABNORMALFThe account status is abnormal.Retry with an account in a valid status, or contact WorldFirst technical support.
BATCH_STATUS_INVALIDFA quote can only be created in INIT status.Confirm the batch is in `INIT` via [Query a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/query_a_batch_payout); submitted or terminated batches cannot be re-quoted.
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_ITEM_EMPTYFNo item in the batch payout.Add at least one item using [Add Items to a Batch Payout](https://docs.worldfirst.com/wfdocs/api-sdk/add_items_to_a_batch_payout).
BATCH_HAS_INVALID_ITEMFAn item in the batch payout failed validation.Call [List Batch Payout Items](https://docs.worldfirst.com/wfdocs/api-sdk/list_batch_payout_items) with `status=INVALID` to inspect failures; remove or replace the offending items and retry.
CURRENCY_NOT_SUPPORTEDFThe specified currency is not supported.Ensure each item's `sourceAmount.currency` and `payoutAmount.currency` are supported by your account; contact WorldFirst if unsure.
TRADE_AMOUNT_IS_NOT_ENOUGHFThe trade amount is not enough.Check the trade orders associated with the items and ensure their available amount covers the payout amounts.
BENEFICIARY_NOT_EXISTFThe beneficiary does not exist.Verify each item's `beneficiary.beneficiaryId` refers to an existing beneficiary.
BALANCE_INSUFFICIENTFInsufficient balance.Ensure the payer account has sufficient balance to fund the batch, or reduce the payout amounts.
EXCEED_MAX_COUNT_LIMITFThe maximum count limit has been exceeded.Reduce the number of items or contact WorldFirst technical support to increase the limit.
Definition
POST /api/open/v1/batchPayouts/calculate
Request
{
"id": "20260808BATCH00001"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"id": "20260808BATCH00001",
"status": "INIT",
"createdAt": "2026-08-08T09:15:00+08:00",
"updatedAt": "2026-08-08T11:00:00+08:00",
"requestId": "req_batch_20260808_0001",
"batchName": "Aug 8 supplier payouts",
"totalItemCount": 2,
"validItemCount": 2,
"calculationSummary": {
  "lastCalculatedAt": "2026-08-08T11:00:00+08:00",
  "currencyPairs": [
    {
      "currencyPair": "USD/USD",
      "clientRate": "1.000000",
      "sourceAmount": {
        "currency": "USD",
        "value": 500000
      },
      "payoutAmount": {
        "currency": "USD",
        "value": 500000
      },
      "feeRate": "0.001",
      "feeAmount": {
        "currency": "USD",
        "value": 500
      },
      "feeItemList": [
        {
          "feeItemType": "PAYOUT_SERVICE_FEE",
          "feeItemAmount": {
            "currency": "USD",
            "value": 500
          }
        }
      ]
    },
    {
      "currencyPair": "USD/EUR",
      "clientRate": "0.923400",
      "sourceAmount": {
        "currency": "USD",
        "value": 300000
      },
      "payoutAmount": {
        "currency": "EUR",
        "value": 277020
      },
      "feeRate": "0.0005",
      "feeAmount": {
        "currency": "USD",
        "value": 150
      },
      "feeItemList": [
        {
          "feeItemType": "PAYOUT_SERVICE_FEE",
          "feeItemAmount": {
            "currency": "USD",
            "value": 150
          }
        }
      ],
      "originalFeeRate": "0.001",
      "originalFeeAmount": {
        "currency": "USD",
        "value": 300
      },
      "promotionList": [
        {
          "promotionName": "August Fee Discount",
          "promotionType": "FEE_DISCOUNT",
          "activeTime": "2026-08-01T00:00:00+08:00",
          "expiredTime": "2026-08-31T23:59:59+08:00"
        }
      ]
    }
  ]
}
}