Create Child Merchant API

This section describes how to create and onboard child merchants using the Create Child Merchant API as part of the Aggregator workflow. Creating a child merchant using this API involves the following steps:

  1. Add a child merchant
  2. Update bank details.
  3. Upload Schedule C document

📘

Notes:

HTTP Method: POST

Environment

Step 1: Add child merchant

📘

Authorization:

Generate token using the Get Client Token API and pass it in header along with the following request parameters.

For the Postman collection, refer to Postman Collection. Merchant access token or client token with scope ‘refer_child_merchant’ from Hub.

Request Parameters

Parameter Description Example

product
mandatory

This parameter must be passed with the following value: "PayUBiz"

PayUBiz

name
mandatory

The display name of the child merchant

Harsh Agarwal

email
mandatory

The child merchant email.

[email protected]

mobile
mandatory

The mobile number of the child merchant

995315***1

aggregator_parent_mid
mandatory

The parent merchant MID is specified in this parameter.

7210921

merchant_type
mandatory

This parameter is used to specify the merchant type as aggregator.
Note: The value for this parameter must be posted as aggregator.

aggregator

business_entity_id
mandatory

The business entity ID of the merchant. The business entity ID and corresponding business entity is listed in the Business Entity Mapping table of this section.

2

pancard_number
mandatory

The PAN card number of the child merchant.

DBZPK4951B

pancard_name
mandatory

The name of the child merchant as in the PAN card.

kapil kumar

business_category_id
mandatory

The business category ID of the child merchant. For the list business category ID, refer to Business Category & Sub-category UUIDs List.

16

business_sub_category_id
mandatory

The business sub category ID of the child merchant. For the list business sub-category ID, refer to Business Category & Sub-category UUIDs List .
Note: Each business sub-category is dependent on business category. Hence, you must enter the sub-category according to the value you post in the business_category_id parameter.

128

gst_number
optional

The GST number of the child merchant registered with the Sales tax department.

09ABQFA5416M1ZX

monthly_expected_volume
"mandatory

The monthly expected volume of the child merchant.

60000

business_name
mandatory

The business name of the child merchant, similar to PAN.

Harsh Agarwal

Business Entity Mapping

The business entity ID (business_entity_id) and corresponding business entity mapping are:

Business Entity IDBusiness Entity
1Association of Persons
2Sole Proprietorship
3Partnership
4Private Limited
5Public Limited
6LLP
7Trust
8Society
9Government
10Hindu Undivided Family
11Local Authority
12Non Individual
13Education
14Individual
15NGO
16One Person Company
17Artificial Juridical Person

Sample request

  • Success Scenario
curl --location 'https://uat-onepayuonboarding.payu.in/api/v3/product_accounts'
\
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "product_account": {
        "product":"PayUbiz",
        "name":"Gauri Gupta",
        "email":"[email protected]",
        "mobile":"7310000001",
        "aggregator_parent_mid":"8238118",
        "merchant_type":"aggregator",
        "pancard_number":"C3718G",
        "pancard_name":"GUPTA",
        "business_entity_id":14
    }
}'
  • Failure Scenario

Token is invalid

curl --location -g --request POST 'https://uat-onepayuonboarding.payu.in/api/v3/product_accounts' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
	"merchant": {
        "product": "PayUbiz",
	"email": "[email protected]", 
	"mobile": "8860890284",
        "aggregator_parent_mid": "149726", 
        "merchant_type": "aggregator" 
	}
}'

Token has expired

curl --location -g --request POST 'https://uat-onepayuonboarding.payu.in/api/v3/product_accounts' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
	"merchant": {
        "product": "PayUbiz", // Mandatory to pass
		"email": "[email protected]", // child merchant email, mandatory
		"mobile": "8860890284", // Child merchant user mobile, mandatory
        "aggregator_parent_mid": "149726", // Parent merchant mid, mandatory
        "merchant_type": "aggregator" // Mandatory field
	}
}'

Sample Response

  • Success Scenario

Create Child Merchant Success Scenario

{
    "product_account": {
        "mid": 20000012,
        "id": 12,
        "uuid": "11ec-d682-8f22ad2c-a539-38f9d3c6b9ac",
        "identifier": 20000012,
        "product_id": 1,
        "type": "PayUbizAccount",
        "merchant_account_id": 15,
        "active": true,
        "status": null,
        "quality_score": null,
        "business_entity_id": null,
        "business_category_id": null,
        "business_sub_category_id": null,
        "business_name": "Rajat Mishra Corp",
        "pancard_name": null,
        "pancard_number": null,
        "gst_number": "07CPBPP3374Q1Z1",
        "average_delivery_time": 10,
        "notification_email": "[email protected]",
        "flag": 0,
        "settlement_status": null,
        "merchant_type": null,
        "onboarding_status": "Profile Completion in progress",
        "account_id": null,
        "temp_account_id": null,
        "pan_verification_status": "Pending",
        "admin_user_id": 2,
        "terms_and_condition_accepted_at": null,
        "generate_agreement": "312ad30b7766ec5167ae99e0",
        "agreement_status": null,
        "document_status": "Pending",
        "lob_approval_status": null,
        "created_at": "2022-05-18T08:14:37.000Z",
        "updated_at": "2022-05-18T08:14:37.000Z",
        "partner_uuid": null,
        "business_origin": null,
        "name": "Rajat Mishra",
        "email": "[email protected]",
        "first_name": "Rajat",
        "last_name": "Mishra",
        "business_type": "LongTail",
        "bank_update_attempt_count": 1,
        "merchant_vertical": null,
        "partner_source": null,
        "android_url": null,
        "ios_url": null,
        "integration_type": "Not Selected",
        "integration_status": "Not Integrated",
        "monthly_expected_volume": 100,
        "gmv_amount": null,
        "website_approval_status": null,
        "website_url": "
www.youtube.com"
,
        "website_remarks": null,
        "registered_mobile": "9582787489",
        "product": "PayUbiz",
        "bank_update_attempt_left": 10,
        "is_service_agreement_accepted": false,
        "is_service_agreement_esigned": false,
        "acl_role_name": null,
        "is_authorisation_letter_required": true,
        "saved_kyc_address": null,
        "kyc_status": {
            "status": "LOCKED",
            "kyc_status": "LOCKED"
        },
        "service_intent": "default",
        "nb_eligible": false,
        "lending_eligible": false,
        "offer_engine_enabled": false,
        "revamp_merchant": false,
        "is_cs_eligible": true,
        "onboarding_completed": false,
        "next_bank_update_time": "2022-05-18T13:44:48.000+05:30",
        "business_pan_name_match": false,
        "business_entity_uuid": null,
        "business_category_uuid": null,
        "business_sub_category_uuid": null,
        "account_uuid": null,
        "merchant_account_uuid": "11ec-d682-8e3639c4-a539-38f9d3c6b9ac",
        "product_uuid": "a12c-f114-ce1bac7d-058c-0f95d535aca3",
        "admin_user_uuid": "11eb-7bef-25b9799a-b893-02f413145cce",
        "bank_detail": {
            "id": 1,
            "branch_name": "VASTRAPUR",
            "bank_account_number": "99999999999",
            "ifsc_code": "UTIB0000032",
            "holder_name": "Tony Stark",
            "nodal_code": null,
            "nodal_status": "Not Activated",
            "active": true,
            "status": 0,
            "penny_deposit_status": "Not Initiated",
            "penny_attempt_count": 0,
            "penny_deposit_method": "IMPS",
            "bank_verification_status": "Pending",
            "uuid": "11ec-d682-8f4262de-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:38.000Z",
            "updated_at": "2022-05-18T08:14:38.000Z",
            "bank_name": "AXIS BANK",
            "bank_type": "saving",
            "addendum_status": null,
            "holder_name_by_bank": null,
            "flag": 8,
            "bank_verification_proof": null,
            "penny_attempt_left": 10,
            "bank_error_comments": {
                "error": null,
                "remarks": null
            }
        },
        "operating_address": {
            "id": 24,
            "addressable_id": null,
            "address_type": "Operating",
            "pincode": 110066,
            "city": "South West Delhi",
            "state": "DELHI",
            "address_line": "Operating, UP",
            "uuid": "11ec-d682-8f42e9d4-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:38.000Z",
            "updated_at": "2022-05-18T08:14:38.000Z",
            "addressable_type": null,
            "active": true,
            "record_id": 12,
            "record_type": "ProductAccount"
        },
        "registration_address": {
            "id": 23,
            "addressable_id": null,
            "address_type": "Registered",
            "pincode": 110066,
            "city": "South West Delhi",
            "state": "DELHI",
            "address_line": "Registered, UP",
            "uuid": "11ec-d682-8f4431c2-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:38.000Z",
            "updated_at": "2022-05-18T08:14:38.000Z",
            "addressable_type": null,
            "active": true,
            "record_id": 12,
            "record_type": "ProductAccount"
        },
        "business_entity": null,
        "product_account_statuses": [
            {
                "id": 4,
                "record_type": null,
                "record_id": null,
                "status_type": "WEBSITE",
                "status_value": null,
                "uuid": "11ec-d682-8fde098c-a539-38f9d3c6b9ac",
                "created_at": "2022-05-18T08:14:38.000Z",
                "updated_at": "2022-05-18T08:14:38.000Z",
                "product_record_id": 12,
                "product_record_type": "ProductAccount"
            },
            {
                "id": 5,
                "record_type": null,
                "record_id": null,
                "status_type": "KYC_DOCUMENTS",
                "status_value": "Pending",
                "uuid": "11ec-d682-8fe20992-a539-38f9d3c6b9ac",
                "created_at": "2022-05-18T08:14:38.000Z",
                "updated_at": "2022-05-18T08:14:38.000Z",
                "product_record_id": 12,
                "product_record_type": "ProductAccount"
            },
            {
                "id": 6,
                "record_type": null,
                "record_id": null,
                "status_type": "Agreement",
                "status_value": "Not Generated",
                "uuid": "11ec-d682-8fe60b46-a539-38f9d3c6b9ac",
                "created_at": "2022-05-18T08:14:38.000Z",
                "updated_at": "2022-05-18T08:14:38.000Z",
                "product_record_id": 12,
                "product_record_type": "ProductAccount"
            }
        ],
        "website_detail": null,
        "attached_configs": [],
        "kyc_documents": [],
        "cs_plan": null,
        "contact_details": [],
        "product_account_detail": {
            "id": 2,
            "merchant_id": null,
            "dob": null,
            "pep": null,
            "aml_flag": false,
            "uuid": "11ec-d682-8ff10d0c-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:39.000Z",
            "updated_at": "2022-05-18T08:14:39.000Z",
            "gst_addendum_status": null,
            "sign_up_ip": null,
            "max_same_day_settlement_amt": null,
            "product_account_id": 12,
            "website_url": "
www.youtube.com"
,
            "android_url": null,
            "ios_url": null,
            "integration_type": "Not Selected",
            "integration_status": "Not Integrated",
            "monthly_expected_volume": 100,
            "website_approval_status": null,
            "gmv_amount": null,
            "average_delivery_time": 10
        }
    }
}
  • Failure Scenarios

The token is invalid or expired

{
    "status": "Unauthorized"
}

The bank details are passed

{
    "errors": {
        "bank_holder_name": [
            "Bank holder name does not match either with business name or pancard name"
        ]
    },
    "error": "does not match either with business name or pancard name"
}

Step 2: Update bank details

After adding the child merchant in Step 1: Add a child merchant, update the bank details of the child merchant using the following request parameters.

📘

Reference:

Generate token using the Get Client Token API and pass it in header along with the following request parameters.

Request Parameters

Parameter Description Example

bank_detail
mandatory

The details of bank account of the child merchant is specified in the following JSON format. The details of the fields are described in the next table.
{ "bank_account_number": "6633809947434", "holder_name”:”Harsh Agarwal”, "ifsc_code": "ICIC0000031" }

📘

Authorization:

This request is using Bearer Token from the collection. For more information, refer to Postman Collection. Merchant access token or client token with scope ‘refer_child_merchant’ from Hub.

The bank_detail parameter is in a JSON parameter, and the fields in this parameter are described in the following table:

FieldDescriptionExample
bank_account_numberThe account number of the child merchant is specified in this field.6633809947434
holder_nameThe name of the child merchant who holds the account is specified in this field.Harsh Agarwal
ifsc_codeThe IFSC code of the bank branch where the child merchant has the account.ICIC0000031

Sample request

curl --location -g --request PUT '{{host}}/api/v3/product_accounts/{{product_account_uuid}}' \
--header 'Authorization: Bearer adf9092d141031a6ec1be0e297e91aff313f1c427c384cc18d747b9848a67cbf' \
--header 'Content-Type: application/json' \
--data-raw '{
    "product_account": {
        "bank_detail": {
            "bank_account_number": "123456789",
            "ifsc_code": "SBIN0010650",
            "holder_name": "ABC"
        }
    }
}'

Sample response

{
    "product_account": {
        "mid": 20000012,
        "id": 12,
        "uuid": "11ec-d682-8f22ad2c-a539-38f9d3c6b9ac",
        "identifier": 20000012,
        "product_id": 1,
        "type": "PayUbizAccount",
        "merchant_account_id": 15,
        "active": true,
        "status": null,
        "quality_score": null,
        "business_entity_id": null,
        "business_category_id": null,
        "business_sub_category_id": null,
        "business_name": "Rajat Mishra Corp",
        "pancard_name": null,
        "pancard_number": null,
        "gst_number": "07CPBPP3374Q1Z1",
        "average_delivery_time": 10,
        "notification_email": "[email protected]",
        "flag": 0,
        "settlement_status": null,
        "merchant_type": null,
        "onboarding_status": "Profile Completion in progress",
        "account_id": null,
        "temp_account_id": null,
        "pan_verification_status": "Pending",
        "admin_user_id": 2,
        "terms_and_condition_accepted_at": null,
        "generate_agreement": "312ad30b7766ec5167ae99e0",
        "agreement_status": null,
        "document_status": "Pending",
        "lob_approval_status": null,
        "created_at": "2022-05-18T08:14:37.000Z",
        "updated_at": "2022-05-18T08:14:37.000Z",
        "partner_uuid": null,
        "business_origin": null,
        "name": "Rajat Mishra",
        "email": "[email protected]",
        "first_name": "Rajat",
        "last_name": "Mishra",
        "business_type": "LongTail",
        "bank_update_attempt_count": 1,
        "merchant_vertical": null,
        "partner_source": null,
        "android_url": null,
        "ios_url": null,
        "integration_type": "Not Selected",
        "integration_status": "Not Integrated",
        "monthly_expected_volume": 100,
        "gmv_amount": null,
        "website_approval_status": null,
        "website_url": "
www.youtube.com"
,
        "website_remarks": null,
        "registered_mobile": "9582787489",
        "product": "PayUbiz",
        "bank_update_attempt_left": 10,
        "is_service_agreement_accepted": false,
        "is_service_agreement_esigned": false,
        "acl_role_name": null,
        "is_authorisation_letter_required": true,
        "saved_kyc_address": null,
        "kyc_status": {
            "status": "LOCKED",
            "kyc_status": "LOCKED"
        },
        "service_intent": "default",
        "nb_eligible": false,
        "lending_eligible": false,
        "offer_engine_enabled": false,
        "revamp_merchant": false,
        "is_cs_eligible": true,
        "onboarding_completed": false,
        "next_bank_update_time": "2022-05-18T13:44:48.000+05:30",
        "business_pan_name_match": false,
        "business_entity_uuid": null,
        "business_category_uuid": null,
        "business_sub_category_uuid": null,
        "account_uuid": null,
        "merchant_account_uuid": "11ec-d682-8e3639c4-a539-38f9d3c6b9ac",
        "product_uuid": "a12c-f114-ce1bac7d-058c-0f95d535aca3",
        "admin_user_uuid": "11eb-7bef-25b9799a-b893-02f413145cce",
        "bank_detail": {
            "id": 1,
            "branch_name": "VASTRAPUR",
            "bank_account_number": "99999999999",
            "ifsc_code": "UTIB0000032",
            "holder_name": "Tony Stark",
            "nodal_code": null,
            "nodal_status": "Not Activated",
            "active": true,
            "status": 0,
            "penny_deposit_status": "Not Initiated",
            "penny_attempt_count": 0,
            "penny_deposit_method": "IMPS",
            "bank_verification_status": "Pending",
            "uuid": "11ec-d682-8f4262de-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:38.000Z",
            "updated_at": "2022-05-18T08:14:38.000Z",
            "bank_name": "AXIS BANK",
            "bank_type": "saving",
            "addendum_status": null,
            "holder_name_by_bank": null,
            "flag": 8,
            "bank_verification_proof": null,
            "penny_attempt_left": 10,
            "bank_error_comments": {
                "error": null,
                "remarks": null
            }
        },
        "operating_address": {
            "id": 24,
            "addressable_id": null,
            "address_type": "Operating",
            "pincode": 110066,
            "city": "South West Delhi",
            "state": "DELHI",
            "address_line": "Operating, UP",
            "uuid": "11ec-d682-8f42e9d4-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:38.000Z",
            "updated_at": "2022-05-18T08:14:38.000Z",
            "addressable_type": null,
            "active": true,
            "record_id": 12,
            "record_type": "ProductAccount"
        },
        "registration_address": {
            "id": 23,
            "addressable_id": null,
            "address_type": "Registered",
            "pincode": 110066,
            "city": "South West Delhi",
            "state": "DELHI",
            "address_line": "Registered, UP",
            "uuid": "11ec-d682-8f4431c2-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:38.000Z",
            "updated_at": "2022-05-18T08:14:38.000Z",
            "addressable_type": null,
            "active": true,
            "record_id": 12,
            "record_type": "ProductAccount"
        },
        "business_entity": null,
        "product_account_statuses": [
            {
                "id": 4,
                "record_type": null,
                "record_id": null,
                "status_type": "WEBSITE",
                "status_value": null,
                "uuid": "11ec-d682-8fde098c-a539-38f9d3c6b9ac",
                "created_at": "2022-05-18T08:14:38.000Z",
                "updated_at": "2022-05-18T08:14:38.000Z",
                "product_record_id": 12,
                "product_record_type": "ProductAccount"
            },
            {
                "id": 5,
                "record_type": null,
                "record_id": null,
                "status_type": "KYC_DOCUMENTS",
                "status_value": "Pending",
                "uuid": "11ec-d682-8fe20992-a539-38f9d3c6b9ac",
                "created_at": "2022-05-18T08:14:38.000Z",
                "updated_at": "2022-05-18T08:14:38.000Z",
                "product_record_id": 12,
                "product_record_type": "ProductAccount"
            },
            {
                "id": 6,
                "record_type": null,
                "record_id": null,
                "status_type": "Agreement",
                "status_value": "Not Generated",
                "uuid": "11ec-d682-8fe60b46-a539-38f9d3c6b9ac",
                "created_at": "2022-05-18T08:14:38.000Z",
                "updated_at": "2022-05-18T08:14:38.000Z",
                "product_record_id": 12,
                "product_record_type": "ProductAccount"
            }
        ],
        "website_detail": null,
        "attached_configs": [],
        "kyc_documents": [],
        "cs_plan": null,
        "contact_details": [],
        "product_account_detail": {
            "id": 2,
            "merchant_id": null,
            "dob": null,
            "pep": null,
            "aml_flag": false,
            "uuid": "11ec-d682-8ff10d0c-a539-38f9d3c6b9ac",
            "created_at": "2022-05-18T08:14:39.000Z",
            "updated_at": "2022-05-18T08:14:39.000Z",
            "gst_addendum_status": null,
            "sign_up_ip": null,
            "max_same_day_settlement_amt": null,
            "product_account_id": 12,
            "website_url": "
www.youtube.com"
,
            "android_url": null,
            "ios_url": null,
            "integration_type": "Not Selected",
            "integration_status": "Not Integrated",
            "monthly_expected_volume": 100,
            "website_approval_status": null,
            "gmv_amount": null,
            "average_delivery_time": 10
        }
    }
}

Step 3: Upload Schedule C document

After you add a child merchant, you must upload the Schedule C document for the child merchant. For more information on how to upload the Schedule C document of the child merchant, refer to Add a Sub-Account.