Create Sub-merchant API

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

Request Headers

Field Name

Value

X-Verify

SHA256(base64 encoded payload + "/v1/submerchant" + salt key) + ### + salt index

Content-Type

“application/json”

Request Parameters

Field name

Mandatory

Data Type

Comments

merchantId

Yes

String

Merchant-id of the aggregator

fullName

Yes

String

CBS name of the sub-merchant

displayName

Yes

String

Display name of the sub-merchant

mcc

Yes

String

4-character MCC code of sub-merchant

websiteUrl

No

String

Website URL of the sub-merchant

externalMerchantType

Yes

Enum

Either “OFFLINE” or “ONLINE”

externalOnboardingType

Yes

Enum

Will be “AGGREGATORS” only, for now

phoneNumber

No

String

Phone number of the sub-merchant

email

No

String

Email of the sub-merchant

address

No

Json Object

Address of the sub-merchant. It will be a json object with following subfields:
{ "building": ,
"street": ,
"area": ,
"locality": ,
"city": ,
"state": ,
"country": ,
"pinCode": ,
"landmark":
}

aggregatorSubMerchantId

Yes

String

Uniqueness check for sub-merchant in this API call. Not to be used for other API calls.

Response

Case

Response 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!