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

# Create Fiat Payout

> Processes a withdrawal request from a specified account to a destination bank account.



## OpenAPI

````yaml POST /partners/payouts
openapi: 3.1.0
info:
  title: HyperRail
  description: HyperRail documentation
  license:
    name: MIT
  version: 1.0.0
servers:
  - description: Live server
    url: https://api.hyperrails.io/api/v1
security:
  - bearerAuth: []
paths:
  /partners/payouts:
    post:
      tags:
        - Withdrawals
      summary: Initiate Bank Withdrawal
      description: >-
        Processes a withdrawal request from a specified account to a destination
        bank account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
            examples:
              ngnPayout:
                summary: Nigerian Naira payout
                value:
                  reference: payout-001
                  amount: 10000
                  currency: NGN
                  destination:
                    accountNumber: '0123456789'
                    accountName: Jane Doe
                    bankCode: '058'
                    branchCode: '001'
                  narration: Vendor payout April
              ghsPayout:
                summary: Ghana Cedis payout
                value:
                  reference: payout-002
                  amount: 50000
                  currency: GHS
                  destination:
                    accountNumber: '0987654321'
                    accountName: John Smith
                    bankCode: '030100'
                    branchCode: '001'
                  narration: Salary payment
      responses:
        '200':
          description: Withdrawal initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
              example:
                reference: payout-001
                hyperrailReference: HPR-TRSF-3a1b2c3d4e5f
                amount: 10000
                fee: 50
                currency: NGN
                destination:
                  accountNumber: '0123456789'
                  accountName: Jane Doe
                  bankCode: '058'
                  branchCode: '001'
                  bankName: GTBank
                narration: Vendor payout April
                status: processing
                createdAt: '2026-04-24T10:30:00Z'
                estimatedCompletionAt: '2026-04-24T10:35:00Z'
        '400':
          description: Bad request - Invalid withdrawal details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficientBalance:
                  summary: Insufficient balance
                  value:
                    code: INSUFFICIENT_BALANCE
                    message: >-
                      Account balance (5000 NGN) is less than requested amount
                      (10000 NGN) plus fees (50 NGN)
                invalidBankCode:
                  summary: Invalid bank code
                  value:
                    code: INVALID_BANK_CODE
                    message: Bank code '999' is not a valid Nigerian bank code
                invalidAccountNumber:
                  summary: Invalid account number
                  value:
                    code: INVALID_ACCOUNT_NUMBER
                    message: Account number must be 10 digits for Nigerian banks
                duplicateReference:
                  summary: Duplicate reference
                  value:
                    code: DUPLICATE_REFERENCE
                    message: Payout with reference 'payout-001' already exists
                accountNameMismatch:
                  summary: Account name verification failed
                  value:
                    code: NAME_MISMATCH
                    message: >-
                      Provided account name 'Jane Doe' does not match bank
                      records 'Jane D. Doe'
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity - Amount below minimum threshold
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: AMOUNT_TOO_LOW
                message: Minimum withdrawal amount is 100 NGN
        '503':
          description: Service unavailable - Bank service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: SERVICE_UNAVAILABLE
components:
  schemas:
    WithdrawalRequest:
      type: object
      required:
        - reference
        - amount
        - currency
        - destination
      properties:
        reference:
          type: string
          description: >-
            Unique idempotency reference for this payout. Used to prevent
            duplicate transfers.
          example: payout-li
          minLength: 1
          maxLength: 100
        amount:
          type: number
          example: 100
        currency:
          type: string
          description: Currency code for the transfer
          example: NGN
        destination:
          $ref: '#/components/schemas/BankDestination'
        narration:
          type: string
          example: ..
    WithdrawalResponse:
      type: object
      properties:
        amount:
          type: number
          format: double
          example: 100
        currency:
          type: string
          example: NGN
        destination:
          type: object
          properties:
            accountNumber:
              type: string
              example: '8083233781'
            accountName:
              type: string
              example: John Doe
            bankCode:
              type: string
              example: SPB-17646
        providerStatus:
          type: string
          description: Status of the transaction with the upstream provider.
          example: PROCESSING
        reference:
          type: string
          description: Unique transaction reference.
          example: TRF-a633516c526a40c4b2ebc6e3c249c5f5
        status:
          type: string
          description: Internal processing status.
          example: PROCESSING
    Error:
      required:
        - code
        - message
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: INVALID_CURRENCY
        message:
          type: string
          description: Error message
          example: 'Invalid source currency. Supported: NGN, GHS'
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    BankDestination:
      type: object
      required:
        - accountNumber
        - accountName
        - bankCode
      properties:
        accountNumber:
          type: string
          description: Recipient bank account number (10 digits for Nigerian banks)
          example: '0123456789'
          pattern: ^[0-9]{10}$
        accountName:
          type: string
          description: Account holder name (must match bank records)
          example: Jane Doe
          minLength: 2
          maxLength: 100
        bankCode:
          type: string
          description: Bank code (3 digits for Nigerian banks, 6 digits for Ghanaian banks)
          example: '058'
        branchCode:
          type: string
          description: Bank branch code (optional for most Nigerian banks)
          example: '001'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key authentication using Bearer token

````