Add Update UBO API

put

https://test-accounts.payu.in/api/v1/merchants/{uuid}/signatory_details

The Add/Update UBO API submits Ultimate Beneficial Owner details (Step 12 of 16).

Prerequisite:

Step 11 (VKYC), as applicable.

Entity applicability:
Required for Private Limited, Public Limited, Partnership, Trust, LLP, and Society. Not required for Individual, Sole Proprietorship, or One Person Company.

Use array indexing (ubo[0], ubo[1], …) for multiple UBOs.

HTTP Method: PUT

Environment

	URL
Test Environment	`https://test-partner.payu.in/api/v1/merchants/{uuid}/signatory_details`
Production Environment	`https://partner.payu.in/api/v1/merchants/{uuid}/signatory_details`

Sample request

  curl --location --request PUT 'https://test-partner.payu.in/api/v1/merchants/{{uuid}}/signatory_details' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'ubo[0][name]=UBO Name' \
  --data-urlencode 'ubo[0][pancard_number]=ABCDE1234F' \
  --data-urlencode 'ubo[0][ownership_percentage]=30'

Sample response

Success scenario

{
  "merchant": {
    "mid": 12345678,
    "status": "account_created"
  }
}

Failure scenario

401 Unauthorized — Token invalid or expired; call Step 00 again

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

422 Validation Failed — Request parameters failed validation

{
  "error": "validation_failed",
  "message": "Check the error details in the response body"
}

Response parameters

Parameter	Description	Example
merchant.mid	`integer` — Merchant ID	`12345678`
merchant.status	`string` — Current onboarding status	`account_created`

Additional request parameters info

Header parameters

Header	Description	Example
Authorization `mandatory`	`string` — Bearer token from Step 00 (`GetToken`)	`Bearer {{access_token}}`
Content-Type `mandatory`	`string` — Must be `application/x-www-form-urlencoded`	`application/x-www-form-urlencoded`

Path parameters

Parameter	Description	Example
uuid `mandatory`	`string` — Merchant UUID from Step 01 (`CreateMerchant`)	`11ef-d968-6b042d6c-9b94-02975f21d323`

Body parameters

Parameter	Description	Example
ubo[0][name] `mandatory`	`string` — UBO full name	`UBO Name`
ubo[0][pancard_number] `mandatory`	`string` — UBO PAN	`ABCDE1234F`
ubo[0][ownership_percentage] `mandatory`	`string` — Ownership percentage (typically 25%+)	`30`

Path Params

uuid

string

required

string — Merchant UUID from Step 01 (CreateMerchant)

Form Data

merchant[ubo[0][beneficiary_name]]

string

string — Full name of the ultimate beneficial owner.

merchant[ubo[0][ubo_pan_number]]

string

string — PAN number of the UBO.

merchant[ubo[0][ownership_percent]]

string

string — Ownership percentage (typically 25%+).

merchant[ubo[0][dob]]

string

string — Date of birth of the UBO (YYYY-MM-DD).

merchant[ubo[0][nationality]]

string

string — Nationality as ISO country code.

merchant[ubo[0][email]]

string

string — Email of the UBO (optional but recommended).

merchant[ubo[0][address][address_line]]

string

string — Address line of the UBO.

merchant[ubo[0][address][pincode]]

string

string — 6-digit pincode of the UBO address.

merchant[ubo[1][beneficiary_name]]

string

string — Full name of the ultimate beneficial owner.

merchant[ubo[1][ubo_pan_number]]

string

string — PAN number of the UBO.

merchant[ubo[1][ownership_percent]]

string

string — Ownership percentage (typically 25%+).

merchant[ubo[1][dob]]

string

string — Date of birth of the UBO (YYYY-MM-DD).

merchant[ubo[1][nationality]]

string

string — Nationality as ISO country code.

merchant[ubo[1][email]]

string

string — Email of the UBO (optional but recommended).

merchant[ubo[1][address][address_line]]

string

string — Address line of the UBO.

merchant[ubo[1][address][pincode]]

string

string — 6-digit pincode of the UBO address.

merchant[ubo[2][beneficiary_name]]

string

string — Full name of the ultimate beneficial owner.

merchant[ubo[2][ubo_pan_number]]

string

string — PAN number of the UBO.

merchant[ubo[2][ownership_percent]]

string

string — Ownership percentage (typically 25%+).

merchant[ubo[2][dob]]

string

string — Date of birth of the UBO (YYYY-MM-DD).

merchant[ubo[2][nationality]]

string

string — Nationality as ISO country code.

merchant[ubo[2][email]]

string

string — Email of the UBO (optional but recommended).

merchant[ubo[2][address][address_line]]

string

string — Address line of the UBO.

merchant[ubo[2][address][pincode]]

string

string — 6-digit pincode of the UBO address.

merchant[ubo[3][beneficiary_name]]

string

string — Full name of the ultimate beneficial owner.

merchant[ubo[3][ubo_pan_number]]

string

string — PAN number of the UBO.

merchant[ubo[3][ownership_percent]]

string

string — Ownership percentage (typically 25%+).

merchant[ubo[3][dob]]

string

string — Date of birth of the UBO (YYYY-MM-DD).

merchant[ubo[3][nationality]]

string

string — Nationality as ISO country code.

merchant[ubo[3][email]]

string

string — Email of the UBO (optional but recommended).

merchant[ubo[3][address][address_line]]

string

string — Address line of the UBO.

merchant[ubo[3][address][pincode]]

string

string — 6-digit pincode of the UBO address.

merchant[ubo_exist]

string

string — Must be "1" when any UBOs are submitted.

Responses

400

Bad Request

401

Unauthorized - Invalid or expired token

403

Forbidden - No access to this resource

404

Not Found

422

Validation Failed

500

Internal Server Error

Language

Credentials

Bearer

JWT

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Sample request

Sample response

Success scenario

Failure scenario

Response parameters

Additional request parameters info

Header parameters

Path parameters

Body parameters

200Successful response

EXAMPLE QUESTIONS