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

# Create Payment Batch

> Creates an empty batch. Add recipients with the recipient endpoints, then start the payouts with POST /api/v1/payment-batch/{batchId}/withdraw. Requires the `PAYMENT_METHOD.CREATE` key permission.

Creates an empty payment batch. Add recipients with the [add recipient](/api-reference/endpoint/payment-batches/add-recipient) or [bulk add recipients](/api-reference/endpoint/payment-batches/add-recipients-bulk) endpoints, then start the payouts with [withdraw](/api-reference/endpoint/payment-batches/withdraw).

Requires the `PAYMENT_METHOD.CREATE` key permission.


## OpenAPI

````yaml POST /api/v1/payment-batch
openapi: 3.1.0
info:
  title: Afriex Business API
  version: 1.0.13
  description: >-
    Welcome to the Afriex Business API. This API allows you to manage customers,
    process payments, handle payouts, and receive real-time notifications via
    webhooks.


    For detailed guidance on authentication, pagination, error handling, and
    webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
    the top bar. The guide provides a step-by-step instructions to help you
    integrate seamlessly.
  termsOfService: https://www.afriex.com/terms-and-condition
  contact:
    name: Afriex API Support
    email: support@afriex.com
    url: https://docs.afriex.com
  license:
    name: Proprietary
    url: https://www.afriex.com/terms-and-condition
servers:
  - url: https://sandbox.api.afriex.com
    description: Staging Base URL
  - url: https://api.afriex.com
    description: Production Base URL
security:
  - ApiKey: []
tags:
  - name: Customers
    description: Create and manage your customers.
  - name: Payment Methods
    description: Register and resolve customer payout and collection methods.
  - name: Transactions
    description: Create and track deposits, withdrawals, and swaps.
  - name: Balance
    description: View and top up your business wallet balances.
  - name: Rates
    description: Fetch real-time exchange rates.
  - name: Checkout Sessions
    description: Create hosted checkout sessions.
  - name: Webhooks
    description: Webhook event payloads and sandbox webhook testing.
  - name: Media
    description: Generate presigned URLs for secure file uploads.
  - name: Payment Batches
    description: >-
      Manage payment batches, their recipients and their runs.


      Where payload signing is enabled for your business, sign the JSON of the
      request body for POST and PATCH routes that take one. For GET routes with
      `page` and `limit`, and for the withdraw route, sign the query parameters
      as the server reads them, with defaults applied: a list call with no
      parameters signs `{"limit":100,"page":0}` and a withdraw with no
      `sessionId` signs `{}`. For the remaining routes (get, delete and
      remove-recipient) sign the path parameters, e.g. `{"batchId":"..."}`.
paths:
  /api/v1/payment-batch:
    parameters:
      - $ref: '#/components/parameters/x-api-version'
      - $ref: '#/components/parameters/x-api-signature'
    post:
      tags:
        - Payment Batches
      summary: Create a payment batch
      description: >-
        Creates an empty batch. Add recipients with the recipient endpoints,
        then start the payouts with POST
        /api/v1/payment-batch/{batchId}/withdraw. Requires the
        `PAYMENT_METHOD.CREATE` key permission.
      operationId: createPaymentBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentBatchRequest'
      responses:
        '201':
          description: The batch was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentBatch'
        '400':
          $ref: '#/components/responses/PaymentBatchBadRequest'
        '401':
          $ref: '#/components/responses/PaymentBatchUnauthorized'
components:
  parameters:
    x-api-version:
      name: x-api-version
      in: header
      required: false
      description: >-
        API version in ISO 8601 format. The only supported version is
        `2026-05-18`, which is also the default when the header is omitted. Any
        other value is rejected with a `400 Bad Request`.
      schema:
        type: string
    x-api-signature:
      name: x-api-signature
      in: header
      required: false
      description: >-
        Signature of the request payload, used for request authentication where
        payload signing is enabled for your business.
      schema:
        type: string
  schemas:
    PaymentBatchRequest:
      type: object
      required:
        - name
        - sourcePaymentMethod
      additionalProperties: false
      properties:
        name:
          type: string
          description: A label for the batch.
        sourcePaymentMethod:
          type: object
          description: >-
            The wallet the batch is funded from. Every payout is converted from
            this currency. Other keys are ignored and not stored.
          required:
            - currencyCode
          properties:
            channel:
              type: string
              enum:
                - WALLET
              default: WALLET
            currencyCode:
              type: string
              example: USD
    PaymentBatch:
      type: object
      description: A payment batch, including the method payouts are funded from.
      properties:
        id:
          type: string
        name:
          type: string
        sourcePaymentMethod:
          type: object
          description: >-
            The payment method the batch is funded from, as the payment-method
            endpoints return it. Round-tripped whole on update.
        meta:
          type: object
          properties:
            memberCount:
              type: integer
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        errorMessage:
          type: string
          description: Detailed/technical error message.
        friendlyMessage:
          type: string
          description: User-facing error message safe to display.
        data:
          type: object
          description: >-
            Optional caller-safe context for the error. On a customer-create
            uniqueness conflict (EMAIL_ALREADY_EXISTS /
            PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
            id, so you can adopt it without a follow-up lookup.
          properties:
            customerId:
              type: string
              description: Id of the existing customer (on a create conflict).
  responses:
    PaymentBatchBadRequest:
      description: >-
        The request is invalid, or it came from an IP outside the business's
        whitelist or carried a bad payload signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentBatchUnauthorized:
      description: >-
        Missing or invalid API key, or a key without the permission this
        endpoint requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Static business API key issued from the dashboard. A business can

        provision **multiple API keys**, each scoped to a configurable set of

        **permissions** (e.g. read transactions, create deposits, etc).
        Permissions are chosen per key at creation time in the

        dashboard and may be revoked by deleting the key. Requests made with a

        key that does not include the permission required by the target

        endpoint is rejected with a `401 Unauthorized` response, the same

        response an unrecognised, malformed, revoked or disabled key returns.
        The API

        does not distinguish the two cases on the wire.

        Manage your keys and their permissions under **Developer → API keys**

        in the dashboard.


        The permission each endpoint requires is below. Where several are

        listed, any one of them is enough. Keys created before permissions

        existed carry none and keep access to every endpoint.


        | Endpoint | Permission |

        | --- | --- |

        | `GET /customer`, `GET /customer/{customerId}` | `CUSTOMER.READ` |

        | `POST /customer` | `CUSTOMER.CREATE` |

        | `PATCH /customer/{customerId}`, `PATCH /customer/{customerId}/kyc`,
        `POST /customer/{customerId}/verify` | `CUSTOMER.UPDATE` |

        | `DELETE /customer/{customerId}` | `CUSTOMER.DELETE` |

        | `GET /payment-method`, `GET /payment-method/{paymentMethodId}`, `GET
        /payment-method/institution`, `GET /payment-method/institution/codes`,
        `GET /payment-method/resolve`, `GET /payment-method/virtual-account`,
        `GET /payment-method/pool-account` | `PAYMENT_METHOD.READ` |

        | `POST /payment-method`, `DELETE /payment-method/{paymentMethodId}`,
        `POST /payment-method/virtual-account`, `GET
        /payment-method/crypto-wallet` | `PAYMENT_METHOD.CREATE` |

        | `POST /transaction` | `TRANSACTION.DEPOSIT.CREATE`,
        `TRANSACTION.WITHDRAW.CREATE` or `TRANSACTION.SWAP.CREATE` |

        | `POST /transaction/{transactionId}/authorize`, `POST
        /transaction/pool-account` | `TRANSACTION.DEPOSIT.CREATE` |

        | `GET /transaction`, `GET /transaction/{transactionId}`, `GET
        /transaction/{transactionId}/advice` | `TRANSACTION.HISTORY.READ` |

        | `GET /org/balance`, `GET /org/rates` | `WALLET.BALANCES.READ` |

        | `POST /media/url` | `PAYMENT_METHOD.CREATE` |

        | `POST /sme-registration` | `COMPLIANCE.KYB.SUBMIT` |

        | `GET /sme-registration/status` | `COMPLIANCE.KYB.READ` |

        | `POST /checkout-session` | `CHECKOUT_LINK.CREATE` |

        | `GET /payment-batch`, `GET /payment-batch/{batchId}`, `GET
        /payment-batch/{batchId}/recipients` | `PAYMENT_METHOD.READ` |

        | `POST /payment-batch`, `PATCH /payment-batch/{batchId}`, `DELETE
        /payment-batch/{batchId}`, `POST /payment-batch/{batchId}/recipients`,
        `POST /payment-batch/{batchId}/recipients/bulk`, `PATCH
        /payment-batch/{batchId}/recipients/{recipientId}`, `DELETE
        /payment-batch/{batchId}/recipients/{recipientId}` |
        `PAYMENT_METHOD.CREATE` |

        | `POST /payment-batch/{batchId}/withdraw` |
        `TRANSACTION.WITHDRAW.CREATE` |

        | `GET /payment-batch/{batchId}/sessions` | `TRANSACTION.HISTORY.READ` |

        | `POST /org/balance/topup`, `POST /webhooks/trigger` | None; any valid
        key |

````