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

# Initiate local bank transfer

> Initiate a local bank transfer via PesaLink. This endpoint currently supports paymentChannel=PESALINK only. The sender account is resolved from senderAccountNo and must map to an active payouts account class.



## OpenAPI

````yaml api-reference/openapi.json post /v1/local-bank-transfer
openapi: 3.1.0
info:
  title: Fingo Pay API
  description: >-
    Fingo Pay's unified payments API for M-Pesa C2B (STK Push), B2C
    disbursements, B2B transfers, bank transfers, account balances, and
    transactions.
  version: 1.0.0
servers:
  - url: https://api.fingopay.io
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Receive payments from customers
  - name: Payouts
    description: Send payments to recipients
  - name: Accounts
    description: Account balances and management
  - name: Transactions
    description: Transaction history and lookup
  - name: Verification
    description: Pre-transaction verification and lookup
  - name: Webhooks
    description: Webhook event notifications
paths:
  /v1/local-bank-transfer:
    post:
      tags:
        - Payouts
      summary: Initiate local bank transfer
      description: >-
        Initiate a local bank transfer via PesaLink. This endpoint currently
        supports paymentChannel=PESALINK only. The sender account is resolved
        from senderAccountNo and must map to an active payouts account class.
      operationId: localBankTransfer
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            Unique key to safely retry POST without duplicates. Required in live
            environment.
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomesticBankTransferRequest'
      responses:
        '202':
          description: Accepted — transfer will be processed asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransferAcceptedResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        '429':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    DomesticBankTransferRequest:
      type: object
      description: Request body for local bank transfers (PesaLink).
      properties:
        merchantTransactionId:
          type: string
          description: >-
            Merchant-side reference used for reconciliation. Accepts 1-64
            characters (letters, numbers, dot, underscore, or hyphen).
          example: bank_tx_48291
          pattern: ^[A-Za-z0-9._-]{1,64}$
          minLength: 1
          maxLength: 64
        senderAccountNo:
          type: string
          description: >-
            Sender payout account number funding the transfer. The account
            number is resolved to an account and validated against its account
            class.
          example: ACC-123456
        senderAddress:
          type: string
          description: Registered sender address.
          example: 12 Riverside Drive, Nairobi
        beneficiaryBankCode:
          type: string
          description: Destination bank code.
          example: '07000'
        beneficiaryBankName:
          type: string
          description: Destination bank name.
          example: Equity Bank
        beneficiaryBranchCode:
          type: string
          description: Optional branch code. Provide an empty string if not applicable.
          example: '00123'
        beneficiaryAccountId:
          type: string
          description: Destination account number.
          example: '0012345678901'
        beneficiaryAccountCcy:
          type: string
          description: Destination account currency (ISO 4217).
          example: KES
        beneficiaryName:
          type: string
          description: Destination account holder name.
          example: Jane Wambui
        amount:
          type: integer
          description: >-
            Amount in smallest currency unit (cents). Range 1-100,000,000 (KES
            0.01-1,000,000.00).
          example: 25000000
          minimum: 1
          maximum: 100000000
        narration:
          type: string
          description: Transfer narration. Maximum 140 characters.
          example: Supplier payment
          maxLength: 140
        paymentChannel:
          type: string
          description: Payment rail used for the transfer. Only PESALINK is supported.
          enum:
            - PESALINK
          example: PESALINK
        paymentPurposeId:
          type: string
          description: Optional payment purpose identifier.
          example: OTHR
      required:
        - merchantTransactionId
        - senderAccountNo
        - senderAddress
        - beneficiaryBankCode
        - beneficiaryBankName
        - beneficiaryAccountId
        - beneficiaryAccountCcy
        - beneficiaryName
        - amount
        - narration
        - paymentChannel
      additionalProperties: false
    BankTransferAcceptedResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Bank transfer initiated successfully
        data:
          type: object
          properties:
            merchantTransactionId:
              type: string
              example: bank_tx_48291
            transactionId:
              type: string
              example: txn_01j7bankdom
          required:
            - merchantTransactionId
            - transactionId
      required:
        - status
        - message
        - data
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - rate_limit_error
                - api_error
                - idempotency_error
                - not_found_error
                - conflict_error
              description: Error category
            code:
              type: string
              enum:
                - missing_parameter
                - invalid_parameter
                - unauthorized
                - forbidden
                - too_many_requests
                - internal_error
                - duplicate
                - resource_not_found
                - missing_header
                - validation_error
              description: Specific error code
            message:
              type: string
              description: Human-readable error message
            param:
              type:
                - string
                - 'null'
              description: The parameter that caused the error, if applicable
            requestId:
              type: string
              description: Request ID for support reference
          required:
            - type
            - code
            - message
      required:
        - error
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use your API key as a Bearer token. Example: Authorization: Bearer
        sk_live_...

````