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

# Create customer

> Create an individual or a business customer. Only email and a name are required (firstname and lastname for an individual, businessName for a business); type defaults to individual. Identification, address, phone, documents, owners and metadata are optional here and are checked when a virtual account is created.



## OpenAPI

````yaml /pagoramp-checkout-openapi.json post /api/v1/customers
openapi: 3.0.0
info:
  title: Pagoramp Open API
  description: Our collection orchestration API for merchants to integrate to their system
  version: '1.0'
  contact: {}
servers:
  - url: https://pay-api.pagoramp.com
    description: Production
  - url: https://pay-api-staging.pagoramp.com
    description: Staging
security:
  - x-api-key: []
tags:
  - name: Checkout
    description: ''
  - name: P2P
    description: ''
  - name: Payment Links
    description: ''
  - name: Customer
    description: ''
  - name: Customers
    description: ''
  - name: Virtual Accounts
    description: ''
  - name: Misc
    description: ''
paths:
  /api/v1/customers:
    post:
      tags:
        - Customers
      summary: Create customer
      description: >-
        Create an individual or a business customer. Only email and a name are
        required (firstname and lastname for an individual, businessName for a
        business); type defaults to individual. Identification, address, phone,
        documents, owners and metadata are optional here and are checked when a
        virtual account is created.
      operationId: MerchantCustomersController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                example:
                  status: success
                  message: Customer created successfully
                  data:
                    uuid: 224ca5c5-f2a6-419b-bf36-73997434d945
                    type: individual
                    firstname: John
                    lastname: Doe
                    businessName: null
                    email: johndoe@example.com
                    phone: '+2348012345678'
                    country: NG
                    externalReference: cust_1001
                    kycStatus: pending
                    identification:
                      type: BVN
                      last4: '8901'
                    address:
                      line1: 12 Marina Road
                      city: Lagos
                      country: NG
                    metadata:
                      plan: pro
                    createdAt: '2026-08-27T11:39:52.476Z'
                    updatedAt: '2026-08-27T11:39:52.476Z'
        '409':
          description: ''
          content:
            application/json:
              schema:
                example:
                  status: error
                  message: A customer with this email already exists
                  errors:
                    - field: email
                      code: customer_exists
                      customerId: 224ca5c5-f2a6-419b-bf36-73997434d945
      security:
        - x-api-key: []
components:
  schemas:
    CreateCustomerDto:
      type: object
      properties:
        firstname:
          type: string
          example: John
          description: Required for individuals.
        lastname:
          type: string
          example: Doe
          description: Required for individuals.
        businessName:
          type: string
          example: Acme Ltd
          description: Required for businesses.
        phone:
          type: string
          example: '+2348012345678'
          description: >-
            Must start with + and the country code. Spaces, dashes and brackets
            are removed.
        country:
          type: string
          example: NG
        externalReference:
          type: string
          example: cust_1001
          description: Your own id for this customer. Unique per merchant.
        identification:
          $ref: '#/components/schemas/CustomerIdentificationDto'
        address:
          $ref: '#/components/schemas/CustomerAddressDto'
        dateOfBirth:
          type: string
          example: '1990-06-15'
          description: Individuals.
        nationality:
          type: string
          example: NG
          description: Individuals.
        occupation:
          type: string
          description: Individuals.
        registrationNumber:
          type: string
          example: BN123456789
          description: Businesses.
        owners:
          description: 'Businesses: owners and directors.'
          type: array
          items:
            $ref: '#/components/schemas/CustomerOwnerDto'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/CustomerDocumentDto'
        metadata:
          type: object
          example:
            plan: pro
          description: Returned unchanged. 4000 characters of JSON at most.
        type:
          type: string
          enum:
            - individual
            - business
          default: individual
          description: Defaults to individual when omitted.
        email:
          type: string
          example: johndoe@example.com
      required:
        - email
    CustomerIdentificationDto:
      type: object
      properties:
        type:
          type: string
          example: BVN
          description: For example BVN, NIN, passport, national_id, tax_id.
        number:
          type: string
          example: '12345678901'
          description: >-
            Stored encrypted and never returned; only the last four characters
            come back.
      required:
        - type
        - number
    CustomerAddressDto:
      type: object
      properties:
        line1:
          type: string
          example: 12 Marina Road
        line2:
          type: string
        city:
          type: string
          example: Lagos
        state:
          type: string
          example: Lagos
        postalCode:
          type: string
          example: '100001'
        country:
          type: string
          example: NG
    CustomerOwnerDto:
      type: object
      properties:
        firstname:
          type: string
          example: Jane
        lastname:
          type: string
          example: Roe
        ownershipPercent:
          type: number
          example: 60
        dateOfBirth:
          type: string
          example: '1985-04-12'
        nationality:
          type: string
          example: CA
      required:
        - firstname
        - lastname
    CustomerDocumentDto:
      type: object
      properties:
        type:
          type: string
          example: incorporation
          description: >-
            For example id_document, utility_bill, incorporation,
            proof_of_address.
        url:
          type: string
          example: https://files.example.com/acme-incorporation.pdf
          description: An https link the provider can open.
      required:
        - type
        - url
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key

````

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