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

# Create Or Update A Customer

> This endpoint registers a new customer and requests virtual accounts in a single API call. The customer can be an individual or a business.

**Notes:**
- Kindly note that IP whitelisting is required for your requests.
- Sending the same `customer_reference` again updates the existing customer rather than creating a new customer record. This can be used, for example, to submit additional information or provide a missing document during the verification process.
- Store `data.id` and `customer_reference` against the merchant's customer record.
- If the customer status is `ACTION_REQUIRED`, retrieve the outstanding items in `requirements[]` and submit the missing information using the same `customer_reference`.
- If the customer status is `UNDER_REVIEW`, wait for the verification process to complete and periodically retrieve the customer's status using the Get Customer endpoint.
- `date_of_birth`, identification `number`, and `issued_on` are accepted in the request but are not echoed back in the response.



## OpenAPI

````yaml /openapi.json post /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:
    post:
      tags:
        - vIBANS
      summary: Create Or Update A Customer
      description: >-
        This endpoint registers a new customer and requests virtual accounts in
        a single API call. The customer can be an individual or a business.


        **Notes:**

        - Kindly note that IP whitelisting is required for your requests.

        - Sending the same `customer_reference` again updates the existing
        customer rather than creating a new customer record. This can be used,
        for example, to submit additional information or provide a missing
        document during the verification process.

        - Store `data.id` and `customer_reference` against the merchant's
        customer record.

        - If the customer status is `ACTION_REQUIRED`, retrieve the outstanding
        items in `requirements[]` and submit the missing information using the
        same `customer_reference`.

        - If the customer status is `UNDER_REVIEW`, wait for the verification
        process to complete and periodically retrieve the customer's status
        using the Get Customer endpoint.

        - `date_of_birth`, identification `number`, and `issued_on` are accepted
        in the request but are not echoed back in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/createACustomerRequest'
            examples:
              Create Or Update A customer:
                summary: Create Or Update A Customer Request
                value:
                  customer_reference: account_001
                  type: individual
                  email: johndoe@company.com
                  phone: '+2348012345679'
                  country_code: NG
                  address:
                    street: 123 Main Street
                    city: Lagos
                    subdivision: Lagos
                    postal_code: '100001'
                    country_code: NG
                  individual:
                    first_name: John
                    last_name: Doe
                    date_of_birth: '1990-01-15'
                  identifications:
                    - type: PASSPORT
                      number: A12345678
                      issuing_country: NG
                      issued_on: '2020-01-15'
                      expires_on: '2030-01-15'
                    - type: TIN
                      number: 12345678-0001
                      issuing_country: NG
                  documents:
                    - type: IDENTITY_DOCUMENT
                      side: FRONT
                      url: >-
                        https://your-bucket.s3.amazonaws.com/kyc/john-doe-passport.png
                  account:
                    - USD
      responses:
        '200':
          description: Initiate Payment Successful Response
          content:
            application/json:
              schema:
                oneOf:
                  - d802d903-bc6a-4096-bfbe-93bb524d3b99
              examples:
                Create A Customer Request:
                  summary: Success Response
                  value:
                    message: Customer processed
                    status: true
                    retry_count: 0
                    data:
                      id: 15
                      customer_reference: account_001
                      type: individual
                      name: John Doe
                      status: UNDER_REVIEW
                      requirements: []
                      registrations:
                        - provider_reference: 01a1e843-b041-7384-8649-430c0e7abc30
                          provisioning: ON_REQUEST
                          status: UNDER_REVIEW
                          programs:
                            - currencies:
                                - USD
                              status: UNDER_REVIEW
                              provider_status: PENDING
                              requirements: []
                          documents:
                            - type: IDENTITY_DOCUMENT
                              side: FRONT
                              status: UPLOADED
                              file_name: 1774864420319-pocketapp.png
                      accounts:
                        - id: 8
                          account_reference: primary
                          currency: USD
                          status: PENDING
                          payment_instructions: []
                          message: Waiting for the customer to become ACTIVE
                      identifications:
                        - type: PASSPORT
                          issuing_country: NG
                          last4: '1511'
                          expires_on: '2030-01-15'
        '400':
          description: >-
            Please ensure that you provide a valid customer_reference in your
            request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: VALIDATION_ERROR
                  message:
                    type: string
                    example: customer_reference is required
                  status:
                    type: boolean
                    example: false
                  retry_count:
                    type: integer
                    example: 0
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: VALIDATION_ERROR
                    message: customer_reference is required
                    status: false
                    retry_count: 0
        '409':
          description: >-
            The Idempotency-Key provided has already been used for a different
            request. Please use a new Idempotency-Key for this request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: IDEMPOTENCY_CONFLICT
                  message:
                    type: string
                    example: Idempotency-Key was already used for a different request
                  status:
                    type: boolean
                    example: false
                  retry_count:
                    type: integer
                    example: 0
              examples:
                Idempotency Conflict:
                  summary: Idempotency Conflict
                  value:
                    code: IDEMPOTENCY_CONFLICT
                    message: Idempotency-Key was already used for a different request
                    status: false
                    retry_count: 0
      security:
        - ApiKeyAuth:
            - Payaza {{Public API Key In Base64}}
          TenantID:
            - test or live
          IdempotencyKey:
            - >-
              A unique value that prevents duplicate processing when retrying
              the same request.
components:
  schemas:
    createACustomerRequest:
      title: Create A Customer Request
      type: object
      required:
        - customer_reference
        - type
        - email
        - phone
        - address
        - country_code
        - identifications
        - documents
      properties:
        customer_reference:
          type: string
          description: >-
            Merchant's unique reference for the customer. Used for retrieving
            and updating the customer.
          example: account_001
        type:
          type: string
          description: 'Customer type. Supported values: "individual", "business".'
          example: individual
        email:
          type: string
          format: email
          description: The customer's email address.
          example: johndoe@company.com
        phone:
          type: string
          description: The customer's phone number in E.164 format, e.g. +2348012345679..
          example: '+2348012345679'
        country_code:
          type: string
          description: The customer's country code in ISO 3166-1 Alpha-2 format, e.g. NG.
          example: NG
        address:
          type: object
          description: >-
            The customer's residential or operating address. See Address
            Parameters below.
          required:
            - street
            - city
            - subdivision
            - postal_code
            - country_code
          properties:
            street:
              type: string
              description: Street address, line 1.
              example: 123 Main Street
            street2:
              type: string
              description: Street address, line 2.
              example: Apartment 4B
            city:
              type: string
              description: The customer's city.
              example: Lagos
            subdivision:
              type: string
              description: The state or region, e.g. Lagos.
              example: Lagos
            postal_code:
              type: string
              description: The postal or ZIP code.
              example: '100001'
            country_code:
              type: string
              description: The country code in ISO Alpha-2 format..
              example: NG
        individual:
          type: object
          description: The individual customer's details.
          required:
            - first_name
            - last_name
            - date_of_birth
          properties:
            first_name:
              type: string
              description: The first name of the customer.
              example: John
            middle_name:
              type: string
              description: The middle name of the customer.
              example: Jane
            last_name:
              type: string
              description: The last name of the customer.
              example: Doe
            date_of_birth:
              type: string
              format: date
              description: The customer's date of birth in YYYY-MM-DD format.
              example: '1990-01-15'
        identifications:
          type: array
          description: The customer identification records
          required:
            - type
            - number
            - issuing_country
            - issued_on
            - expires_on
          items:
            type: object
            properties:
              type:
                type: string
                description: The type of identification (e.g., PASSPORT, TIN).
                example: PASSPORT
              number:
                type: string
                description: >-
                  The full identification number. The full number is not
                  returned in responses; only the last four characters are
                  displayed..
                example: A12345678
              issuing_country:
                type: string
                description: The ISO Alpha-2 country code of the issuing country.
                example: NG
              issued_on:
                type: string
                format: date
                description: The issuance date of the document in YYYY-MM-DD format.
                example: '2020-01-15'
              expires_on:
                type: string
                format: date
                description: The expiration date of the document in YYYY-MM-DD format.
                example: '2030-01-15'
        documents:
          type: array
          description: A list of uploaded document links for KYC verification.
          required:
            - street
            - city
          items:
            type: object
            properties:
              type:
                type: string
                description: >-
                  Document type, e.g. IDENTITY_DOCUMENT. Business formation
                  document types are listed under Business Formation Documents.
                example: IDENTITY_DOCUMENT
              side:
                type: string
                description: The side of the document scanned (e.g., FRONT, BACK).
                example: FRONT
              url:
                type: string
                format: uri
                description: >-
                  The public reachable HTTPS URL of the document. Payaza
                  downloads the file and stores its SHA-256 hash.
                example: https://your-bucket.s3.amazonaws.com/kyc/john-doe-passport.png
        account:
          type: array
          description: A list of currencies for the accounts to be created.
          items:
            type: string
            example: USD
  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” '
    IdempotencyKey:
      type: apiKey
      in: header
      name: Idempotency-Key
      description: >-
        A unique value that prevents duplicate processing when retrying the same
        request.

````

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