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.

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner

Add / Update Beneficial Owner

cURL

curl --request PUT \
  --url https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner \
  --header 'Content-Type: application/json' \
  --header 'x-gl-auth: <api-key>' \
  --header 'x-gl-digest: <api-key>' \
  --data '
[
  {
    "designation": "Director",
    "name": "Ravi Kumar",
    "pan": "ABCPK1234R",
    "percentageOwnership": 60
  },
  {
    "designation": "Co-Founder",
    "name": "Priya Sharma",
    "pan": "DEFPS5678R",
    "percentageOwnership": 40
  }
]
'

200

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "",
  "data": {
    "merchantInfo": {
      "onboardingId": "pg_onboard_abc123",
      "partnerOnboardingId": "partner-merchant-001",
      "businessDetails": {
        "entityType": "<string>",
        "gstNumber": "<string>",
        "natureOfBusiness": "<string>",
        "registeredName": "<string>",
        "tradeName": "<string>",
        "iec": "<string>",
        "businessMonthlySize": "<string>",
        "websiteUrl": "<string>",
        "purposeCode": "<string>",
        "businessRegisteredAddress": {
          "streetAddress1": "<string>",
          "streetAddress2": "<string>",
          "zipcode": "<string>",
          "stateCode": "MH",
          "city": "<string>",
          "state": "Maharashtra"
        },
        "businessOperatingAddress": {
          "streetAddress1": "<string>",
          "streetAddress2": "<string>",
          "zipcode": "<string>",
          "stateCode": "MH",
          "city": "<string>",
          "state": "Maharashtra"
        }
      },
      "directorDetails": [
        {
          "designation": "<string>",
          "name": "<string>",
          "pan": "<string>"
        }
      ],
      "beneficialOwnerDetails": [
        {
          "designation": "<string>",
          "name": "<string>",
          "pan": "<string>",
          "percentageOwnership": 123
        }
      ],
      "authorisedSignatoryDetails": {
        "authSignatoryName": "<string>",
        "authSignatoryPan": "<string>",
        "contact": {
          "phone": "<string>",
          "email": "<string>"
        }
      },
      "settlementDetails": {
        "bankAccountNumber": "<string>",
        "bankIfscCode": "<string>",
        "accountHolderName": "<string>"
      }
    },
    "merchantOnboardingCheckListStatus": {
      "documentsToBeUploaded": [
        "<string>"
      ]
    }
  }
}

When to Use

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

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.

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

Authorizations

x-gl-auth · string · header · required

Static API Key generated from the PayGlocal Partner Dashboard.

x-gl-digest · string · header · required

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.

Path Parameters

onboardingId · string · required

Body

application/json

name · string · required

Full legal name of the beneficial owner.

Example:

"Ravi Kumar"

pan · string · required

Personal PAN (type P) of the beneficial owner.

Example:

"ABCPK1234R"

percentageOwnership · number · required

Ownership percentage (range 10–100).

Required range: 10 <= x <= 100

Example:

60

designation · string

Job title or role of the beneficial owner.

Example:

"Director"

Response

200

application/json

Beneficial owner details updated successfully.

gid · string

PayGlocal global transaction ID.

Example:

"gl_9c2645ed09edb22e"

timestamp · string

Response timestamp (DD/MM/YYYY HH:MM:SS).

Example:

"10/01/2026 15:00:00"

reasonCode · string

Empty string on success.

Example:

""

data · object

Show child attributes