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

# Create a bulk-pay batch

> Create a draft batch of disbursements. Up to a fixed maximum number of
recipients per batch. **Requires scope `bulk_pay`.**




## OpenAPI

````yaml /openapi.yaml post /merchant/api/bulk/batches
openapi: 3.1.0
info:
  title: Kori Merchant API
  version: 1.0.0
  description: >
    The Kori Merchant API lets your application collect and disburse
    mobile-money

    payments across Mali (Orange Money, Wave, Sama, Moov) and manage payouts,

    beneficiaries, bulk payments, payment links, your team, webhooks and
    settings.


    Every endpoint documented here is reachable with a **merchant API key**. You

    exchange your API key + secret for a short-lived **Bearer token** scoped to
    a set

    of permissions, then call the rest of the API with that token. The scopes
    you can

    grant are exactly the ones shown in the **API Keys** screen of your Kori
    dashboard.


    ## Authentication flow

    1. `POST /merchant/api/auth` with `X-API-Key` and `X-API-Secret` headers.
    Optionally
       request a subset of `scopes` and an expiry (`expires_in_hours`, 1–720).
    2. Use the returned `data.token` as `Authorization: Bearer <token>` on every
    other call.

    3. Each endpoint requires a specific scope; a token missing that scope gets
    `403`.


    ## Response envelope

    All responses share the shape `{ "success": boolean, "message"?: string,

    "request_id"?: string, "data"?: object }`. Errors set `success: false` and a

    human-readable `message`.


    ## Asynchronous payments

    `POST /merchant/api/pay` returns `202` with `status: "pending"` — the
    customer has

    only been *prompted*. Wait for the `payment_received` webhook (or poll the

    transaction) before treating a collection as paid. Never rely on the HTTP
    response

    alone to mark an order complete.
  contact:
    name: Kori Support
    url: https://kori.ml
servers:
  - url: https://api.kori.ml
    description: Production
  - url: https://dev.kori.ml
    description: Sandbox / development
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: Exchange your API key + secret for a scoped Bearer token.
  - name: Payments
    description: >-
      Collect from customers (`pay`), disburse (`deposit`), check balance and
      transactions.
  - name: Payouts
    description: Withdraw your balance to mobile money or bank accounts.
  - name: Beneficiaries
    description: Saved payout recipients.
  - name: Payment Links
    description: Shareable hosted payment pages.
  - name: Bulk Pay
    description: Batch disbursements to many recipients.
  - name: Team
    description: Manage dashboard team members and roles.
  - name: Webhooks
    description: Register endpoints to receive event notifications.
  - name: Settings
    description: Merchant account preferences.
paths:
  /merchant/api/bulk/batches:
    post:
      tags:
        - Bulk Pay
      summary: Create a bulk-pay batch
      description: |
        Create a draft batch of disbursements. Up to a fixed maximum number of
        recipients per batch. **Requires scope `bulk_pay`.**
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/BulkRecipientInput'
      responses:
        '201':
          description: Batch created (draft).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/BulkBatch'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    BulkRecipientInput:
      type: object
      required:
        - name
        - account
        - amount
        - payment_method
      properties:
        name:
          type: string
        account:
          type: string
        amount:
          type: number
          format: float
        payment_method:
          $ref: '#/components/schemas/PayoutMethod'
    Envelope:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        request_id:
          type: string
          format: uuid
    BulkBatch:
      type: object
      properties:
        id:
          type: integer
        status:
          $ref: '#/components/schemas/BulkStatus'
        recipient_count:
          type: integer
        total_amount:
          type: number
          format: float
        created_at:
          type: string
          format: date-time
    PayoutMethod:
      type: string
      description: Destination method for payouts (BankTransfer not yet supported).
      enum:
        - OrangeMoney
        - Wave
        - Sama
        - Moov
        - BankTransfer
    BulkStatus:
      type: string
      enum:
        - draft
        - processing
        - completed
        - partial
        - failed
        - cancelled
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid or missing parameter
        request_id:
          type: string
          format: uuid
  responses:
    BadRequest:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, or expired Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Token lacks the required scope (or IP not whitelisted).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Scoped Bearer token from `POST /merchant/api/auth`.

````