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

# Get or List Customers

> This endpoint is used to either retrieve a specific customer or list multiple customers depending on the `operation` parameter.

**For Get A Customer (`operation=GET`):**
- Endpoint URL Example `https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=GET&customer_reference=VirtualAccount1`.
- Requires the `customer_reference` parameter.
- Retrieves the specific customer's verification progress and virtual account info.

**For List Customers (`operation=LIST`):**
- Endpoint URL example `https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=LIST&page_number=1&page_size=10`m.
- Requires `page_number` and `page_size`.
- Retrieves a paginated list of customers.

**Notes:**
- Kindly note that IP Address whitelisting is required for these requests.



## OpenAPI

````yaml /openapi.json get /payaza-account/api/v1/mainaccounts/merchant/customer
openapi: 3.0.1
info:
  title: Payaza Documentation
  version: 2.0.0
  description: >-
    API reference for processing payments using Card, Bank Transfer, USSD, and
    QR Code methods.
servers:
  - url: https://api.payaza.africa/live
    description: >-
      The /live path is fixed and test transactions are performed by using the
      Test API Key with or without the X-TenantID header set to test.
security:
  - ApiKeyAuth: []
  - TenantID: []
  - ProductID: []
tags:
  - name: Transfers
    description: >-
      Transfers are transactions made from your Payaza account to beneficiaries.
      Merchants can instantly transfer funds from their available balance. For
      every transfer, you need to specify the amount and the beneficiary’s
      details. You become eligible to make transfers after you have been
      verified. (you sign up, finish account activation and KYC verification).
  - name: Payaza Account
    description: >-
      This is our internal account that can be used to make payouts to other
      bank accounts, in single or in bulk. The Payaza account can also be used
      to receive settlements. It can also be used to track the transfer status
      of your transactions and check your balance instantly
  - name: Sub Accounts
    description: >-
      This enables you to establish Sub Payaza accounts for your customers. Each
      sub-account comes with an assigned static virtual account, facilitating
      direct funding for individual accounts. Furthermore, the Main Payaza
      account can directly initiate funding for each sub-account. These
      sub-accounts serve the purpose of managing unique account positions or
      balances and facilitating disbursements from these positions to specified
      beneficiaries.
  - name: Apple Pay and Google Pay
    description: >-
      Apple Pay and Google Pay give your customers a fast, familiar, and secure
      way to complete payments. Our APIs provide a gateway to provide these
      services to your users for a smooth payment experience.
  - name: Virtual Accounts
    description: >-
      Virtual Accounts are bank accounts that are created for a specific purpose
      and last for specified durations. Virtual accounts are issued by Payaza’s
      partner banks. Our virtual account APIs can be used to create virtual
      accounts and perform other tasks relevant to virtual accounts. Virtual
      accounts are created to foster easy payment collections for your business
      and platform. 

      Static/Reserved Account: This virtual account is created by the merchant
      and remains valid indefinitely. It can be used multiple times and does not
      expire. 

      Dynamic Account: This virtual account is generated for a specific
      transaction or purpose. Please note that dynamic virtual account remains
      valid for a temporary period of time or until a payment of the specified
      amount is received. Upon expiry, a merchant can generate another one for a
      different purpose.
  - name: Card Collection
    description: >-
      The Card Collection APIs can be used to make card transactions, refund
      transactions that have been performed, check the status of a transaction
      and so much more.
  - name: Refunds And Chargebacks
    description: >-
      The Refunds and Chargeback APIs are used to initiate refunds, view your
      refund and chargeback history and so much more.
  - name: Branches
    description: The Branch API are used to fetch branches that belong to a business.
  - name: Auth-Capture-Void
    description: >-
      The Auth-Capture-Void APIs provide a two-phase payment process where
      transactions are first authorized, then captured or voided. This allows
      merchants to hold funds and complete the transaction in the future.
  - name: Momo, XOF and ZAR Collections
    description: APIs for MoMo, ZAR and XOF collections.
  - name: Check Transaction Status(Merchant Reference)
    description: >-
      This endpoint is used to check the transaction status of a transaction
      using the Merchant Reference..
  - name: Payment Links
    description: The Payment Links API allows you to create and manage your payment links.
  - name: Split Settlements
    description: >-
      The Split Settlements API allows you to create and manage split
      settlements.
paths:
  /payaza-account/api/v1/mainaccounts/merchant/customer:
    get:
      tags:
        - vIBANS
      summary: Get or List Customers
      description: >-
        This endpoint is used to either retrieve a specific customer or list
        multiple customers depending on the `operation` parameter.


        **For Get A Customer (`operation=GET`):**

        - Endpoint URL Example
        `https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=GET&customer_reference=VirtualAccount1`.

        - Requires the `customer_reference` parameter.

        - Retrieves the specific customer's verification progress and virtual
        account info.


        **For List Customers (`operation=LIST`):**

        - Endpoint URL example
        `https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=LIST&page_number=1&page_size=10`m.

        - Requires `page_number` and `page_size`.

        - Retrieves a paginated list of customers.


        **Notes:**

        - Kindly note that IP Address whitelisting is required for these
        requests.
      parameters:
        - name: operation
          in: query
          required: true
          schema:
            type: string
            enum:
              - GET
              - LIST
            default: LIST
          description: >-
            Specifies the operation to perform. Select `GET` for a single
            customer or `LIST` for a paginated list.
        - name: customer_reference
          in: query
          required: false
          schema:
            type: string
            example: account_001
          description: >-
            Required if `operation=GET`. The unique customer reference supplied
            during customer creation.
        - name: page_number
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Required if `operation=LIST`. The page number to retrieve.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 10
          description: Required if `operation=LIST`. The number of records per page.
      responses:
        '200':
          description: Request Successful
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/getACustomerResponse'
                  - $ref: '#/components/schemas/listCustomersResponse'
              examples:
                Get A Customer Response:
                  summary: Get A Customer Response
                  value:
                    message: Customer retrieved
                    status: true
                    retry_count: 0
                    data:
                      id: 15
                      customer_reference: account_001
                      type: individual
                      name: John Doe
                      email: johndoe@company.com
                      phone: '+2348012345679'
                      country_code: NG
                      address:
                        street: 123 Main Street
                        street2: null
                        city: Lagos
                        subdivision: Lagos
                        postal_code: '100001'
                        country_code: NG
                      status: UNDER_REVIEW
                      requirements: []
                      registrations:
                        - provider_reference: 01a1e843-b041-7384-8649-430c0e7abc30
                          provisioning: ON_REQUEST
                          status: UNDER_REVIEW
                          programs:
                            - program: null
                              currencies:
                                - USD
                              status: UNDER_REVIEW
                              provider_status: PENDING
                              requirements: []
                              updated_at: '2026-11-17T06:48:34.357002564Z'
                          documents:
                            - type: IDENTITY_DOCUMENT
                              side: FRONT
                              person_reference: null
                              file_name: 1774864420319-pocketapp.png
                              status: UPLOADED
                              message: null
                              sha256: >-
                                d8a2a85c3fe1d410f9459b70caf12e258c49b9f3b1cc477b9eaae74e7985380c
                              size: 2889
                              provider_reference: 1179696a-b405-4255-aeb8-831c6d981825
                              uploaded_at: '2026-11-17T06:48:33.395663472Z'
                          last_error: null
                          refreshed_at: '2026-11-17T06:48:34.357003Z'
                          created_at: '2026-11-17T06:48:16.161453Z'
                      accounts:
                        - id: 8
                          account_reference: primary
                          customer_id: 15
                          customer_reference: account_001
                          program: null
                          provisioning: ON_REQUEST
                          provider_reference: null
                          currency: USD
                          country_code: null
                          network: null
                          label: null
                          status: PENDING
                          provider_status: null
                          holder_name: null
                          payment_instructions: []
                          metadata: {}
                          message: Waiting for the customer to become ACTIVE
                          refreshed_at: null
                          created_at: '2026-11-17T06:48:16.262954Z'
                          updated_at: '2026-11-17T06:48:16.262954Z'
                      business: null
                      individual:
                        first_name: John
                        middle_name: null
                        last_name: Doe
                        nationality: null
                      identifications:
                        - type: PASSPORT
                          issuing_country: NG
                          last4: '1511'
                          expires_on: '2030-01-15'
                        - type: TIN
                          issuing_country: NG
                          last4: '1511'
                          expires_on: null
                      associated_persons: []
                      metadata: {}
                      created_at: '2026-11-17T06:48:15.891065Z'
                      updated_at: '2026-11-17T06:48:32.137453Z'
                List Customers Response:
                  summary: List Customers Response
                  value:
                    message: Customers retrieved
                    status: true
                    retry_count: 0
                    data:
                      data:
                        - id: 3
                          customer_reference: payout-sender
                          type: business
                          status: ACTION_REQUIRED
                        - id: 14
                          customer_reference: Customer_reference_012
                          type: individual
                          status: ACTIVE
                        - id: 15
                          customer_reference: payaza_account_001
                          type: individual
                          status: UNDER_REVIEW
                      page: 1
                      size: 20
                      total: 3
        '400':
          description: >-
            The Page Size must be between 1 and 100. Please adjust the page_size
            parameter accordingly.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: VALIDATION_ERROR
                  message:
                    type: string
                    example: page_size must be between 1 and 100
                  status:
                    type: boolean
                    example: false
                  retry_count:
                    type: integer
                    example: 0
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: VALIDATION_ERROR
                    message: page_size must be between 1 and 100
                    status: false
                    retry_count: 0
      security:
        - ApiKeyAuth:
            - Payaza {{Public API Key In Base64}}
          TenantID:
            - test or live
components:
  schemas:
    getACustomerResponse:
      title: Get A Customer Response
      type: object
      properties:
        message:
          type: string
          description: >-
            A descriptive message regarding the overall outcome of the
            operation.
          example: Customer retrieved
        status:
          type: boolean
          description: This indicates whether the request was successful.
          example: true
        retry_count:
          type: integer
          description: The number of retries attempted during processing.
          example: 0
        data:
          type: object
          description: The payload containing the retrieved customer details.
          properties:
            id:
              type: integer
              description: The unique internal identifier for the customer record.
              example: 15
            customer_reference:
              type: string
              description: The merchant's unique customer reference..
              example: account_001
            type:
              type: string
              description: The type of customer (e.g., individual, business).
              example: individual
            name:
              type: string
              description: The full name of the customer.
              example: John Doe
            email:
              type: string
              format: email
              description: The customer's email address.
              example: johndoe@company.com
            phone:
              type: string
              description: The customer's phone number.
              example: '+2348012345679'
            country_code:
              type: string
              description: The 2-letter ISO country code of the customer.
              example: NG
            address:
              type: object
              description: The customer's physical address details.
              properties:
                street:
                  type: string
                  example: 123 Main Street
                street2:
                  type: string
                  nullable: true
                  example: null
                city:
                  type: string
                  example: Lagos
                subdivision:
                  type: string
                  example: Lagos
                postal_code:
                  type: string
                  example: '100001'
                country_code:
                  type: string
                  example: NG
            status:
              type: string
              description: The overall KYC or account status of the customer.
              example: UNDER_REVIEW
            registrations:
              type: array
              description: >-
                The customer registration and provider verification
                information..
              items:
                type: object
                properties:
                  provider_reference:
                    type: string
                    example: 01a1e843-b041-7384-8649-430c0e7abc30
                  provisioning:
                    type: string
                    example: ON_REQUEST
                  status:
                    type: string
                    example: UNDER_REVIEW
                  programs:
                    type: array
                    items:
                      type: object
                      properties:
                        program:
                          type: string
                          nullable: true
                          example: null
                        currencies:
                          type: array
                          items:
                            type: string
                          example:
                            - USD
                        status:
                          type: string
                          example: UNDER_REVIEW
                        provider_status:
                          type: string
                          example: PENDING
                        requirements:
                          type: array
                          items:
                            type: object
                          example: []
                        updated_at:
                          type: string
                          format: date-time
                          example: '2026-11-17T06:48:34.357002564Z'
                  documents:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: IDENTITY_DOCUMENT
                        side:
                          type: string
                          example: FRONT
                        person_reference:
                          type: string
                          nullable: true
                          example: null
                        file_name:
                          type: string
                          example: 1774864420319-pocketapp.png
                        status:
                          type: string
                          example: UPLOADED
                        message:
                          type: string
                          nullable: true
                          example: null
                        sha256:
                          type: string
                          example: >-
                            d8a2a85c3fe1d410f9459b70caf12e258c49b9f3b1cc477b9eaae74e7985380c
                        size:
                          type: integer
                          example: 2889
                        provider_reference:
                          type: string
                          example: 1179696a-b405-4255-aeb8-831c6d981825
                        uploaded_at:
                          type: string
                          format: date-time
                          example: '2026-11-17T06:48:33.395663472Z'
                  last_error:
                    type: string
                    nullable: true
                    example: null
                  refreshed_at:
                    type: string
                    format: date-time
                    example: '2026-11-17T06:48:34.357003Z'
                  created_at:
                    type: string
                    format: date-time
                    example: '2026-11-17T06:48:16.161453Z'
            accounts:
              type: array
              description: The virtual or real accounts provisioned for the customer.
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 8
                  account_reference:
                    type: string
                    example: primary
                  customer_id:
                    type: integer
                    example: 15
                  customer_reference:
                    type: string
                    example: account_001
                  program:
                    type: string
                    nullable: true
                    example: null
                  provisioning:
                    type: string
                    example: ON_REQUEST
                  provider_reference:
                    type: string
                    nullable: true
                    example: null
                  currency:
                    type: string
                    example: USD
                  country_code:
                    type: string
                    nullable: true
                    example: null
                  network:
                    type: string
                    nullable: true
                    example: null
                  label:
                    type: string
                    nullable: true
                    example: null
                  status:
                    type: string
                    example: PENDING
                  provider_status:
                    type: string
                    nullable: true
                    example: null
                  holder_name:
                    type: string
                    nullable: true
                    example: null
                  payment_instructions:
                    type: array
                    items:
                      type: object
                    example: []
                  metadata:
                    type: object
                    example: {}
                  message:
                    type: string
                    example: Waiting for the customer to become ACTIVE
                  refreshed_at:
                    type: string
                    format: date-time
                    nullable: true
                    example: null
                  created_at:
                    type: string
                    format: date-time
                    example: '2026-11-17T06:48:16.262954Z'
                  updated_at:
                    type: string
                    format: date-time
                    example: '2026-11-17T06:48:16.262954Z'
            business:
              type: object
              nullable: true
              example: null
            individual:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                middle_name:
                  type: string
                  nullable: true
                  example: null
                last_name:
                  type: string
                  example: Doe
                nationality:
                  type: string
                  nullable: true
                  example: null
            identifications:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: PASSPORT
                  issuing_country:
                    type: string
                    example: NG
                  last4:
                    type: string
                    example: '1511'
                  expires_on:
                    type: string
                    format: date
                    nullable: true
                    example: '2030-01-15'
            associated_persons:
              type: array
              description: The persons associated with the customer, where applicable.
              items:
                type: object
              example: []
            metadata:
              type: object
              description: The additional customer information.
              example: {}
            created_at:
              type: string
              description: The timestamp when the customer was created.
              format: date-time
              example: '2026-11-17T06:48:15.891065Z'
            updated_at:
              type: string
              description: The timestamp when the customer was last updated.
              format: date-time
              example: '2026-11-17T06:48:32.137453Z'
    listCustomersResponse:
      title: List Customers Response
      type: object
      properties:
        message:
          type: string
          description: >-
            A descriptive message regarding the overall outcome of the
            operation.
          example: Customers retrieved
        status:
          type: boolean
          description: Indicates whether the request was successful.
          example: true
        retry_count:
          type: integer
          description: The number of retries attempted during processing.
          example: 0
        data:
          type: object
          description: >-
            The payload containing the paginated list of customers and
            pagination metadata.
          properties:
            data:
              type: array
              description: The list of customer records.
              items:
                type: object
                properties:
                  id:
                    type: integer
                    description: The unique internal identifier for the customer record.
                    example: 15
                  customer_reference:
                    type: string
                    description: The unique external reference provided during creation.
                    example: payaza_account_001
                  type:
                    type: string
                    description: The type of customer (e.g., individual, business).
                    example: individual
                  status:
                    type: string
                    description: The overall KYC or account status of the customer.
                    example: UNDER_REVIEW
            page:
              type: integer
              description: >-
                Page number returned. A request with page_number=0 returns page:
                1, meaning response pagination is one-based.
              example: 1
            size:
              type: integer
              description: Page size used.
              example: 20
            total:
              type: integer
              description: Total number of customers across all pages.
              example: 3
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Payaza {{Public API Key in Base 64}}
    TenantID:
      type: apiKey
      in: header
      name: X-TenantID
      description: live or test
    ProductID:
      type: apiKey
      in: header
      name: X-ProductID
      description: 'default value is ‟app” '

````

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