post
https://test-partner.payu.in/api/v3/merchants
CreateMerchant — Step 01 of 16
Creates a new merchant shell account on PayU.
Endpoint
POST /api/v3/merchants
Prerequisite Steps
- Step 00: Valid bearer token with
refer_merchantscope
Entity Applicability
All entities
Request Body (form-data)
| Parameter | Type | Required | Validation | Description |
|---|---|---|---|---|
merchant[display_name] | string | Yes | Non-empty | Business or display name |
merchant[email] | string | Yes | Valid email, unique across PayU | Merchant email |
merchant[mobile] | string | Yes | Exactly 10 digits | Indian mobile number |
merchant[business_details][business_entity_type] | string | Yes | From allowed list | Business entity type |
merchant[business_details][business_entity_type] | string | Yes | From allowed list | Entity type — determines downstream flow |
merchant[product] | string | Yes | Must be PayUbiz | PayU product type — required to avoid backend error |
IMPORTANT: merchant[product]=PayUbiz is REQUIRED. Omitting it causes a backend MySQL duplicate entry error in the test environment.
Response (200 OK)
{
"mid": 12345678,
"uuid": "11ef-d968-6b042d6c-9b94-02975f21d323",
"product_account_uuid": "11ef-d968-6b042d6c-9b94-02975f21d323"
}Response-to-Request Mapping
| Response Field | Format | Used In Steps |
|---|---|---|
mid | Numeric (e.g., 12345678) | Steps 06, 09, 14, 15 — KYC document APIs use {mid} in URL path |
uuid | UUID string | Steps 02, 04, 05, 07, 08, 10, 12 — Update/signatory APIs use {uuid} in URL path |
product_account_uuid | UUID string | Step 16 — E-Sign API uses this in URL path |
Error Handling
| Error Code | Cause | Recovery |
|---|---|---|
422 - "Email has already been taken" | Duplicate email | Use a different email or retrieve existing merchant |
422 - "Mobile is invalid" | Not 10 digits | Fix mobile format |
401 | Token expired or invalid | Re-authenticate via Step 00 |
Response Fields (200 OK)
| Field | Type | Description | Used In |
|---|---|---|---|
merchant.mid | integer | Numeric merchant ID | Steps 06, 09, 14, 15 (URL path {mid}) |
merchant.uuid | string | Merchant UUID | Steps 02, 04, 05, 07, 08, 10, 12 (URL path {uuid}) |
merchant.email | string | Registered email | — |
merchant.registered_mobile | string | Registered mobile | — |
merchant.product | string | PayU product (PayUbiz) | — |
merchant.business_type | string | Business classification (LongTail) | — |
merchant.business_entity | string | Entity type set at creation | Determines downstream flow |
merchant.status | string | Onboarding status: account_created initially | Poll via GetMerchant |
merchant.partner_source | string | Always Create Merchant API for API-created merchants | — |
merchant.pan_verification_status | string | Pending initially → Success / Failed after Step 02 | Check before Step 03 |
merchant.bank_verification_status | string | null initially → set after Step 05 | Determines Step 06 |
merchant.kyc_status.kyc_status | string | LOCKED initially → COMPLETED after KYC done | — |
merchant.kyc_status.ckyc_status | string | PENDING initially → COMPLETED after Step 03 | Determines Step 09 |
merchant.agreement_status | string | Not Generated initially → Approved after Step 16 | — |
merchant.vkyc_status | string | pending → link_generated → approved / declined | — |
merchant.digilocker_status | string | null → link_generated → approved | — |
merchant.document_status | string | Pending → tracks KYC document upload progress | — |
merchant.settlement_status | string | null → Active once merchant is live | — |
merchant.is_authorisation_letter_required | boolean | true for non-individual entities | Affects Step 14 docs |
merchant.blocked | boolean | Whether merchant is blocked | — |
merchant.skip_vkyc_eligible | boolean | Whether VKYC can be skipped | Step 11 |
merchant.ckyc_skipped | boolean | Whether CKYC was skipped | Affects Step 09 DigiLocker |
merchant.service_intent | string | Service intent (default) | — |
Next Step
Proceed to Step 02 — Update merchant with PAN, DOB, and business entity type.