Create Sub-merchant API

This API endpoint can be used by aggregators to onboard a new sub-merchant.

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”:
}
Language
Click Try It! to start a request and see the response here!