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

# Create Bulk Payout

> Submits multiple payout orders in a single request using the Bulk Payout API. Orders are validated and processed independently — a failure in one order does not block the others.

<Info>This API is still under construction.</Info>

## Error responses

| **Status** | **Message**                                           | **What it means**                                                        | **How to fix**                                                                |
| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| 400        | `Insufficient wallet balance for transaction`         | Wallet balance cannot cover the total payout amount plus fees.           | Top up the wallet or reduce the number of orders before retrying.             |
| 400        | `Quotes only last for 10 minutes`                     | One or more referenced quotes expired before submission.                 | Generate fresh bulk quotes and submit the payout immediately.                 |
| 400        | `Invalid country or currency ISO code`                | Unsupported country/currency combination in a recipient.                 | Use corridor-supported ISO codes for both quote and recipient data.           |
| 400        | `Account name mismatch, use account enquiry endpoint` | Account name in payload differs from bank enquiry results.               | Re-run account enquiry and match the returned account name.                   |
| 400        | `Invalid Bank Sortcode`                               | Sort code missing, malformed, or unsupported.                            | Fetch the correct sort code from the bank list and verify formatting.         |
| 400        | `{field_name} cannot be empty`                        | Required recipient field omitted from the payload.                       | Fill in every mandatory field (name, account number, etc.) before submitting. |
| 400        | `Duplicate quote ID in bulk order`                    | The same quote ID was provided multiple times in the bulk order request. | Ensure each quote ID is unique within the same bulk order.                    |
| 401        | `API key missing or incorrect`                        | `x-api-key` header absent, invalid, or expired.                          | Supply the correct API key for the environment you are targeting.             |
| 403        | `IP not whitelisted`                                  | Request originated from an unapproved IP.                                | Add your server IP to the dashboard allowlist.                                |
| 422        | `Invalid quote ID provided`                           | Quote ID missing, invalid, expired, or already consumed.                 | Create new bulk quotes and reference them in the payout call.                 |
| 500        | `Service temporarily unavailable`                     | Temporary backend/service disruption.                                    | Retry with exponential backoff; contact support if it persists.               |


## OpenAPI

````yaml post /v1/bulk/payout
openapi: 3.0.3
info:
  title: meCash API
  version: 3.0.3
  description: >-
    API for meCash services, including FIAT and Ramp operations. This is the
    OpenAPI specification for the meCash API, covering all available endpoints
    for wallet management, currency quotes, and payouts.


    It follows a design-first approach based on OpenAPI 3.0.


    Authentication is handled via an API key passed in the `x-api-key` header.
    Replace `YOUR_API_KEY` with your actual key when making requests.


    Some useful links:

    - [meCash Documentation](https://docs.me-cash.com/)

    - [Authentication Guide](https://docs.me-cash.com/authentication)
servers:
  - url: https://sandboxapi.me-cash.com
    description: Sandbox Server for Testing
security:
  - ApiKeyAuth: []
tags:
  - name: Wallet
    description: Wallet management operations
  - name: Quote
    description: Currency quote operations
  - name: Payout
    description: Payout operations
  - name: Transaction
    description: Transaction management
  - name: Virtual Account
    description: Virtual account operations for static and dynamic accounts
  - name: Bank
    description: Bank account and list operations
  - name: Ramp
    description: Ramp operations for crypto
  - name: Miscellaneous
    description: Utility and miscellaneous operations
  - name: Collection
    description: Mobile money and wallet funding operations
  - name: Bulk Payout
    description: >-
      Bulk transfer operations for sending to multiple beneficiaries in a single
      request
paths:
  /v1/bulk/payout:
    post:
      tags:
        - Bulk Payout
      summary: Create Bulk Payout
      description: >-
        Submits multiple payout orders in a single request using the Bulk Payout
        API. Orders are validated and processed independently — a failure in one
        order does not block the others.
      operationId: createBulkPayout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkPayoutRequest'
            example:
              items:
                - referenceNumber: '12345'
                  targetAmount: '1500'
                  reason: Salary payment
                  recipient:
                    name: NNOROM UZOMA CHUKWUDI
                    account:
                      bankName: FCMB
                      sortCode: '214'
                      accountNumber: '2483520014'
                    paymentChannel: BANK_TRANSFER
                    currency: NGN
                    country: NG
                - referenceNumber: '67890'
                  targetAmount: '1100'
                  reason: Salary payment
                  recipient:
                    name: NNOROM UZOMA CHUKWUDI
                    account:
                      bankName: FCMB
                      sortCode: '214'
                      accountNumber: '2483520014'
                    paymentChannel: BANK_TRANSFER
                    currency: NGN
                    country: NG
              source:
                currency: NGN
                country: NG
              target:
                currency: NGN
                country: NG
              paymentChannel: BANK_TRANSFER
              remark: June 2026 Salary
      responses:
        '200':
          $ref: '#/components/responses/BulkPayoutCreatedSuccess'
        '400':
          $ref: '#/components/responses/PayoutBadRequest'
        '401':
          $ref: '#/components/responses/PayoutUnauthorized'
        '403':
          $ref: '#/components/responses/PayoutForbidden'
        '500':
          $ref: '#/components/responses/PayoutInternalServerError'
components:
  schemas:
    CreateBulkPayoutRequest:
      type: object
      required:
        - items
        - source
        - target
        - paymentChannel
        - remark
      properties:
        items:
          type: array
          description: List of payout orders to process in the bulk payload.
          items:
            $ref: '#/components/schemas/BulkPayoutOrderItem'
        source:
          type: object
          description: The source currency and country for the batch.
          required:
            - currency
            - country
          properties:
            currency:
              type: string
              description: ISO 4217 currency code of the source wallet (e.g., NGN).
              example: NGN
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code of the source (e.g., NG).
              example: NG
        target:
          type: object
          description: The target currency and country for the batch.
          required:
            - currency
            - country
          properties:
            currency:
              type: string
              description: ISO 4217 currency code of the target (e.g., NGN).
              example: NGN
            country:
              type: string
              description: >-
                ISO 3166-1 alpha-2 country code of the target recipient (e.g.,
                NG).
              example: NG
        paymentChannel:
          type: string
          description: The overall payment channel intended for the batch.
          enum:
            - BANK_TRANSFER
            - MOBILE_MONEY
          example: BANK_TRANSFER
        remark:
          type: string
          description: A general remark for the bulk payout.
          example: June 2026 Salary
    BulkPayoutOrderItem:
      type: object
      required:
        - referenceNumber
        - targetAmount
        - reason
        - recipient
      properties:
        referenceNumber:
          type: string
          description: Unique reference number for this specific payout item.
          example: REF_ZZOEAZH8ZJI6
        targetAmount:
          type: string
          description: The amount to send to the recipient.
          example: '1500'
        reason:
          type: string
          description: Purpose of the transfer.
          example: Salary payment
        recipient:
          type: object
          required:
            - name
            - account
            - paymentChannel
            - currency
            - country
          properties:
            name:
              type: string
              description: Full name of the designated recipient.
              example: NNOROM UZOMA CHUKWUDI
            account:
              type: object
              required:
                - bankName
                - sortCode
                - accountNumber
              properties:
                bankName:
                  type: string
                  example: FCMB
                sortCode:
                  type: string
                  example: '214'
                accountNumber:
                  type: string
                  example: '2483520014'
            paymentChannel:
              type: string
              description: Payment channel to use for delivery.
              enum:
                - BANK_TRANSFER
                - MOBILE_MONEY
              example: BANK_TRANSFER
            currency:
              type: string
              example: NGN
            country:
              type: string
              example: NG
    BulkPayoutResponseData:
      type: object
      properties:
        bulkReference:
          type: string
          description: A unique reference for the entire bulk payout request.
          example: 00a5478d-272a-4be0-8c77-d85be1ec5ea8
        status:
          type: string
          example: SUCCESS
        totalRequested:
          type: integer
          description: Total number of payout orders submitted.
          example: 2
        successfulCount:
          type: integer
          description: Number of orders successfully accepted for processing.
          example: 2
        failedCount:
          type: integer
          description: Number of orders that failed validation.
          example: 0
        totalAmount:
          type: number
          description: Total source amount for all successful orders.
          example: 350.5
        totalFees:
          type: number
          description: Total fees for all successful orders.
          example: 400
        orders:
          type: array
          description: >-
            List of processed payout orders. Successful orders return full
            payout details, while failed ones may return just a failureReason.
          items:
            oneOf:
              - $ref: '#/components/schemas/Payout'
              - type: object
                properties:
                  failureReason:
                    type: string
                    example: Recipient name mismatch
        createdAt:
          type: string
          format: date-time
          example: '2026-03-25T10:50:07.810009313Z'
    PayoutFailedResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message.
        status:
          type: string
          example: failed
      required:
        - message
        - status
    Payout:
      type: object
      properties:
        id:
          type: string
          example: c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx
        remark:
          type: string
          example: Testing
        invoice:
          type: object
          properties:
            fileName:
              type: string
              example: image.png
        reason:
          type: string
          example: Gift
        referenceNumber:
          type: string
          example: L2TEZEHNXXXXXX
        type:
          type: string
          example: SEND
        state:
          type: string
          example: COMPLETED
        quote:
          $ref: '#/components/schemas/CreateQuoteSuccessData'
        recipient:
          description: >-
            Details of the recipient. Structure mirrors
            `CreatePayoutRequest.recipient`.
          oneOf:
            - $ref: '#/components/schemas/NgnRecipient'
            - $ref: '#/components/schemas/UsdSwiftRecipient'
            - $ref: '#/components/schemas/EurRecipient'
            - $ref: '#/components/schemas/GbpRecipient'
            - $ref: '#/components/schemas/CadRecipient'
            - $ref: '#/components/schemas/SgdRecipient'
            - $ref: '#/components/schemas/KrwRecipient'
            - $ref: '#/components/schemas/ThbRecipient'
            - $ref: '#/components/schemas/MyrRecipient'
            - $ref: '#/components/schemas/VndRecipient'
            - $ref: '#/components/schemas/CnyRecipient'
        created:
          type: string
          format: date-time
        processed:
          type: string
          format: date-time
    CreateQuoteSuccessData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx
        paymentChannel:
          $ref: '#/components/schemas/PaymentChannel'
        source:
          type: object
          properties:
            currency:
              type: string
              example: NGN
            country:
              type: string
              example: NG
            amount:
              type: number
              example: 150000
        target:
          type: object
          properties:
            currency:
              type: string
              example: USD
            country:
              type: string
              example: US
            amount:
              type: number
              example: 81.97
        rate:
          type: number
          example: 1830
        fee:
          type: object
          properties:
            amount:
              type: number
              example: 0
            stampDuty:
              type: number
              example: 0
        rules:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
                example: LIMIT
              appliedCurrency:
                type: string
                example: USD
              appliedCountry:
                type: string
                example: US
              transaction:
                type: object
                properties:
                  minimum:
                    type: number
                    example: 1
                  maximum:
                    type: number
                    example: 20000000000000
              invoice:
                type: number
                example: 200000000000
        summary:
          type: object
          properties:
            total:
              type: number
              example: 150000
        settlementTime:
          type: string
          example: 1 hr
        settlement:
          type: string
          example: 1 hr
        quoteCurrency:
          type: string
          example: USD
        expiresInSeconds:
          type: integer
          example: 600
    NgnRecipient:
      title: NGN Payout
      description: Recipient details for a payout to Nigeria (NGN).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Full name of the recipient.
            account:
              type: object
              required:
                - accountNumber
                - bankCode
              properties:
                bankName:
                  type: string
                  description: The name of the Bank
                accountNumber:
                  type: string
                  example: '0010401234'
                  description: Recipient's account number
                sortCode:
                  type: string
                  description: The 3-digit NIP sort code.
                  example: '058'
    UsdSwiftRecipient:
      title: USD SWIFT Payout
      description: Recipient details for USD to USD SWIFT payout to the USA (USD).
      type: object
      required:
        - name
        - type
        - account
        - nickName
        - gender
        - occupation
      properties:
        paymentChannel:
          $ref: '#/components/schemas/PaymentChannel'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        country:
          $ref: '#/components/schemas/CountryCode'
        name:
          type: string
          description: Full name of the recipient.
        nickName:
          type: string
          description: Nickname or alias for the recipient.
        gender:
          type: string
          description: Gender of the recipient.
          enum:
            - M
            - F
        occupation:
          type: string
          description: Occupation or profession of the recipient.
          enum:
            - C-Suite executive / Board member
            - Employee
            - Entrepreneur / Business owner
            - Foreign worker
            - Foreign domestic worker
            - Home-maker
            - Middle management employee
            - Pilot
            - Professional
            - Senior management employee
            - Student
        type:
          type: string
          description: Recipient type; use `BUSINESS`
          enum:
            - BUSINESS
        account:
          type: object
          required:
            - accountNumber
            - swiftCode
            - bankName
          properties:
            bankName:
              type: string
              description: The name of the bank.
              example: DBS Bank Limited
            accountNumber:
              type: string
              description: The recipient's bank account number.
              example: '885406477269'
            swiftCode:
              type: string
              description: SWIFT/BIC code for international wire transfers.
              example: GTBINGLA
            sortCode:
              type: string
              description: Bank sort code.
              example: '02090'
            bankCity:
              type: string
              description: City where the bank is located.
              example: Atlanta
            intermediarySwiftCode:
              type: string
              description: >-
                The SWIFT/BIC code of the intermediary bank, required for some
                international USD transfers.
              example: CHASUS33XXX
    EurRecipient:
      title: EUR Payout
      description: Recipient details for a payout within Europe (EUR).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - firstName
            - lastName
            - type
            - address
          properties:
            type:
              $ref: '#/components/schemas/RecipientType'
              description: >-
                Recipient type; align with the actual customer profile (e.g.
                `BUSINESS`).
            firstName:
              type: string
              description: Recipient's first name.
            lastName:
              type: string
              description: Recipient's last name.
            address:
              type: string
              description: Mailing address of the recipient; required for EUR payouts.
            account:
              type: object
              required:
                - bankName
                - bankCountry
                - address
                - swiftCode
                - accountNumber
                - iban
              properties:
                bankName:
                  type: string
                  description: Name of the bank, e.g Adria Bank
                bankCountry:
                  type: string
                  description: The two-letter ISO country code of the recipient's bank.
                address:
                  type: string
                  description: The bank's physical address.
                swiftCode:
                  type: string
                  description: The SWIFT/BIC code for the bank.
                  example: '3456765'
                accountNumber:
                  type: string
                  description: The recipient's local bank account number.
                  example: '34567876545'
                iban:
                  type: string
                  description: The recipient's International Bank Account Number (IBAN).
                  example: '123454'
    GbpRecipient:
      title: GBP Payout
      description: Recipient details for a payout to the UK (GBP).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - firstName
            - lastName
            - type
          properties:
            firstName:
              type: string
              description: Recipient's first name.
            lastName:
              type: string
              description: Recipient's last name.
            type:
              $ref: '#/components/schemas/RecipientType'
              description: >-
                Recipient type; use `BUSINESS` for corporate payouts or
                `INDIVIDUAL` for consumers.
            account:
              type: object
              required:
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of the bank
                accountNumber:
                  type: string
                  description: The 8-digit UK bank account number.
                  example: '78355047'
                sortCode:
                  type: string
                  description: The 6-digit UK bank sort code.
                  example: '040004'
                address:
                  type: string
                  description: The bank's physical address.
    CadRecipient:
      title: CAD Payout
      description: Recipient details for a payout to Canada (CAD).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - address
          properties:
            name:
              type: string
              description: Full name of the recipient.
            address:
              type: string
              description: Mailing address of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
              description: >-
                Recipient type; optional for CAD payouts but recommended when
                sending to businesses.
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - transitNumber
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                  example: '2309912345'
                address:
                  type: string
                  description: The bank's physical address.
                sortCode:
                  type: string
                  description: Bank sort code.
                swiftCode:
                  type: string
                  description: SWIFT/BIC code, if applicable.
                transitNumber:
                  type: string
                  description: The 5-digit branch transit number.
                  example: '12345'
                institutionNumber:
                  type: string
                  description: The 3-digit financial institution number.
                  example: '004'
    SgdRecipient:
      title: SGD Payout
      description: Recipient details for a payout to Singapore (SGD).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
              description: Recipient type (INDIVIDUAL or BUSINESS).
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - swiftCode
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code / Sort code.
                swiftCode:
                  type: string
                  description: SWIFT/BIC code.
                bankCity:
                  type: string
                  description: City of the bank.
    KrwRecipient:
      title: KRW Payout
      description: Recipient details for a payout to South Korea (KRW).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
            - mobileNumber
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            mobileNumber:
              type: string
              description: Recipient mobile number.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 01462).
                bankCity:
                  type: string
                  description: City of the bank.
    ThbRecipient:
      title: THB Payout
      description: Recipient details for a payout to Thailand (THB).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            nickName:
              type: string
              description: Recipient nickname.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 00301).
                bankCity:
                  type: string
                  description: City of the bank.
    MyrRecipient:
      title: MYR Payout
      description: Recipient details for a payout to Malaysia (MYR).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            nickName:
              type: string
              description: Recipient nickname.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 00163).
    VndRecipient:
      title: VND Payout
      description: Recipient details for a payout to Vietnam (VND).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            nickName:
              type: string
              description: Recipient nickname.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 00205).
                bankCity:
                  type: string
                  description: City of the bank.
    CnyRecipient:
      title: CNY Payout
      description: Recipient details for a payout to China (CNY).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient. (Must be in Chinese characters)
            nickName:
              type: string
              description: Recipient nickname.
            occupation:
              type: string
              description: Occupation of the recipient.
            icNumber:
              type: string
              description: Identity card number of the recipient.
            relationship:
              type: string
              description: Relationship with the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            account:
              type: object
              required:
                - bankName
                - accountNumber
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code / Sort code.
                bankCity:
                  type: string
                  description: City of the bank.
            companyName:
              type: string
              description: Company name (if business).
            companyIdNumber:
              type: string
              description: Company identification number.
            gender:
              type: string
              description: Gender of the recipient.
              enum:
                - M
                - F
            nationality:
              type: string
              description: Nationality of the recipient (e.g., CN).
            itemCategory:
              type: string
              description: Category of items (e.g., PRD0003).
            itemType:
              type: string
              description: Type of item (e.g., Pipe Wrench).
            quantity:
              type: integer
              description: Quantity of items.
    PaymentChannel:
      type: string
      description: >-
        The channel through which the payment will be processed. For SWIFT
        transfers, use `SWIFT_CUSTOMER` (sender/customer bears all transfer
        charges), `SWIFT_SHARED` (charges split between sender and beneficiary),
        or `SWIFT_BENEFICIARY` (beneficiary bears all transfer charges).
      example: BANK_TRANSFER
      enum:
        - BANK_TRANSFER
        - INTERAC
        - SWIFT_CUSTOMER
        - SWIFT_SHARED
        - SWIFT_BENEFICIARY
        - MOBILE_MONEY
    BaseRecipient:
      type: object
      properties:
        paymentChannel:
          $ref: '#/components/schemas/PaymentChannel'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        country:
          $ref: '#/components/schemas/CountryCode'
        type:
          $ref: '#/components/schemas/RecipientType'
        stored:
          type: boolean
          description: Whether the recipient details should be saved in the address book.
          default: false
        address:
          type: string
          description: Full address of the recipient.
        account:
          type: object
          description: >-
            Currency-specific account details. Refer to the destination currency
            schema for the exact structure.
      required:
        - paymentChannel
        - currency
        - country
        - account
    CurrencyCode:
      type: string
      description: Currency code (ISO 4217).
      example: NGN
      enum:
        - NGN
        - USD
        - GBP
        - EUR
        - MWK
        - CAD
        - SGD
        - KRW
        - THB
        - MYR
        - VND
        - CNY
        - GHS
        - KES
        - RWF
        - XOF
        - ZAR
        - DKK
    CountryCode:
      type: string
      description: Country code (ISO 3166-1 alpha-2).
      example: NG
      enum:
        - NG
        - US
        - GB
        - DE
        - MW
        - CA
        - SG
        - KR
        - TH
        - MY
        - VN
        - CN
        - GH
        - CI
        - KE
        - RW
        - SN
        - ZA
        - AT
        - DK
    RecipientType:
      type: string
      description: The type of recipient.
      enum:
        - INDIVIDUAL
        - BUSINESS
    SourceOfFunds:
      type: string
      description: Code indicating the source of funds.
      enum:
        - D1
        - D2
        - D3
        - I1
        - I2
        - I3
        - I4
        - O1
        - O2
        - O3
        - O4
  responses:
    BulkPayoutCreatedSuccess:
      description: Bulk payout submitted successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: bulk payout queued
              status:
                type: string
                example: success
              data:
                $ref: '#/components/schemas/BulkPayoutResponseData'
          example:
            message: bulk order processed
            status: success
            data:
              bulkReference: 00a5478d-272a-4be0-8c77-d85be1ec5ea8
              status: SUCCESS
              totalRequested: 2
              successfulCount: 2
              failedCount: 0
              totalAmount: 350.5
              totalFees: 400
              orders:
                - id: 77250b66-9bb7-4d5a-a634-0b16659959fe
                  remark: payment 1
                  reason: Gift
                  referenceNumber: IE8YGOSWDG9HN
                  type: SEND
                  state: PENDING
                  quote:
                    id: 4be1d423-e2eb-437d-8223-16cfcb308195
                    paymentChannel: BANK_TRANSFER
                    source:
                      currency: NGN
                      country: NG
                      amount: 250.5
                    target:
                      currency: NGN
                      country: NG
                      amount: 250.5
                    rate: 1
                    fee:
                      amount: 200
                      stampDuty: 0
                    summary:
                      total: 450.5
                    settlement: 30 Mins
                    quoteCurrency: NGN
                  recipient:
                    name: NNOROM UZOMA CHUKWUDI
                    account:
                      bankName: FCMB
                      sortCode: '214'
                      accountNumber: '2483520014'
                    paymentChannel: BANK_TRANSFER
                    currency: NGN
                    country: NG
                  created: '2026-03-25T10:50:06.115252622Z'
                  processed: '2026-03-25T10:50:06.115252622Z'
                  bulkReference: 00a5478d-272a-4be0-8c77-d85be1ec5ea8
                - id: 17f755c3-f7fc-4ab5-b076-c3f3eb912155
                  remark: payment 2
                  reason: Gift
                  referenceNumber: AXZYRRN5PBDIO
                  type: SEND
                  state: PENDING
                  quote:
                    id: cf132126-af1c-4fd7-b924-427826a34b64
                    paymentChannel: BANK_TRANSFER
                    source:
                      currency: NGN
                      country: NG
                      amount: 100
                    target:
                      currency: NGN
                      country: NG
                      amount: 100
                    rate: 1
                    fee:
                      amount: 200
                      stampDuty: 0
                    summary:
                      total: 300
                    settlement: 30 Mins
                    quoteCurrency: NGN
                  recipient:
                    name: NNOROM UZOMA CHUKWUDI
                    account:
                      bankName: FCMB
                      sortCode: '214'
                      accountNumber: '2483520014'
                    paymentChannel: BANK_TRANSFER
                    currency: NGN
                    country: NG
                  created: '2026-03-25T10:50:07.309355914Z'
                  processed: '2026-03-25T10:50:07.309355914Z'
                  bulkReference: 00a5478d-272a-4be0-8c77-d85be1ec5ea8
              createdAt: '2026-03-25T10:50:07.810009313Z'
    PayoutBadRequest:
      description: >-
        Bad Request. The request could not be processed due to a client-side
        error, such as an expired quote or insufficient funds.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          examples:
            QuoteExpired:
              summary: Quote has expired
              value:
                message: Quote expired
                status: failed
            InsufficientBalance:
              summary: Insufficient wallet balance
              value:
                message: Insufficient Balance
                status: failed
            DuplicateQuoteId:
              summary: Duplicate quote ID in bulk order
              value:
                message: >-
                  Duplicate quote ID in bulk order:
                  537a5e91-3aa6-4e3f-9ed7-c16066ced503
                status: failed
    PayoutUnauthorized:
      description: Unauthorized. The provided API key is invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: Invalid API key
            status: failed
    PayoutForbidden:
      description: >-
        Forbidden. The request is not allowed because the source IP is not
        whitelisted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: 'Access denied: IP address not whitelisted'
            status: failed
    PayoutInternalServerError:
      description: Internal Server Error. The server failed to process the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: Server failed to process request.
            status: failed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````