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

# Create Onboarding

> Creates a new merchant onboarding record. This is always the first API call in the
onboarding sequence. The `onboardingId` returned is required for all subsequent calls.


## When to Use

Always the **first API call** in the onboarding sequence. The `onboardingId` returned in the response is required as a path parameter for every subsequent call.

A merchant is uniquely identified by their PAN. Each PAN can have only one active onboarding record in the PayGlocal system.

Valid PAN types: `P` (Individual), `C` (Company), `T` (Trust), `F` (Firm).

## Error Scenarios

| Scenario                                   | HTTP Code |
| ------------------------------------------ | --------- |
| Required fields missing or empty           | `400`     |
| Invalid field format                       | `400`     |
| PAN type is not one of P, C, T, F          | `400`     |
| PAN already exists in the PayGlocal system | `400`     |
| PAN does not exist (invalid PAN)           | `400`     |


## OpenAPI

````yaml POST /gcc/v2/partner/merchant/onboard
openapi: 3.0.3
info:
  title: PayGlocal API
  description: >
    PayGlocal REST API covering merchant onboarding, payment initiation,
    refunds,

    capture, reversal, and standing-instruction (subscription) flows.
  version: '2.0'
  contact:
    name: PayGlocal Support
    email: merchant.support@payglocal.in
    url: https://payglocal.in
servers:
  - url: https://api.onboard.payglocal.in
    description: Onboarding — Production
  - url: https://api.onboard.uat.payglocal.in
    description: Onboarding — Sandbox
  - url: https://api.payglocal.in
    description: Payments — Production
  - url: https://api.uat.payglocal.in
    description: Payments — Sandbox
  - url: https://gcc.prod.payglocal.in
    description: MCA — Production
  - url: https://gcc.uat.payglocal.in
    description: MCA — Sandbox
security:
  - ApiKeyAuth: []
    DigestAuth: []
tags:
  - name: Merchant Onboarding
    description: Endpoints to create and manage merchant onboarding records.
  - name: Reference Data
    description: Lookup endpoints for static reference data (categories, codes).
  - name: Payment
    description: Payment initiation, refund, capture, reversal, and status endpoints.
  - name: Standing Instructions
    description: Subscription / recurring-payment mandate operations.
  - name: MCA
    description: >-
      Merchant Collection Account — virtual account fetch and transaction
      document upload.
paths:
  /gcc/v2/partner/merchant/onboard:
    post:
      tags:
        - Merchant Onboarding
      summary: Create Onboarding
      description: >
        Creates a new merchant onboarding record. This is always the first API
        call in the

        onboarding sequence. The `onboardingId` returned is required for all
        subsequent calls.
      operationId: createOnboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - externalOnboardingId
                - panNumber
              properties:
                externalOnboardingId:
                  type: string
                  description: >-
                    Partner's unique identifier for this merchant. Must be
                    unique per merchant.
                  example: partner-merchant-001
                panNumber:
                  type: string
                  description: >-
                    PAN of the business entity. Valid types — P (Individual), C
                    (Company), T (Trust), F (Firm).
                  example: ABCDE1234F
            example:
              externalOnboardingId: partner-merchant-001
              panNumber: ABCDE1234F
      responses:
        '201':
          description: Merchant onboarding record created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonSuccessResponse'
              example:
                gid: gl_9c2645ed09edb22e
                timestamp: 10/01/2026 15:00:00
                reasonCode: ''
                data:
                  merchantInfo:
                    onboardingId: pg_onboard_abc123
                    partnerOnboardingId: partner-merchant-001
                    onboardingStatus: INITIATED
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CommonSuccessResponse:
      type: object
      properties:
        gid:
          type: string
          description: PayGlocal global transaction ID.
          example: gl_9c2645ed09edb22e
        timestamp:
          type: string
          description: Response timestamp (DD/MM/YYYY HH:MM:SS).
          example: 10/01/2026 15:00:00
        reasonCode:
          type: string
          description: Empty string on success.
          example: ''
        data:
          type: object
          properties:
            merchantInfo:
              $ref: '#/components/schemas/MerchantInfo'
            merchantOnboardingCheckListStatus:
              $ref: '#/components/schemas/ChecklistStatus'
    MerchantInfo:
      type: object
      properties:
        onboardingId:
          type: string
          description: PayGlocal-generated onboarding ID.
          example: pg_onboard_abc123
        partnerOnboardingId:
          type: string
          description: Partner's external onboarding ID.
          example: partner-merchant-001
        onboardingStatus:
          type: string
          description: Current onboarding lifecycle status.
          enum:
            - INITIATED
            - IN_PROGRESS
            - PENDING_VERIFICATION
            - PENDING_REVIEW
            - APPROVED
            - REJECTED
            - RFI
        businessDetails:
          type: object
          properties:
            entityType:
              type: string
            gstNumber:
              type: string
            natureOfBusiness:
              type: string
            registeredName:
              type: string
            tradeName:
              type: string
            iec:
              type: string
            businessMonthlySize:
              type: string
            websiteUrl:
              type: string
            purposeCode:
              type: string
            businessRegisteredAddress:
              $ref: '#/components/schemas/Address'
            businessOperatingAddress:
              $ref: '#/components/schemas/Address'
        directorDetails:
          type: array
          items:
            type: object
            properties:
              designation:
                type: string
              name:
                type: string
              pan:
                type: string
        beneficialOwnerDetails:
          type: array
          items:
            type: object
            properties:
              designation:
                type: string
              name:
                type: string
              pan:
                type: string
              percentageOwnership:
                type: number
        authorisedSignatoryDetails:
          type: object
          properties:
            authSignatoryName:
              type: string
            authSignatoryPan:
              type: string
            contact:
              type: object
              properties:
                phone:
                  type: string
                email:
                  type: string
        settlementDetails:
          type: object
          properties:
            bankAccountNumber:
              type: string
            bankIfscCode:
              type: string
            accountHolderName:
              type: string
            accountType:
              type: string
              enum:
                - CURRENT
                - SAVINGS
    ChecklistStatus:
      type: object
      properties:
        businessDetails:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        beneficialOwners:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        bankDetails:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        authorisedSignatory:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        vkyc:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        digiLocker:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        tncAcknowledged:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        documents:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        products:
          $ref: '#/components/schemas/PartnerMerchantStepStatus'
        documentsToBeUploaded:
          type: array
          items:
            type: string
    CommonErrorResponse:
      type: object
      properties:
        gid:
          type: string
          example: gl_9c2645ed09edb22e
        timestamp:
          type: string
          example: 10/01/2026 15:00:00
        reasonCode:
          type: string
          example: VALIDATION_ERROR
        data:
          type: object
        errors:
          type: object
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    Address:
      type: object
      properties:
        streetAddress1:
          type: string
          description: Primary street line.
        streetAddress2:
          type: string
          description: Secondary street line (suite, floor, etc.).
        zipcode:
          type: string
          description: PIN code.
        stateCode:
          type: string
          description: Two-letter state code (e.g., MH, KA, DL).
          example: MH
        city:
          type: string
          description: City name.
        state:
          type: string
          description: Full state name.
          example: Maharashtra
    PartnerMerchantStepStatus:
      type: string
      enum:
        - COMPLETE
        - INCOMPLETE
        - NOT_APPLICABLE
      description: Per-step completion state for an onboarding checklist field.
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          description: Name of the field that failed validation.
          example: panNumber
        message:
          type: string
          description: Human-readable error message.
          example: Required field is missing
  responses:
    BadRequest:
      description: Validation error — missing or invalid fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
          examples:
            validationError:
              summary: Validation error example
              value:
                gid: gl_9c2645ed09edb22e
                timestamp: 10/01/2026 15:00:00
                reasonCode: VALIDATION_ERROR
                data: {}
                errors: null
                errorDetails:
                  - fieldName: paymentData.totalAmount
                    message: This field is required
    Unauthorized:
      description: Authentication failed — invalid API key or digest.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
          examples:
            unauthorizedError:
              summary: Unauthorized error example
              value:
                gid: gl_9c2645ed09edb22e
                timestamp: 10/01/2026 15:00:00
                reasonCode: UNAUTHORIZED
                data: {}
                errors: null
                errorDetails:
                  - fieldName: authorization
                    message: Invalid x-gl-token-external
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-gl-auth
      description: Static API Key generated from the PayGlocal Partner Dashboard.
    DigestAuth:
      type: apiKey
      in: header
      name: x-gl-digest
      description: >
        Per-request HmacSHA256 signature, Base64-encoded, using your API Secret
        as the HMAC key.

        - For GET requests: sign the request URI path (e.g.
        `/gcc/v2/partner/merchant/onboard/business-category`), including query
        string if present.

        - For POST/PUT requests: sign the exact raw request body.

````