Integration using Partner APIs
Get a merchant onboarded with a small set of API calls: create merchant, update PAN/bank/business, CKYC OTP, upload KYC documents, initialize e-sign.
Onboarding flow
flowchart TD
A[1. Create Merchant] --> B[2. Update Website/App Details]
B --> C[3. Update Business Details]
C --> D[4. Submit Signing Authority]
D --> E[5. Upload KYC Documents]
E --> F[6. KYC Verification]
F --> G[7. Add/Update UBO]
G --> H[8. E-Sign Agreement]
H --> I[Merchant Activated]
style A fill:#e1f5ff
style I fill:#d4edda
Steps to integrate
Obtain a bearer token with the refer_merchant scope before these steps. See GetToken API. Each step below includes the environment URL and sample request/response. Request parameters are listed for Step 1; for later steps, use the linked API reference.
Step 1. Create Merchant (Name, Email, Phone)
Creates a new merchant shell account on PayU. Pass display name, email, mobile, product (PayUbiz), and business entity type. Store mid, uuid, and product_account_uuid from the response — later steps use these identifiers. For the full parameter list and Try It experience, see Create Merchant API.
HTTP Method: POST
Environment
| URL | |
|---|---|
| Test Environment | https://uat-partner.payu.in/api/v3/merchants |
| Production Environment | https://partner.payu.in/api/v3/merchants |
Request parameters
| Parameter | Description | Example |
|---|---|---|
merchant[display_name]mandatory | string — Business or display name | Acme Stores |
merchant[email]mandatory | string — Unique merchant email across PayU | [email protected] |
merchant[mobile]mandatory | string — Exactly 10-digit Indian mobile number | 9876543210 |
merchant[product]mandatory | string — Must be PayUbiz (required to avoid backend errors) | PayUbiz |
merchant[business_details][business_entity_type]mandatory | string — Entity type; determines CKYC method and later steps | Private Limited |
Sample request
curl --location 'https://uat-partner.payu.in/api/v3/merchants' \
--header 'Authorization: Bearer {{access_token}}' \
--form 'merchant[display_name]="Acme Stores"' \
--form 'merchant[email]="[email protected]"' \
--form 'merchant[mobile]="9876543210"' \
--form 'merchant[product]="PayUbiz"' \
--form 'merchant[business_details][business_entity_type]="Private Limited"'Sample response
{
"mid": 12345678,
"uuid": "11ef-d968-6b042d6c-9b94-02975f21d323",
"product_account_uuid": "11ef-d968-6b042d6c-9b94-02975f21d323"
}Step 2. Update Merchant Details (Business Info)
Adds business category, sub-category, expected monthly volume, GST, business name, and CIN where required (for Private Limited, Public Limited, and One Person Company). Use the merchant uuid from Step 1. For the full parameter list and Try It experience, see UpdateMerchant Business Details API.
HTTP Method: PUT
Environment
| URL | |
|---|---|
| Test Environment | https://uat-partner.payu.in/api/v1/merchants/{uuid}/update |
| Production Environment | https://partner.payu.in/api/v1/merchants/{uuid}/update |
Request Parameters
Header parameters
Header parameters
| Header | Description | Example |
|---|---|---|
Authorizationmandatory | string — Bearer token from Step 00 (GetToken) | Bearer {{access_token}} |
Content-Typemandatory | string — Must be multipart/form-data | multipart/form-data |
Path parameters
Path parameters
| Parameter | Description | Example |
|---|---|---|
uuidmandatory | string — Merchant UUID from Step 01 (CreateMerchant) | 11ef-d968-6b042d6c-9b94-02975f21d323 |
Body parameters
Body parameters
| Parameter | Description | Example |
|---|---|---|
merchant[pancard_number]mandatory | string — PAN in ABCDE1234F format | ABCDE1234F |
merchant[pancard_name]mandatory | string — Name on PAN card (must match registry) | MERCHANT LEGAL NAME |
merchant[dob]mandatory | string — DOB (Individual) or date of incorporation (YYYY-MM-DD) | 2000-01-06 |
Sample request
curl --location --request PUT 'https://uat-partner.payu.in/api/v1/merchants/{{uuid}}/update' \
--header 'Authorization: Bearer {{access_token}}' \
--form 'merchant[business_category]="Arts, Gifts & Stationery"' \
--form 'merchant[business_sub_category]="Art Dealers and Galleries"' \
--form 'merchant[monthly_expected_volume]="500000"' \
--form 'merchant[gst_number]="29ABCDE1234F1Z5"' \
--form 'merchant[gst_consent]="true"' \
--form 'merchant[business_name]="MERCHANT BUSINESS NAME"' \
--form 'merchant[cin_number]="U74999KA2020PTC123456"'Sample response
{
"merchant": {
"mid": 12345678,
"business_name": "MERCHANT BUSINESS NAME",
"status": "account_created"
}
}Step 3. Update Website/App Details
Adds the merchant website and/or app store URLs. At least one channel URL is typically required depending on how the merchant sells. For the full parameter list and Try It experience, see Update Merchant Website Details API.
Skip Website Details:If you are willing to skip updating the website details, refer to Skip Website Details API. If you skjp this step or don't update website/app, you cannot accept payments through Partner Payments or Payment Links.
HTTP Method: PUT
Environment
| URL | |
|---|---|
| Test Environment | https://uat-partner.payu.in/api/v1/merchants/{uuid}/update |
| Production Environment | https://partner.payu.in/api/v1/merchants/{uuid}/update |
Request Parameters
Header parameters
Header parameters
| Header | Description | Example |
|---|---|---|
Authorizationmandatory | string — Bearer token from Step 00 (GetToken) | Bearer {{access_token}} |
Content-Typemandatory | string — Must be multipart/form-data | multipart/form-data |
Path parameters
Path parameters
| Parameter | Description | Example |
|---|---|---|
uuidmandatory | string — Merchant UUID from Step 01 (CreateMerchant) | 11ef-d968-6b042d6c-9b94-02975f21d323 |
Body parameters
Body parameters
| Parameter | Description | Example |
|---|---|---|
merchant[website_details][website_url]conditional | string — Merchant website URL | https://www.example.com |
merchant[website_details][android_url]optional | string — Android app store URL | https://play.google.com/store/apps/details?id=com.example |
merchant[website_details][ios_url]optional | string — iOS App Store URL | https://apps.apple.com/app/example/id123456 |
Sample request
curl --location --request PUT 'https://uat-partner.payu.in/api/v1/merchants/{{uuid}}/update' \
--header 'Authorization: Bearer {{access_token}}' \
--form 'merchant[website_details][website_url]="https://www.example.com"' \
--form 'merchant[website_details][android_url]="https://play.google.com/store/apps/details?id=com.example"' \
--form 'merchant[website_details][ios_url]="https://apps.apple.com/app/example/id123456"'Sample response
{
"merchant": {
"mid": 12345678,
"status": "account_created"
}
}Step 4. Submit Signing Authority Details
Submits the authorised signatory for the merchant agreement. Complete this step before DigiLocker or Video KYC — those APIs fail if signatory details are missing. For the full parameter list and Try It experience, see Add Signatory Details API.
HTTP Method: PUT
Environment
| URL | |
|---|---|
| Test Environment | https://uat-partner.payu.in/api/v1/merchants/{uuid}/signatory_details |
| Production Environment | https://partner.payu.in/api/v1/merchants/{uuid}/signatory_details |
Request Parameters
Header parameters
Header parameters
| Header | Description | Example |
|---|---|---|
Authorizationmandatory | string — Bearer token from Step 00 (GetToken) | Bearer {{access_token}} |
Content-Typemandatory | string — Must be application/x-www-form-urlencoded | application/x-www-form-urlencoded |
Path parameters
Path parameters
| Parameter | Description | Example |
|---|---|---|
uuidmandatory | string — Merchant UUID from Step 01 (CreateMerchant) | 11ef-d968-6b042d6c-9b94-02975f21d323 |
Body parameters
Body parameters
| Parameter | Description | Example |
|---|---|---|
merchant[signatory_contact_details_attributes[0][authorised_signatory]]mandatory | string — true for the authorised signatory | true |
merchant[signatory_contact_details_attributes[0][name]]mandatory | string — Signatory full name | Signatory 1 Name |
merchant[signatory_contact_details_attributes[0][pancard_number]]mandatory | string — Signatory PAN | ABCDE1234F |
merchant[signatory_contact_details_attributes[0][email]]mandatory | string — Signatory email | [email protected] |
merchant[signatory_contact_details_attributes[0][contact_detail_type]]mandatory | string — e.g. Signing Authority | Signing Authority |
merchant[signatory_contact_details_attributes[0][cin_number]]conditional | string — CIN only for Pvt Ltd / Public Ltd / OPC | (empty for others) |
Sample request
curl --location --request PUT 'https://uat-partner.payu.in/api/v1/merchants/{{uuid}}/signatory_details' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'merchant[signatory_contact_details_attributes[0][authorised_signatory]]=true' \
--data-urlencode 'merchant[signatory_contact_details_attributes[0][name]]=Signatory 1 Name' \
--data-urlencode 'merchant[signatory_contact_details_attributes[0][pancard_number]]=ABCDE1234F' \
--data-urlencode 'merchant[signatory_contact_details_attributes[0][email]][email protected]' \
--data-urlencode 'merchant[signatory_contact_details_attributes[0][contact_detail_type]]=Signing Authority' \
--data-urlencode 'merchant[signatory_contact_details_attributes[0][cin_number]]='Sample response
{
"merchant": {
"mid": 12345678,
"status": "account_created"
}
}Step 5. Upload KYC Documents
Uploads one KYC document per required category (JPG, PNG, or PDF; max 5 MB). Call this API once for each required category. Use numeric mid from Step 1 in the path. For the full parameter list and Try It experience, see Upload KYC Document API.
HTTP Method: POST
Environment
| URL | |
|---|---|
| Test Environment | https://uat-partner.payu.in/api/v3/merchants/{mid}/kyc_document |
| Production Environment | https://partner.payu.in/api/v3/merchants/{mid}/kyc_document |
Request Parameters
Header parameters
Header parameters
| Header | Description | Example |
|---|---|---|
Authorizationmandatory | string — Bearer token from Step 00 (GetToken) | Bearer {{access_token}} |
Content-Typemandatory | string — Must be multipart/form-data | multipart/form-data |
Path parameters
Path parameters
| Parameter | Description | Example |
|---|---|---|
midmandatory | string — Numeric merchant ID (mid) from Step 01 | 8390925 |
Body parameters
Body parameters
| Parameter | Description | Example |
|---|---|---|
merchant[document_category]mandatory | string — Exact document_categories[i].name from Step 14 | PAN Card of Signing Authority |
merchant[document_type]mandatory | string — Exact document_types[j].name from Step 14 | PAN Card |
merchant[processed_document]mandatory | file — JPG/PNG/PDF, max 5 MB | pan.pdf |
Sample request
curl --location 'https://uat-partner.payu.in/api/v3/merchants/{{mid}}/kyc_document' \
--header 'Authorization: Bearer {{access_token}}' \
--form 'merchant[document_category]="PAN Card of Signing Authority"' \
--form 'merchant[document_type]="PAN Card"' \
--form 'merchant[processed_document]=@"/path/to/pan.pdf"'Sample response
{
"merchant": {
"mid": "8390925",
"kyc_document_name": "PAN Card of Signing Authority",
"kyc_document_uuid": "11ef-587e-4383...",
"kyc_document_status": "DOCUMENT_SUBMITTED",
"error_message": null,
"created_at": "2024-08-12T07:41:19.000Z"
}
}Step 6. Request E-Sign Agreement
Generates the merged merchant agreement for electronic signing. After successful e-sign, the merchant can be activated. Ensure the token includes refer_merchant and either client_manage_agreement or client_manage_kyc_details. Contact your PayU Key Account Manager (KAM) if scopes need enablement. For the full parameter list and Try It experience, see Generate Agreement for E-Sign API.
HTTP Method: GET
Environment
| URL | |
|---|---|
| Test Environment | https://uat-partner.payu.in/api/v1/merchants/{uuid}/generate_merged_document_for_esign |
| Production Environment | https://partner.payu.in/api/v1/merchants/{uuid}/generate_merged_document_for_esign |
Request Parameters
Header parameters
Header parameters
| Header | Description | Example |
|---|---|---|
Authorizationmandatory | string — Bearer token from Step 00 (GetToken) | Bearer {{access_token}} |
Acceptoptional | string — Preferred response media type | application/json |
Path parameters
Path parameters
| Parameter | Description | Example |
|---|---|---|
uuidmandatory | string — Merchant UUID from Step 01 (CreateMerchant) | 11ef-d968-6b042d6c-9b94-02975f21d323 |
Sample request
curl --location 'https://uat-partner.payu.in/api/v1/merchants/{{uuid}}/generate_merged_document_for_esign' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept: application/json'Sample response
{
"agreement_url": "https://esign.example.com/document/...",
"agreement_status": "Generated",
"message": "Agreement generated successfully"
}Step 7: Collect Payments
After you complete the steps 6, you can start collecting payments. To collect payments, you can integrate using PayU Hosted Checkout or Pre-Built Checkout or UPI S2S Checkout integration based on your requirements:
Next Steps
Refer to the APIs in the APIs used in Partner Integration for detailed API reference. After you complete the integration in the Test environment, refer to Testing and Go Live - Partner Integration.
Updated 11 days ago
