Add / Update Beneficial Owner

PUT

gcc

partner

merchant

onboard

{onboardingId}

beneficial-owner

Add / Update Beneficial Owner

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
  }
]
'

import requests

url = "https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner"

payload = [
    {
        "designation": "Director",
        "name": "Ravi Kumar",
        "pan": "ABCPK1234R",
        "percentageOwnership": 60
    },
    {
        "designation": "Co-Founder",
        "name": "Priya Sharma",
        "pan": "DEFPS5678R",
        "percentageOwnership": 40
    }
]
headers = {
    "x-gl-auth": "<api-key>",
    "x-gl-digest": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.put("https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner")
  .header("x-gl-auth", "<api-key>")
  .header("x-gl-digest", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"designation\": \"Director\",\n    \"name\": \"Ravi Kumar\",\n    \"pan\": \"ABCPK1234R\",\n    \"percentageOwnership\": 60\n  },\n  {\n    \"designation\": \"Co-Founder\",\n    \"name\": \"Priya Sharma\",\n    \"pan\": \"DEFPS5678R\",\n    \"percentageOwnership\": 40\n  }\n]")
  .asString();

const url = 'https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner';
const options = {
  method: 'PUT',
  headers: {
    'x-gl-auth': '<api-key>',
    'x-gl-digest': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      designation: 'Director',
      name: 'Ravi Kumar',
      pan: 'ABCPK1234R',
      percentageOwnership: 60
    },
    {
      designation: 'Co-Founder',
      name: 'Priya Sharma',
      pan: 'DEFPS5678R',
      percentageOwnership: 40
    }
  ])
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "",
  "data": {
    "merchantInfo": {
      "onboardingId": "pg_onboard_abc123",
      "partnerOnboardingId": "partner-merchant-001",
      "onboardingStatus": "INITIATED",
      "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>",
        "accountType": "CURRENT"
      }
    },
    "merchantOnboardingCheckListStatus": {
      "businessDetails": "COMPLETE",
      "beneficialOwners": "COMPLETE",
      "bankDetails": "COMPLETE",
      "authorisedSignatory": "COMPLETE",
      "vkyc": "COMPLETE",
      "digiLocker": "COMPLETE",
      "tncAcknowledged": "COMPLETE",
      "documents": "COMPLETE",
      "products": "COMPLETE",
      "documentsToBeUploaded": [
        "<string>"
      ]
    }
  }
}

{
  "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"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "UNAUTHORIZED",
  "data": {},
  "errors": null,
  "errorDetails": [
    {
      "fieldName": "authorization",
      "message": "Invalid x-gl-token-external"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "VALIDATION_ERROR",
  "data": {},
  "errors": {},
  "errorDetails": [
    {
      "field": "panNumber",
      "message": "Required field is missing"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "VALIDATION_ERROR",
  "data": {},
  "errors": {},
  "errorDetails": [
    {
      "field": "panNumber",
      "message": "Required field is missing"
    }
  ]
}

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

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

Add / Update Beneficial Owner

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
  }
]
'

import requests

url = "https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner"

payload = [
    {
        "designation": "Director",
        "name": "Ravi Kumar",
        "pan": "ABCPK1234R",
        "percentageOwnership": 60
    },
    {
        "designation": "Co-Founder",
        "name": "Priya Sharma",
        "pan": "DEFPS5678R",
        "percentageOwnership": 40
    }
]
headers = {
    "x-gl-auth": "<api-key>",
    "x-gl-digest": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.put("https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner")
  .header("x-gl-auth", "<api-key>")
  .header("x-gl-digest", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"designation\": \"Director\",\n    \"name\": \"Ravi Kumar\",\n    \"pan\": \"ABCPK1234R\",\n    \"percentageOwnership\": 60\n  },\n  {\n    \"designation\": \"Co-Founder\",\n    \"name\": \"Priya Sharma\",\n    \"pan\": \"DEFPS5678R\",\n    \"percentageOwnership\": 40\n  }\n]")
  .asString();

const url = 'https://api.onboard.payglocal.in/gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner';
const options = {
  method: 'PUT',
  headers: {
    'x-gl-auth': '<api-key>',
    'x-gl-digest': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      designation: 'Director',
      name: 'Ravi Kumar',
      pan: 'ABCPK1234R',
      percentageOwnership: 60
    },
    {
      designation: 'Co-Founder',
      name: 'Priya Sharma',
      pan: 'DEFPS5678R',
      percentageOwnership: 40
    }
  ])
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "",
  "data": {
    "merchantInfo": {
      "onboardingId": "pg_onboard_abc123",
      "partnerOnboardingId": "partner-merchant-001",
      "onboardingStatus": "INITIATED",
      "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>",
        "accountType": "CURRENT"
      }
    },
    "merchantOnboardingCheckListStatus": {
      "businessDetails": "COMPLETE",
      "beneficialOwners": "COMPLETE",
      "bankDetails": "COMPLETE",
      "authorisedSignatory": "COMPLETE",
      "vkyc": "COMPLETE",
      "digiLocker": "COMPLETE",
      "tncAcknowledged": "COMPLETE",
      "documents": "COMPLETE",
      "products": "COMPLETE",
      "documentsToBeUploaded": [
        "<string>"
      ]
    }
  }
}

{
  "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"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "UNAUTHORIZED",
  "data": {},
  "errors": null,
  "errorDetails": [
    {
      "fieldName": "authorization",
      "message": "Invalid x-gl-token-external"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "VALIDATION_ERROR",
  "data": {},
  "errors": {},
  "errorDetails": [
    {
      "field": "panNumber",
      "message": "Required field is missing"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "VALIDATION_ERROR",
  "data": {},
  "errors": {},
  "errorDetails": [
    {
      "field": "panNumber",
      "message": "Required field is missing"
    }
  ]
}

Partner APIs: Merchant Onboarding

Payment APIs

Partner APIs: MCA

When to Use

Error Scenarios

Authorizations

Path Parameters

Body

Response

​When to Use

​Error Scenarios

Authorizations

Path Parameters

Body

Response

When to Use

Error Scenarios