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

# Validate Customer Identifier

> Verify customer account numbers, electricity meter numbers, smartcard IUCs, and student matric numbers.

Validates a customer's recipient identifier before initiating a payment. This verifies that the recipient account exists, belongs to the correct tariff, and returns customer name and outstanding balances.

### Common Validation Use Cases

1. **Electricity Meters**: Verify prepaid or postpaid meter number against DisCo databases before vending energy units.
2. **Cable TV Smartcards**: Validate IUC/Smartcard numbers against MultiChoice/StarTimes to retrieve customer name, current bouquet, and due date.
3. **Education / Exam Portals**: Validate student matriculation or registration numbers for tuition and exam fee settlements.
4. **Betting Accounts**: Confirm player user ID before wallet funding.


## OpenAPI

````yaml openapi.json POST /bill-payment/validate-customer
openapi: 3.0.3
info:
  title: Handle Merchant Payment Gateway API
  description: >-
    Developer API specification for accepting cardless, instant
    Account-to-Account (A2A) payments via Handle.
  version: 1.0.0
  contact:
    name: Handle Developer Support
    email: support@handle.ng
    url: https://handle.ng
servers:
  - url: https://api-local.handle.ng/api/v1
    description: Local Development (SSL)
  - url: https://api.handle.ng/api/v1
    description: Production Live Gateway
security:
  - BearerAuth: []
paths:
  /bill-payment/validate-customer:
    post:
      tags:
        - VAS & Bill Payments
      summary: Validate Customer Identifier
      description: >-
        Verify meter numbers, smartcards, candidate IDs, or phone numbers
        against upstream providers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - category
                - billerCode
                - recipientId
              properties:
                category:
                  type: string
                  enum:
                    - GOVERNMENT
                    - ELECTRICITY
                    - AIRTIME
                    - DATA
                    - INTERNET
                    - CABLE_TV
                    - UTILITIES
                    - EDUCATION
                    - FLIGHTS
                    - BETTING
                    - GAMING
                    - SOLAR
                    - TRANSPORT
                    - ESIM
                    - TAXES
                    - HOSPITALS
                    - INSURANCE
                    - RELIGIOUS
                    - ASSOCIATIONS
                    - FINANCIAL_SERVICES
                    - CREDIT_LOANS
                    - MICRO_PENSIONS
                    - INVOICE
                    - GIFT_CARDS
                    - SHOPPING
                    - FOOD_DINING
                    - LIFESTYLE_BEAUTY
                    - HOME_LIVING
                  default: GOVERNMENT
                  example: GOVERNMENT
                billerCode:
                  type: string
                  default: FRSC
                  example: FRSC
                recipientId:
                  type: string
                  default: KJA-829-AA
                  example: KJA-829-AA
                params:
                  type: object
                  description: >-
                    Optional parameters (e.g. billPaymentProductId for
                    Government/Remita, or meterType for Electricity)
                  properties:
                    billPaymentProductId:
                      type: string
                      example: NOTICE_OF_OFFENCE
                    meterType:
                      type: string
                      enum:
                        - prepaid
                        - postpaid
      responses:
        '200':
          description: Customer verification details
          content:
            application/json:
              schema:
                type: object
                properties:
                  isValid:
                    type: boolean
                    example: true
                  customerName:
                    type: string
                    example: ADEWALE AYODEJI PETERS
                  address:
                    type: string
                    example: 14 ADEOLA ODEKU STREET, VICTORIA ISLAND, LAGOS
                  meterNumber:
                    type: string
                    example: '0219927013063'
                  billerCode:
                    type: string
                    example: AEDC
                  outstandingAmount:
                    type: number
                    example: 0
                  metadata:
                    type: object
                    properties:
                      accountType:
                        type: string
                        example: PREPAID
                      district:
                        type: string
                        example: WUSE
                      tariffCode:
                        type: string
                        example: A1-R2
              example:
                isValid: true
                customerName: ADEWALE AYODEJI PETERS
                address: 14 ADEOLA ODEKU STREET, VICTORIA ISLAND, LAGOS
                meterNumber: '0219927013063'
                billerCode: AEDC
                outstandingAmount: 0
                metadata:
                  accountType: PREPAID
                  district: WUSE
                  tariffCode: A1-R2
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Supply your secret API key (e.g. `sk_live_...` or `sk_test_...`) in the
        Authorization header.
      x-default: sk_test_handle_master_key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.