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

# Add / Update Beneficial Owner

> Submits or replaces the complete list of Ultimate Beneficial Owners (UBOs).
The array completely replaces the existing list — always send all UBOs together.
Cannot be updated after the verification step is complete.


## When to Use

Submits or replaces the list of Ultimate Beneficial Owners (UBOs) for a merchant.

<Warning>
  The array sent in the request body **completely replaces** the existing list of beneficial owners. Always send all UBOs in a single request — partial updates are not supported.
</Warning>

A **beneficial owner** is any individual holding more than **10% equity** in the entity. For Partnerships, LLPs, and Companies, include every such individual with their PAN and shareholding percentage. See [Merchant Requirements](/guides/merchant-requirements#documents-by-entity-type) for the full list per entity type.

Beneficial owner details cannot be updated after the merchant's verification step is complete.

## Error Scenarios

| Scenario                                             | HTTP Code |
| ---------------------------------------------------- | --------- |
| Required fields missing or empty                     | `400`     |
| PAN is not a personal PAN (type `P`)                 | `400`     |
| PAN does not exist                                   | `400`     |
| Update attempted after verification step is complete | `400`     |
| `onboardingId` does not exist                        | `404`     |
| `onboardingId` does not belong to this partner       | `403`     |


## OpenAPI

````yaml PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner
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/{onboardingId}/beneficial-owner:
    put:
      tags:
        - Merchant Onboarding
      summary: Add / Update Beneficial Owner
      description: >
        Submits or replaces the complete list of Ultimate Beneficial Owners
        (UBOs).

        The array completely replaces the existing list — always send all UBOs
        together.

        Cannot be updated after the verification step is complete.
      operationId: updateBeneficialOwner
      parameters:
        - name: onboardingId
          in: path
          required: true
          schema:
            type: string
          example: pg_onboard_abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - name
                  - pan
                  - percentageOwnership
                properties:
                  designation:
                    type: string
                    description: Job title or role of the beneficial owner.
                    example: Director
                  name:
                    type: string
                    description: Full legal name of the beneficial owner.
                    example: Ravi Kumar
                  pan:
                    type: string
                    description: Personal PAN (type P) of the beneficial owner.
                    example: ABCPK1234R
                  percentageOwnership:
                    type: number
                    minimum: 10
                    maximum: 100
                    description: Ownership percentage (range 10–100).
                    example: 60
            example:
              - designation: Director
                name: Ravi Kumar
                pan: ABCPK1234R
                percentageOwnership: 60
              - designation: Co-Founder
                name: Priya Sharma
                pan: DEFPS5678R
                percentageOwnership: 40
      responses:
        '200':
          description: Beneficial owner details updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
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
    Forbidden:
      description: The onboardingId does not belong to the authenticated partner.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    NotFound:
      description: The specified onboardingId does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
  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.

````