> ## 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.

# Validate account name

> Validate a bank account, M-Pesa number, or till/paybill before initiating a payout. Returns the registered account holder name and account status. Use this to confirm the recipient identity before sending funds. Currently only Kenya (KE) is supported.



## OpenAPI

````yaml api-reference/openapi.json get /v1/account-name-validation
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/account-name-validation:
    get:
      tags:
        - Verification
      summary: Validate account name
      description: >-
        Validate a bank account, M-Pesa number, or till/paybill before
        initiating a payout. Returns the registered account holder name and
        account status. Use this to confirm the recipient identity before
        sending funds. Currently only Kenya (KE) is supported.
      operationId: validateAccountName
      parameters:
        - name: country
          in: query
          required: true
          description: >-
            Country code (ISO 3166-1 alpha-2). Currently only `KE` (Kenya) is
            supported.
          schema:
            type: string
            enum:
              - KE
            example: KE
        - name: accountId
          in: query
          required: true
          description: >-
            The account identifier to validate. For M-Pesa this is the phone
            number (e.g. `254712345678`), for bank accounts this is the account
            number, for tills/paybills this is the business number.
          schema:
            type: string
            example: '0112345678900'
        - name: accountType
          in: query
          required: true
          description: The type of account to validate.
          schema:
            type: string
            enum:
              - choice_bank
              - mpesa_paybill
              - mpesa_till
              - mpesa_mobile
              - pesalink
        - name: bankCode
          in: query
          required: false
          description: >-
            Bank code from the `/v1/local-bank-codes` endpoint. Required when
            `accountType` is `pesalink`.
          schema:
            type: string
            example: '07000'
      responses:
        '200':
          description: >-
            Validation result returned. Check the `found` field to determine
            whether the account exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNameValidationResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    AccountNameValidationResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Account validated
        data:
          $ref: '#/components/schemas/AccountValidationResult'
      required:
        - status
        - message
        - data
    AccountValidationResult:
      type: object
      description: >-
        Result of account name validation. When found is false, the account does
        not exist or could not be validated.
      properties:
        found:
          type: boolean
          description: Whether the account was found and validated successfully
          example: true
        accountId:
          type: string
          description: The account identifier that was validated
          example: '0112345678900'
        accountName:
          type: string
          description: Registered account holder name. Empty string when found is false.
          example: Jane Wambui
        accountType:
          type: string
          description: The account type that was validated
          enum:
            - choice_bank
            - mpesa_paybill
            - mpesa_till
            - mpesa_mobile
            - pesalink
          example: pesalink
        freezeStatus:
          type: string
          description: >-
            Account freeze status from the bank. '0' indicates normal. Empty
            when found is false.
          example: '0'
        restrictStatus:
          type: string
          description: >-
            Account restriction status from the bank. '0' indicates normal.
            Empty when found is false.
          example: '0'
        errorMessage:
          type: string
          description: Error reason when found is false. Absent when found is true.
          example: Account does not exist.
      required:
        - found
        - accountId
        - accountName
        - accountType
        - freezeStatus
        - restrictStatus
    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_...

````