> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fossapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Bulk Payout Batch

> Validate, fund, and submit an immediate NGN payout batch from a CSV file

Creates an immediate, all-or-nothing payout batch funded by the authenticated merchant's master wallet or one of its subaccounts. The configured single-payout fee is charged for every CSV row.

## CSV columns

| Column           | Rules                                               |
| ---------------- | --------------------------------------------------- |
| `Account Number` | Exactly 10 digits                                   |
| `Bank Name`      | A name from the supported-bank directory            |
| `Amount`         | Positive NGN amount with at most two decimal places |
| `Narration`      | Required; maximum 255 characters                    |

The required header must be the first non-empty row and fields must be separated with commas. Remove spreadsheet column-label rows such as `A,B,C,D`; semicolon- and tab-delimited exports are not accepted.

## Request

```bash theme={null}
curl --request POST \
  --url https://api-production.fossapay.com/api/v1/payouts/batches \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header 'X-Idempotency-Key: payroll-2026-09-v1' \
  --form 'accountNumber=9710000000' \
  --form 'batchReference=PAYROLL-2026-09' \
  --form 'executionMode=IMMEDIATE' \
  --form 'csvFile=@./payroll-2026-09.csv;type=text/csv'
```

Do not set `Content-Type` manually; your client must include the generated multipart boundary. A successful `202` response means the batch was accepted for processing, not that recipients have been paid.

## Idempotency

The same key, form fields, and exact CSV bytes return the original batch. Changed fields or file bytes with the same key return `409`. The `batchReference` must be globally unique.

See the [Bulk Payouts guide](/guides/bulk-payouts) for the CSV format, processing lifecycle, retries, webhooks, and scheduling guidance.


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/payouts/batches
openapi: 3.1.0
info:
  title: FossaPay API
  description: >-
    FossaPay API for checkout wallets, master-wallet payouts, customer
    management, NGN wallets, crypto wallets, transfers, fees, banks, and
    webhooks.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-production.fossapay.com
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/payouts/batches:
    post:
      tags:
        - Bulk Payouts
      summary: Create an immediate bulk payout batch
      description: >-
        Validates a CSV, charges the configured payout fee per recipient, and
        submits an immediate all-or-nothing batch from a merchant-owned master
        or subaccount wallet.
      operationId: ExternalPayoutController_createBatch
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: true
          description: >-
            Unique key for this logical batch. Idempotency-Key is also accepted;
            if both headers are sent, they must match.
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BulkPayoutCreateRequest'
      responses:
        '202':
          description: Batch accepted for processing or idempotently replayed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPayoutResponse'
        '400':
          description: >-
            Invalid multipart request, CSV row, bank, source wallet, balance,
            configuration, or provider request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: >-
            Missing, invalid, inactive, revoked, non-live, or
            non-full-permission API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Merchant KYC approval is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            Duplicate global batch reference or incompatible idempotency-key
            reuse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: >-
            Batch service is temporarily unavailable or the outcome requires
            reconciliation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    BulkPayoutCreateRequest:
      type: object
      required:
        - accountNumber
        - batchReference
        - executionMode
        - csvFile
      properties:
        accountNumber:
          type: string
          description: Merchant-owned master wallet or subaccount number funding the batch.
        batchReference:
          type: string
          maxLength: 255
          description: Globally unique merchant-defined batch reference.
        executionMode:
          type: string
          enum:
            - IMMEDIATE
        csvFile:
          type: string
          format: binary
          description: >-
            UTF-8 CSV containing Account Number, Bank Name, Amount, and
            Narration columns.
      additionalProperties: false
    BulkPayoutResponse:
      type: object
      required:
        - status
        - statusCode
        - message
        - data
      properties:
        status:
          type: string
          const: success
        statusCode:
          type: integer
          enum:
            - 200
            - 202
        message:
          type: string
        data:
          $ref: '#/components/schemas/BulkPayout'
      additionalProperties: false
    ApiError:
      type: object
      properties:
        status:
          oneOf:
            - type: string
            - type: boolean
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
        code:
          type: string
        errors:
          type: object
          additionalProperties: true
      additionalProperties: true
    BulkPayout:
      type: object
      required:
        - id
        - reference
        - accountNumber
        - status
        - executionMode
        - totalRecipients
        - totalAmount
        - totalFee
        - totalDebit
        - failureReason
        - completedAt
        - failedAt
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
        accountNumber:
          type: string
        status:
          type: string
          enum:
            - processing
            - completed
            - failed
        executionMode:
          type: string
          enum:
            - IMMEDIATE
        totalRecipients:
          type: integer
        totalAmount:
          type: string
        totalFee:
          type: string
        totalDebit:
          type: string
        failureReason:
          type:
            - string
            - 'null'
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
        failedAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````