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

# Verify Account

> Resolves the account holder name when available. For some fiat corridors (e.g. KES M-Pesa), `data` may be `"OK"` when the account is valid but no display name is returned — supply your own `accountName` on the order in that case.


Verify a bank or mobile money account before creating an order. Currency is determined by the **institution** code (no separate `currency` field on this endpoint).

## Mobile money identifiers

For institutions with type **mobile\_money**, the API **normalizes** `accountIdentifier` before calling providers:

* Strips `+` and non-digit characters
* Removes a leading domestic `0` and adds the country dial code when missing

| Fiat | Dial code |
| ---- | --------- |
| KES  | 254       |
| UGX  | 256       |
| TZS  | 255       |
| GHS  | 233       |
| MWK  | 265       |

**KES M-Pesa example:** `0712345678`, `+254712345678`, and `254712345678` all normalize to `254712345678`.

You can send local or international MSISDN format; normalization also runs on order create for the same institution types.

## KES Till and Paybill

Phone normalization is **not** applied when:

* **`metadata`** indicates Till or Paybill (same shape as [recipient metadata](/implementation-guides/sender-api-integration) on order create), or
* The identifier looks like Paybill (`businessNumber|reference`) or Till (fewer than 9 digits)

Pass optional **`metadata`** on the verify request for Till/Paybill validation.

## Response `data`

* A **real name** (e.g. `"JOHN DOE"`) — use that exact string as `accountName` on the order.
* **`"OK"`** — account treated as valid but name lookup is unavailable for that corridor (common for some KES/GHS/UGX/MWK mobile flows). Provide your own `accountName` on the order.

The same checks run again when you create an order; calling verify first improves checkout UX.


## OpenAPI

````yaml openapi-v2.yaml POST /verify-account
openapi: 3.0.3
info:
  title: Paycrest Aggregator API
  version: 1.0.0
  description: >
    OpenAPI schema for the Paycrest Aggregator API. This covers sender,
    provider, and general endpoints.
servers:
  - url: https://api.paycrest.io/v2
security: []
tags:
  - name: Sender
    description: Endpoints for senders to create and manage payment orders
  - name: Provider
    description: Endpoints for providers to manage and fulfill orders
  - name: General
    description: General protocol and utility endpoints
paths:
  /verify-account:
    post:
      tags:
        - General
      summary: Verify account
      description: >
        Resolves the account holder name when available. For some fiat corridors
        (e.g. KES M-Pesa), `data` may be `"OK"` when the account is valid but no
        display name is returned — supply your own `accountName` on the order in
        that case.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyAccountRequest'
            examples:
              ngnBank:
                summary: NGN bank account
                value:
                  institution: GTBINGLA
                  accountIdentifier: '0123456789'
              kesMobile:
                summary: KES M-Pesa (local MSISDN normalized server-side)
                value:
                  institution: SAFAKEPC
                  accountIdentifier: '0712345678'
              kesTill:
                summary: KES Till (metadata skips phone normalization)
                value:
                  institution: SAFAKEPC
                  accountIdentifier: '123456'
                  metadata:
                    channel: Till
      responses:
        '200':
          description: Account verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Account name was fetched successfully
                  data:
                    type: string
                    description: >-
                      Resolved account name, or `"OK"` when valid but name
                      lookup is unavailable
                    example: JOHN DOE
        '400':
          description: Bad request
        '502':
          description: Bad gateway
        '503':
          description: Service unavailable
      servers:
        - url: https://api.paycrest.io/v2
components:
  schemas:
    VerifyAccountRequest:
      type: object
      required:
        - institution
        - accountIdentifier
      properties:
        institution:
          type: string
          description: >-
            Institution code (SWIFT code or custom PayCrest code ending with
            'PC'). See [Code Standards](/resources/code-standards) for details.
        accountIdentifier:
          type: string
          description: >
            Bank account number, mobile wallet MSISDN, Till/Paybill identifier,
            or other account identifier.


            For **mobile_money** institutions, the API normalizes phone numbers
            before verification: strips `+`, removes a leading domestic `0`, and
            adds the country dial code when missing (KES 254, UGX 256, TZS 255,
            GHS 233, MWK 265). Examples for KES M-Pesa — `0712345678`,
            `+254712345678`, and `254712345678` all normalize to `254712345678`.


            KES Till/Paybill identifiers are not normalized when `metadata`
            indicates Till/Paybill, or when the value looks like Paybill
            (`business|reference`) or Till (fewer than 9 digits).
        metadata:
          type: object
          additionalProperties: true
          description: >
            Optional. Used for KES Till/Paybill verify so phone normalization is
            not applied. Same semantics as recipient `metadata` on order create
            (e.g. `channel` Till or Paybill, `businessNumber`).

````