Batch Payouts

Batch payouts let you send, track, and reconcile large volumes of payments in bulk using a single request.

Unlike individual payouts, batch payouts are processed asynchronously. Submitting one batch immediately returns a batchId, while validation, execution, and the individual final payout outcomes occur in the background.

Batch payouts are built for workflows that require a high amount payouts such as payroll, marketplace disbursements, vendor payments, invoice settlements, and creator payouts—where speed, scale, reliability, and transparency matter.

For single payouts, see Transfer Money.
To create a batch payout using a CSV file, see Batch Payouts.

When to use batch payouts

Batch payouts solve three core problems for entities that process a high number of payments:

• Scale without complexity: Submit up to 1,000 payouts in a single request, while still receiving per-payout results and full visibility to help with auditing.
• Built-in reliability: All payouts are validated before execution, helping prevent downstream failures, reconciliation gaps, and reducing operational overhead.
• End-to-end transparency: Track every payout using:
  • Batch-level and item-level statuses
  • Real-time webhook notifications
  • Status endpoints for reconciliation and reporting

Using batch payouts

A batch of payouts gets processed asynchronously in four steps:

1. Create and submit: Send a batch containing multiple payout instructions.
2. Reviewed: Each payout is checked by Nium for schema, compliance, and corridor-specific rules.
3. Processed: Valid payouts move into execution.
4. Complete: The state of each individual payout gets updated:

You can mix different beneficiary types, customers, wallets, and payout methods within the same batch.

As payouts update, you'll receive webhooks with updates to the state and status of payouts.

Funding behavior

Batch payouts debit funds from the specified wallet for each individual payout. Funds are reserved only after the payout is successfully validated and processing begins; funds are not debited at submission time..

When scheduling batch payouts, prefunding rules apply. For more information, see Prefund Account

Key concepts

Key concepts of batch payouts include:

Concept	Description
batch	A group of individual payouts submitted together in bulk.
batchExternalId	Unique identifier you create to track a batch.
batchStatus	Overall processing state of the batch.
item	A single payout within a batch.
itemStatus	The processing state of the individual payout.

Nium API

The requests available to manage batch payouts include:

Request	Method	Endpoint	Description
Create Batch Payout	POST	/payout/bulk	Submit a new batch of payouts.
Fetch Batch Payout Status	GET	/payout/bulk/{batchId}/status	Retrieve batch-level status and summary
List Payouts in a Batch	GET	/payout/bulk/{batchId}	Retrieve payout-level results (supports filtering and pagination)

Please note, the following limits apply:

• Maximum payouts per batch: 1,000 payouts
• Maximum request payload size: 10 MB

Create a Batch Payout

Use the POST request Create Batch Payout to create a batch payout.

Use the payouts object to include the details of the beneficiary and paymentAccount for each payout. Please note:

• A batch can complete successfully even if some individual payouts fail or are returned.
• Submitting a batch does not execute payouts immediately. Use webhooks or the status field to track the progress of payouts.

Request example

curl --request POST \
  --url https://gateway.nium.com/api/payout/bulk \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \
  --data '{
    "fundingSource": {
      "fundingInstrumentId": "fi_123456",
      "fundingChannel": "DIRECT_DEBIT",
      "statementNarrative": "November Payroll"
    },
    "batchExternalId": "payroll-2025-11-30",
    "executeAt": "2025-11-30",
    "payouts": [
      {
        "externalId": "TEST10-ITEM-001",
        "customerHashId": "1027d7c5-2577-4e1e-b462-c15728fe16e8",
        "walletHashId": "d396c4d4-dd23-4cc4-a5c0-d0a1d9f151d2",
        "beneficiary": {
          "beneficiary": {
            "name": "John Doe",
            "accountType": "INDIVIDUAL",
            "addresses": [
              {
                "type": "BILLING",
                "line1": "6",
                "line2": "Levuka St",
                "city": "Cairns",
                "state": "Queensland",
                "countryCode": "AU",
                "postalCode": "4868"
              }
            ]
          },
          "paymentAccount": {
            "accountNumber": "999994",
            "payoutCurrency": "AUD",
            "payoutMethod": "LOCAL",
            "routingCode": [
              {
                "type": "BSB CODE",
                "value": "063019"
              }
            ]
          }
        },
        "payout": {
          "payoutCurrency": "AUD",
          "sourceCurrency": "USD",
          "destinationAmount": "100"
        }
      }
    ]
  }'

Response example

{
    "batchExternalId": "TEST010",
    "batchId": "dee896d5-3f40-4f9f-a799-f4f84fa9791e",
    "status": "RECEIVED",
    "totalCount": 1
}

Lifecycle of batch payouts

After a batch payout is submitted, it updates to the following statuses:

status	Description
received	The batch was accepted and waiting for the payouts to be validated by Nium.
validated	Validation completed. Returns counts for payouts that were both accepted and returned validation errors.
processing	Accepted payouts are being processed.
completed	All accepted payouts have reached a final status.
partially_failed	Some accepted payouts ended in returned or failed status. Review the individual payout for more details.
failed	Batch could not be processed.
cancelled	The batch or schedule was cancelled before processing began.

For more information, about the different statuses payouts go through, see Transaction Lifecycle.

Fetch Batch Payout Status

Use the GET request Fetch Batch Payout status to retrieve the overall status of a batch.

Request example

curl --url https://gateway.nium.com/api/payout/bulk{batchId}/status \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0'

Response example

{
    "batchExternalId": "TEST010",
    "batchId": "dee896d5-3f40-4f9f-a799-f4f84fa9791e",
    "status": "ACCEPTED",
    "summary": {
        "total": 1,
        "processing": 1,
        "failed": 0,
        "paid": 0,
        "returned": 0
    },
    "createdAt": "2025-12-09T07:15:21.926139Z",
    "completedAt": null,
    "links": {
        "self": "/api/v1/client/86528edd-55a3-4a2c-9939-144ed9be43ef/payout/bulk/dee896d5-3f40-4f9f-a799-f4f84fa9791e/status",
        "items": "/api/v1/client/86528edd-55a3-4a2c-9939-144ed9be43ef/payout/bulk/dee896d5-3f40-4f9f-a799-f4f84fa9791e?status=INITIATED"
    }
}

List Payouts in a Batch

Use the GET request List Payouts in a Batch to list the details of the items or individual payouts in a batch.

Query parameters

Parameter	Description
status	Filter returned payouts by status.
externalId	Filter returned payouts by the externalId used during payout creation.
limit	Maximum number of payouts returned per page.
cursor	Pagination cursor.

Response example

{
  "batchExternalId": "cust-001",
  "batchId": "b_20251103",
  "page": {
    "limit": 3,
    "nextCursor": "eyJvZmZzZXQiOjZ9",
    "prevCursor": "eyJvZmZzZXQiOjB9"
  },
  "items": [
    {
      "externalId": "INV-001",
      "transactionId": "RT987654321",
      "status": "ACCEPTED",
      "failure": [
        {
          "status": "BAD_REQUEST",
          "code": "AC03",
          "message": "The beneficiary's account number is invalid or missing.",
          "body": "string",
          "errors": [
            "tag key is mandatory"
          ],
          "field": "beneficiary.accountNumber",
          "action": "Confirm the correct beneficiary.accountNumber with the beneficiary.",
          "regex": "^[A-Za-z0-9 \\-.]{1,255}$"
        }
      ],
      "createdAt": "2025-11-03T08:59:10Z",
      "updatedAt": "2025-11-03T09:00:12Z",
      "return": {
        "code": "AC03",
        "message": "The beneficiary's account number is invalid or missing.",
        "reasonCode": "InvalidCreditorAccountNumber"
      }
    }
  ]
}

Webhook

After creating a batch payout, you receive a Batch Validated webhook when a batch of payouts has completed validation:

Event example

{
  "event": "batch.completed",
  "batchId": "b_123",
  "status": "partially_failed",
  "counts": {
    "total": 1000,
    "accepted": 400,
    "paid": 390,
    "returned": 10,
    "validation_error": 600
  }
}

Error handling

Errors that can be returned when creating a batch include:

HTTP status	Error code	Description
400	missing_field	One or more required fields are missing or fail schema validation. Resubmit the request.
409	duplicate_externalId	The same externalId appears more than once within the batch. Change the externalId and resubmit the request.
409	idempotency_conflict	The batchExternalId conflicts with an existing request. Change the batchExternalId and resubmit the request.
413	payload_too_large	The request exceeds 10 MB or contains more than 1,000 payouts. Create multiple batch payouts to process your payload.

Any payout that is returned or runs into a validation-error can be corrected and resubmitted individually or in a new batch.

Next steps

Batch payouts support scalable, asynchronous processing of high-volume payout workflows, with batch-level tracking, item-level results, and lifecycle webhooks. See:

• Nium Portal for details on how to create batch payouts, without development work, using our dashboard.
• Track Payouts to monitor batch progress, review item-level outcomes, and reconcile results