post https://mercury-uat.phonepe.com/v1/submerchant
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” |
{
"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 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. |
{
"success": true,
"code": "SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"subMerchantId": "AB2109241742371166038076",
"aggregatorSubMerchantId": "12d4223c-7713-4676-b242-ecc47ed329a1"
}
}
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”: } |