> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Bulk Payouts

Bulk payouts allow you to send funds to multiple recipients in a single API call. This is ideal for processing large batches of disbursements efficiently, such as payroll, marketplace payouts, or mass customer disbursements.

## When to Use Bulk Payouts

* Processing payroll for multiple employees
* Marketplace seller payouts
* Mass customer disbursements
* Regular scheduled payments
* High-volume operations

## Creating Bulk Payouts

A bulk payout request can include multiple payouts in a single batch. Each payout in the batch follows the same structure as a single payout:

* `merchantId`: Your merchant identifier
* `merchantReference`: Your internal reference for tracking and idempotency
* `destinationValue`: Object with `minorAmount` (integer) and `currency`
* `paymentMethodId`: `"banktransfer"`, `"mobilemoney"`, `"cash"`, or `"institutionwallet"` (note: no underscore, unlike the matching `recipient.type`)
* `paymentLocation`: 3-letter ISO country code
* **Either** `recipient` (inline details) **or** `payoutBeneficiaryId` (reference to a pre-validated recipient). These are mutually exclusive per item — but different items in the same batch can mix and match. See [Payout Beneficiaries](/payout-beneficiaries) for the registration flow, or [Single Payouts → Choosing a Destination](/payout-single#choosing-a-destination) for a side-by-side overview.
* `sender`: Sender details for KYT/KYC screening — `fullName`, `identity`, and `identityNumber` are required for all payouts; some destinations require additional fields (see the market pages)
* `attributes` (optional): Additional payout attributes

**Note:** Amounts are specified in **minor units** (integer), per the currency's ISO 4217 exponent — most currencies have 2 decimal places, XOF/XAF/UGX have none. See [Single Payouts](/payout-single#amount-format) for details.

## Request Structure

```json
{
  "payouts": [
    {
      "merchantId": "your-merchant-id",
      "merchantReference": "PAYOUT-001",
      "destinationValue": {
        "minorAmount": 1000000,
        "currency": "NGN"
      },
      "paymentMethodId": "banktransfer",
      "paymentLocation": "NGA",
      "recipient": {
        "type": "bank_account",
        "accountNumber": "0123456789",
        "bankCode": "044",
        "accountHolderName": "John Doe",
        "country": "NGA"
      },
      "sender": {
        "fullName": "Jane Smith",
        "identity": "passport",
        "identityNumber": "A12345678"
      },
      "attributes": {}
    },
    {
      "merchantId": "your-merchant-id",
      "merchantReference": "PAYOUT-002",
      "destinationValue": {
        "minorAmount": 500000,
        "currency": "KES"
      },
      "paymentMethodId": "mobilemoney",
      "paymentLocation": "KEN",
      "recipient": {
        "type": "mobile_money",
        "phoneNumber": "254712345678",
        "country": "KEN",
        "operator": "mpesa",
        "name": "Jane Smith"
      },
      "sender": {
        "fullName": "Jane Smith",
        "phoneNumber": "27821234567",
        "nationality": "ZAF",
        "identity": "passport",
        "identityNumber": "A12345678",
        "dateOfBirth": "1990-01-15",
        "purposeOfFunds": "salary",
        "sourceOfFunds": "business income",
        "relationship": "employer"
      },
      "attributes": {}
    },
    {
      "merchantId": "your-merchant-id",
      "merchantReference": "PAYOUT-003",
      "destinationValue": {
        "minorAmount": 5000000,
        "currency": "UGX"
      },
      "paymentMethodId": "mobilemoney",
      "paymentLocation": "UGA",
      "payoutBeneficiaryId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "sender": {
        "fullName": "Jane Smith",
        "identity": "passport",
        "identityNumber": "A12345678"
      },
      "attributes": {}
    }
  ]
}
```

**Note:** `minorAmount: 1000000` = 10,000.00 NGN, `minorAmount: 500000` = 5,000.00 KES, `minorAmount: 5000000` = 5,000,000 UGX (UGX has no minor unit). The third item shows the `payoutBeneficiaryId` form — see [Payout Beneficiaries](/payout-beneficiaries).

## Response Structure

Bulk payouts are processed asynchronously. The create request returns a `202 Accepted` with a batch ID and monitor URL.

```json
{
  "message": "Batch accepted for processing",
  "batchId": "batch_1234567890",
  "monitorUrl": "https://api.crisscross.money/v1/payouts/bulk/batch_1234567890"
}
```

**Response fields:**

* `message`: Status message confirming the batch was accepted
* `batchId`: Identifier for the batch
* `monitorUrl`: URL to poll for batch status

## Benefits

* **Efficiency**: Process multiple payouts in one API call
* **Performance**: Reduced API calls and faster processing
* **Reliability**: Batch processing with status tracking for each payout
* **Cost-effective**: Lower overhead for high-volume operations
* **Partial Success Handling**: Individual payouts can succeed or fail independently

## Example Use Cases

* **Payroll**: Distribute salaries to all employees at once
* **Marketplace Payouts**: Pay out earnings to multiple sellers
* **Mass Refunds**: Process refunds for multiple customers
* **Regular Disbursements**: Scheduled payments to multiple recipients

## Handling Partial Failures

When processing bulk payouts, individual payouts may succeed or fail independently. Use the `monitorUrl` to poll for batch status and outcomes, or consume updates via webhooks.

## Error Handling

If the entire bulk request fails (e.g., invalid request structure, authentication error), the API returns an HTTP 400, 401, or 422 with an error object:

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid bulk payout request structure"
  }
}
```

If the request succeeds, the response is HTTP 202 with a `batchId` and `monitorUrl`. Use the monitor URL or webhooks to check individual outcomes.

## Best Practices

* Validate all recipient details before creating bulk payouts
* Use unique, meaningful references for each payout (enables idempotency and easy tracking)
* Monitor batch status and individual payout statuses through history endpoints or webhooks
* Implement retry logic for failed payouts (with corrected recipient details)
* Keep batch sizes manageable and consider splitting very large batches
* Check the `successful` and `failed` counts in the response
* Review individual payout `status` and `failureReason` fields for failed payouts
* Store payout IDs and references for reconciliation and tracking

For detailed API documentation, see the [Payouts API Reference](/api-reference/payouts/payouts/create-bulk-payouts).