Create Sub-merchant API
post https://api-preprod.phonepe.com/apis/pg-sandbox/v1/submerchant

Request Headers

Field NameValue
X-VerifySHA256(base64 encoded payload + “/v1/submerchant” + salt key) + ### + salt index
Content-Type“application/json”
{ "merchantId": "MERCHANTUAT", "fullName": "CBS NAME", "displayName": "Merchant Name", "mcc": "8XXX", "websiteUrl": "www.merchant.com", "externalMerchantType": "ONLINE", "externalOnboardingType": "AGGREGATORS", "aggregatorSubMerchantId": "12d4223c-7713-4676-b242-ecc47ed329a1" }

Request Parameters

Field nameMandatoryData TypeComments
merchantIdYesStringMerchant-id of the aggregator
fullNameYesStringCBS name of the sub-merchant
displayNameYesStringDisplay name of the sub-merchant
mccYesString4-character MCC code of sub-merchant
websiteUrlNoStringWebsite URL of the sub-merchant
externalMerchantTypeYesEnumEither “OFFLINE” or “ONLINE”
externalOnboardingTypeYesEnumWill be “AGGREGATORS” only, for now
phoneNumberNoStringPhone number of the sub-merchant
emailNoStringEmail of the sub-merchant
addressNoJson ObjectAddress of the sub-merchant. It will be a json object with following subfields:
{ “building”: ,
“street”: ,
“area”: ,
“locality”: ,
“city”: ,
“state”: ,
“country”: ,
“pinCode”: ,
“landmark”:
}
aggregatorSubMerchantIdYesStringUniqueness check for sub-merchant in this API call. Not to be used for other API calls.
{ "success": true, "code": "SUCCESS", "message": "Your request has been successfully completed.", "data": { "merchantId": "MERCHANTUAT", "subMerchantId": "AB2109241742371166038076", "aggregatorSubMerchantId": "12d4223c-7713-4676-b242-ecc47ed329a1" } }

Response

CaseResponse Code & Body
Success, if all the information is valid & the new sub-merchant is successfully onboarded.HTTP Code: 200
{
“success”: true,
“code”: “SUCCESS”,
“message”: “Your request has been successfully completed.”,
“data”: {
“merchantId”: “UATMERCHANT”,
“subMerchantId”: “AB2109241742371166038076”, // Generated by PhonePe
“aggregatorSubMerchantId”: “12d4223c-7713-4676-b242-ecc47ed329a1” // Generated by Aggregator
}
}
Bad request, if any mandatory field of the request or the X-Verify authorization header is missing or invalid.HTTP Code: 400
{
“success”: false,
“code”: “BAD_REQUEST”,
“message”:
}
Invalid mcc, if the given mcc onboarding is not allowed by PhonePe.HTTP Code: 400
{
“success”: false,
“code”: “INVALID_MCC”,
“message”: “This mcc onboarding is not allowed by PhonePe.”
}
Duplicate request if this sub-merchant has already been onboarded. (This will be verified using the uniqueId parameter provided in the request.)HTTP Code: 400
{
“success”: false,
“code”: “SUBMERCHANT_ALREADY_EXISTS”,
“message”: “The sub-merchant already exists.”,
“data”:
{ “merchantId”: ,
“subMerchantId”: , // gen by PhonePe
“aggregatorSubMerchantId”: // gen by Agg
}
}
Unauthorized, if the X-Verify authorization header is missing or invalid, or if the aggregator is not authorized to perform the operation.HTTP Code: 401
{
“success”: false,
“code”: “AUTHORIZATION_FAILED”,
“message”:
}
{“method”:”post”,”url”:”/v1/submerchant”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”merchantId\”: \”UATMERCHANT\”,\n \”subMerchantId\”: \”AB2109241742371166038076\”,\n \”aggregatorSubMerchantId\”: \”12d4223c-7713-4676-b242-ecc47ed329a1\”\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”615bec64b33794007b9512ec”},{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”615bec64b33794007b9512eb”},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v1/submerchant\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”615bec64b33794007b9512ea”}],”examples”:{“codes”:[]},”apiSetting”:”5a1563aec32b6d002a16fb67″}
https://api-preprod.phonepe.com/apis/pg-sandbox

HEADERS
Content-Type string required
X-VERIFY string required
SHA256(base64 encoded payload + "/v1/submerchant" + salt key) + ### + salt index

BODY PARAMS
request string required
base64 encoded payload

RESPONSES
Code 200
200
Code 400
400