General FAQs

This API document describes the API endpoints that can be used by aggregators to onboard new sub-merchants or fetch information of already onboarded sub-merchants.

## Prerequisites

This API documentation assumes the following prerequisites:

● Aggregators can continue using one of the existing PhonePe generated merchant-ids.

● Aggregators would need to share the merchant-id with PhonePe to obtain a **new salt key for the sub-merchant on-boarding APIs**.

● These keys will be distinct from the salt keys used for transactional APIs like debit, status, refund, etc., and will not work for transactional operations.

● All request/response payloads are Base64 encoded.

● All requests contain a checksum in the form of X-VERIFY header, calculated as follows:

  • SHA256(base64 encoded payload + api endpoint + salt key) + ### + salt index

  • e.g. For the “Create Sub-merchant API”, it will be SHA256 (base64 encoded payload + "/v1/submerchant" + salt key ) + ### + salt index.

● Aggregators should provide their list of IPs for whitelisting at PhonePe

● Behavior for already onboarded sub-merchants:

  • These were onboarded using the aggregator-generated sub-merchant-ids.

  • Same should be passed by the aggregator for the ‘Read Sub-merchant API’, debit flow, refund flow, etc.

● Behavior for newly onboarded sub-merchants:

  • During the ‘Create Sub-merchant API’ flow, PhonePe will generate new sub-merchant-id and return them in the response.

  • These PhonePe-generated sub-merchant-ids should be passed by the aggregators for the ‘Read Sub-merchant API’, debit flow, refund flow, etc.

● When should aggregators onboard a sub-merchant with PhonePe?

  • Aggregators Onboarding is complete

  • Aggregators Document verification is complete

  • Aggregator is ready to accept Sub-merchant’s Production transaction

● How can aggregators update details for an already onboarded sub-merchant?

  • This is an operational process in phase 1. Based on the volume of update requests for now

  • Existing process can be followed up.

● A list of MCC is not allowed to be onboarded with PhonePe systems. These will be blocked by PhonePe

● The liability of correct data and MCC mapping lies with Aggregators

● The aggregators must be a licensed PA or should have applied for the PA license