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

# Name Lookup

> Checks the phone number and network already on file for the given customer_key against whichever provider (pawaPay or Onafriq) would actually handle a payout to them, reducing the risk of sending funds to the wrong recipient.

Validate the mobile money account name on file for a customer before sending a payout to them, reducing the risk of sending funds to the wrong recipient. The phone number and network checked are always the ones already on file for the given `customer_key` — you cannot pass arbitrary values. Currently supported for corridors handled by pawaPay or Onafriq; unsupported corridors return `status: "UNSUPPORTED"` rather than an error.


## OpenAPI

````yaml POST /api/v3/name-lookup
openapi: 3.0.0
info:
  title: KOTANI PAY API PLATFORM
  description: ''
  version: '3.0'
  contact: {}
servers:
  - url: https://sandbox-api.kotanipay.com
security: []
tags: []
paths:
  /api/v3/name-lookup:
    post:
      tags:
        - NAME LOOKUP
      summary: Validate a phone number against a customer name before payout
      description: >-
        Checks the phone number and network already on file for the given
        customer_key against whichever provider (pawaPay or Onafriq) would
        actually handle a payout to them, reducing the risk of sending funds to
        the wrong recipient.
      operationId: NameLookupController_lookup_api/v3
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameLookupRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Name lookup completed.
                  data:
                    $ref: 5c9d614e-edb0-4234-bb4e-f4dd1d558bf1
                    type: object
        '400':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Bad Request
                  data:
                    type: object
                    example: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Invalid API Key
                  data:
                    type: object
                    example: {}
      security:
        - JWT: []
components:
  schemas:
    NameLookupRequestDto:
      type: object
      properties:
        walletId:
          type: string
          description: >-
            The fiat wallet the payout would be debited from — used to resolve
            which provider would actually handle it.
          example: 5f9b2c7b9c9d6b0017b4e6b1
        customer_key:
          type: string
          description: >-
            Customer key of an existing mobile-money customer. The phone number,
            network, and name validated are always the ones already on file for
            this customer — not arbitrary values — so the result reflects who
            would actually receive this payout.
          example: customer-key-123
      required:
        - walletId
        - customer_key
  securitySchemes:
    JWT:
      scheme: bearer
      bearerFormat: JWT
      type: http

````