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

# Bulk payout

> Send up to 100 payouts in one request. Each row succeeds or fails on its own, and one idempotency key covers the whole batch.



## OpenAPI

````yaml /openapi.json post /v1/payouts/bulk
openapi: 3.0.0
info:
  title: Payve API
  version: v1
  description: >-
    Send, collect and convert money across African corridors. Amounts are
    integers in minor units.
servers:
  - url: https://sandbox.api.payvehq.com
    description: Sandbox
  - url: https://api.payvehq.com
    description: Live
security:
  - api-key: []
tags:
  - name: quotes
    description: Lock an exchange rate and fee before you move money.
    x-group: Quotes
  - name: payouts
    description: Send money to bank accounts and mobile money wallets.
    x-group: Payouts
  - name: payins
    description: Collect money from a payer.
    x-group: Pay-ins
  - name: payment-links
    description: Hosted checkout pages you can share.
    x-group: Payment links
  - name: conversions
    description: Move a balance from one of your wallets to another currency.
    x-group: Conversions
  - name: wallets
    description: Balances and virtual accounts.
    x-group: Wallets
  - name: beneficiaries
    description: Saved payout recipients.
    x-group: Beneficiaries
  - name: refunds
    description: Return a pay-in to the payer.
    x-group: Refunds
  - name: statements
    description: Statement files for your wallets.
    x-group: Statements
  - name: webhooks
    description: Read your endpoints and delivery history.
    x-group: Webhooks
  - name: reference-data
    description: Currencies, indicative rates, banks and operators. No key needed.
    x-group: Reference data
paths:
  /v1/payouts/bulk:
    post:
      tags:
        - payouts
      summary: Bulk payout
      description: >-
        Send up to 100 payouts in one request. Each row succeeds or fails on its
        own, and one idempotency key covers the whole batch.
      operationId: PayoutsController_bulk
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkPayoutDto'
      responses:
        '200':
          description: Per-item results — check each item.status for success/failure
        '400':
          description: Idempotency key missing
        '422':
          description: Validation error on the request body
      security:
        - api-key: []
components:
  schemas:
    CreateBulkPayoutDto:
      type: object
      properties:
        items:
          description: Up to 100 payout items
          type: array
          items:
            $ref: '#/components/schemas/InitiatePayoutDto'
      required:
        - items
    InitiatePayoutDto:
      type: object
      properties:
        sourceCurrency:
          type: string
          enum:
            - NGN
            - GHS
            - KES
        destinationCurrency:
          type: string
          enum:
            - NGN
            - GHS
            - KES
        amount:
          type: number
          description: Amount in minor units
          example: 100000
        method:
          type: string
          enum:
            - bank_transfer
            - card
            - mobile_money
            - eft
            - cash_pickup
            - virtual_account
        beneficiary:
          $ref: '#/components/schemas/BeneficiaryDto'
        merchantReference:
          type: string
          maxLength: 255
        quoteId:
          type: string
        narration:
          type: string
          maxLength: 255
        metadata:
          type: object
        idempotencyKey:
          type: string
          description: Per-item idempotency key for safe bulk retries
          maxLength: 255
      required:
        - sourceCurrency
        - destinationCurrency
        - amount
        - method
        - beneficiary
    BeneficiaryDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - bank_account
            - mobile_money
        accountNumber:
          type: string
        bankCode:
          type: string
        mobileNumber:
          type: string
        holderName:
          type: string
        country:
          type: string
          example: NG
      required:
        - type
        - country
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Your secret key. It starts with sk_test_ or sk_live_.

````