Integration Guide: From Onboarding to Go-Live

This guide covers the full journey for integrating PhonePe In-store Payments: how your integration request is raised, receiving documentation and UAT credentials, building and testing your integration, UAT sign-off, receiving production credentials, and going live. It also shows which steps you own and which ones PhonePe owns.

Need help at any stage? Email [email protected].

Available Solutions

Solution	Best for
Dynamic QR (DQR)	Showing a QR with a fixed amount for each bill
Collect Call	Sending a payment request to the customer’s PhonePe app using their mobile number
Paylink	Sending a payment link to the customer
Integrated Static QR (ISQR)	A fixed QR at the counter, with payments matched to bills through APIs (pull) or callbacks (push)
Integrated EDC	Card and QR payments on a PhonePe EDC terminal linked to your billing system
Single Suite API	One API for PhonePe EDC terminals and DQR devices
Static QR Generation	Creating and managing static QRs through APIs (subject to PhonePe business approval)
Refunds	Refunding completed payments through the API or the PhonePe Business Dashboard

API documentation by solution:

Dynamic QR: Intent Init API (solutionType: DQR), Check Status API, Cancel Payment API, Callback API, FAQs
Collect Call: Intent Init API (solutionType: CHARGE), Check Status API, Cancel Payment API, Callback API, FAQs
Paylink: Intent Init API (solutionType: PAY_LINK), Check Status API, Cancel Payment API, Callback API
Integrated Static QR: pull: Transaction List API, Metadata API; push: Static QR Server to Server Callback; FAQs
Integrated EDC: EDC Sale Request API, EDC StatusCheck API, EDC UAT Testing
Single Suite API: Payment Init API, Transaction Cancel API, External Status API
Static QR Generation: StaticQR Init API
Refunds: Refund API, Refund Status API

The Journey at a Glance

Step	What happens	Owner	Turnaround
1. Integration request	Your PhonePe account manager raises the integration request on your behalf	PhonePe account manager	–
2. Documentation email	You receive an email with the API documentation and UAT testing steps for your solution(s)	PhonePe Integration Team	Automatic, once the request is raised
3. UAT credentials	You reply on the same email thread; PhonePe sends your UAT credentials (and a test static QR for ISQR)	You, then PhonePe Integration Team	Within 24 hours of your reply
4. UAT setup	Configure environments, authentication and the Simulator app	You	–
5. Build	Integrate the APIs for your solution	You	–
6. Test in UAT	Test success, failure and fallback scenarios	You	–
7. UAT demo and sign-off	Demo your integration to PhonePe	You and PhonePe Integration Team	Sign-off within 24 hours of a successful demo
8. Production credentials	PhonePe generates production keys for your live Merchant ID	PhonePe	–
9. Go live	Switch to production and validate	You	–
10. After go-live	Monitor, reconcile, troubleshoot	You, with PhonePe support & Integration Team	–

Step 1: Integration Request (Raised by Your Account Manager)

You don’t need to apply anywhere yourself. After you have discussed your requirements with your PhonePe account manager, they raise the integration request with the PhonePe integration team on your behalf.

Your account manager will ask you for these details, so keep them ready:

Detail	Notes
Business name	Legal or brand name
Technical contact email	Receives the documentation email, credentials and all integration communication
Business use case	A short description of how you will accept payments
Solution(s)	Dynamic QR, Collect Call, Paylink, Integrated Static QR, Integrated EDC, Refund API
Callback requirement	Static callback: one URL registered by PhonePe for your Merchant ID or Provider ID. Dynamic callback: you send the URL with each request in the `X-CALLBACK-URL` header, where the API supports it. Or no callback, using status APIs only.
Refunds	Through the Refund API, or through the PhonePe Business Dashboard
Integration model	Direct: you integrate for your own Merchant ID. Provider or Aggregator: you are a POS or billing provider integrating on behalf of one or more merchants.

Step 2: Receive the Documentation Email

Once your account manager raises the request, your technical contact receives an email from PhonePe containing:

API documentation links for each solution requested (the same links as in Available Solutions above).
Step-by-step UAT testing instructions for each solution (also listed in Step 6 below).
The PhonePe integration support contact.

If you don’t receive this email, check your spam folder, then contact your account manager.

Step 3: Request and Receive UAT Credentials

To get UAT credentials, reply on the same email thread. UAT credentials are created and shared by the PhonePe integration team; you can’t generate them yourself. You will receive them on that thread within 24 hours of your reply.

Credential	Description
`merchantId`	Your UAT Merchant ID
`saltKey`	Secret key used to build the `X-VERIFY` header. For the Provider or Aggregator model, this is the provider’s salt key.
`saltIndex`	Index of the salt key, appended to `X-VERIFY`
`providerId`	Provider or Aggregator model only. Sent in the `X-PROVIDER-ID` header.
`storeId`	Test store ID
`terminalId`	Test terminal ID

Integrated Static QR: you also receive a test static QR code.
Integrated EDC: you also receive a Postman collection, including test APIs to simulate card and QR payment results. See EDC UAT Testing.

Step 4: Set Up Your UAT Environment

Environments

Environment	Base URL	Credentials
UAT	`https://mercury-uat.phonepe.com/enterprise-sandbox`	UAT credentials only
Production	`https://mercury-t2.phonepe.com`	Production credentials only

UAT and production are fully separate. UAT credentials, Merchant IDs and transactions don’t work in production, and the reverse is also true.

Authentication (X-VERIFY)

Every API request needs an X-VERIFY header. For POST requests, the JSON payload is Base64 encoded and sent as {"request": "<base64>"}.

X-VERIFY Header

POST (with body):
X-VERIFY = SHA256(base64EncodedPayload + apiPath + saltKey) + "###" + saltIndex

GET / PUT (without body):
X-VERIFY = SHA256(apiPath + saltKey) + "###" + saltIndex

apiPath example: /v3/transaction/{merchantId}/{transactionId}/status

Provider or Aggregator model: also send X-PROVIDER-ID, and use the provider’s salt key in X-VERIFY.
Common mistakes: using the merchant salt instead of the provider salt; leaving out ###saltIndex; hashing a different path from the one called; using UAT keys in production.

PhonePe Simulator App (Dynamic QR, Static QR, Collect Call, Paylink)

All UAT payments for Dynamic QR, Integrated Static QR, Collect Call and Paylink must be made with the PhonePe Simulator app. Live apps such as PhonePe, Google Pay or Paytm don’t work in UAT.
Install it by following Getting Started With Your API. It is available for Android only. iOS payment flows can be tested in production.
On first use, tap Scan & Pay, enter a VPA in the format <yourMobileNumber>@ybl, and tap Confirm VPA.
Integrated EDC is tested with the Postman collection instead (see Step 3).

Callbacks

Static callback: share your HTTPS callback URL with the integration team (on the same email thread) so it can be registered for your Merchant ID or Provider ID. Callback URLs are registered separately for UAT and production.
Dynamic callback (Dynamic QR, Collect Call, Paylink): alternatively, pass your callback URL in the X-CALLBACK-URL header of each request.
Integrated Static QR (push): a registered callback URL is required.
If no callback URL is registered or passed, no callbacks are sent. This includes EDC. Your integration must then rely on the status APIs.

Step 5: Build Your Integration

Every integration, whatever the solution, must include:

Payment request API for your solution (for example, Intent Init, EDC Sale, or Payment Init).
Status API, used as the source of truth. It is mandatory even if you use callbacks.
Callback handling (if used): verify X-VERIFY, return HTTP 200 quickly, and handle duplicate callbacks safely.
Cancel API, where your solution supports it.
Refund API, if you are not using the Business Dashboard for refunds.
Fallback handling for a missed callback, a pending status, or a 5xx response from the status API. See Troubleshooting: Callback & Payment Status.

Mandatory Security Requirements

Store your Merchant ID, salt key, salt index and API endpoints on your server only.
Call all PhonePe APIs from your backend, never from the POS app, browser or mobile app.
Build the X-VERIFY checksum and the Base64 request on the server side. Never expose this logic to the client.
Always pass storeId in the request body where the API supports it.
Use a new, unique transaction ID for every payment request. Never reuse one, even after a timeout.

Step 6: Test in UAT

Integrated Static QR

Install the PhonePe Simulator app (see Step 4).
Use the test static QR code shared by the PhonePe Integration team.
Scan the static QR with the Simulator app and complete the payment.
Capture the payment:
Option A (pull): call the Transaction List API with merchantId and storeId, then match the payment using the amount and the last 4 digits of the UTR or transaction ID.
Option B (push): share your server URL with the PhonePe team so callbacks can be set up for your Merchant ID.

Dynamic QR

Install the PhonePe Simulator app (see Step 4).
Generate a dynamic QR by calling the UAT Intent Init API with solutionType set to DQR.
Scan the generated QR with the Simulator app and complete the payment.
Capture the payment:
Option A: call the Check Status API with merchantId and transactionId as path parameters.
Option B: receive callbacks, either by sharing your server URL for your Merchant ID or by sending it in the X-CALLBACK-URL header.

Paylink

Install the PhonePe Simulator app (see Step 4).
Generate a Paylink by calling the UAT Intent Init API with solutionType set to PAY_LINK (customer phone number required).
Copy the upiIntent value from the API response and send it to the Android device with the Simulator app installed. Open the link; it opens the Simulator app, where you complete the payment.
Capture the payment with the Check Status API or callbacks, as for Dynamic QR.

Collect Call

Install the PhonePe Simulator app and register it with your mobile number (see Step 4).
Raise a collect request by calling the UAT Intent Init API with solutionType set to CHARGE, passing that mobile number as the customer phone number.
Open the payment request in the Simulator app and complete the payment.
Capture the payment with the Check Status API or callbacks, as for Dynamic QR.

Integrated EDC

Follow EDC UAT Testing using the Postman collection shared with your credentials.

Refunds

After a successful UAT payment, call the Refund API, then confirm the result with the Refund Status API.

Scenarios to Test Before Your Demo

Scenario	Expected behaviour in your system
Successful payment	Order marked paid after a success status from the callback or status API
Failed or declined payment	Order marked failed; customer can retry with a new transaction ID
Customer doesn’t pay before expiry	Order marked failed or expired after the final status check
Payment pending	Order stays pending; the system keeps checking status and doesn’t create a new request
Callback not received	Status API used as a fallback; correct final status recorded
Duplicate callback	Handled once; no duplicate order update
Status API returns 5xx	Status check retried after a few seconds; no change to the order
Payment request times out	Status checked with the same transaction ID before any new request
Reused transaction ID	Rejected by PhonePe; your system always generates unique IDs
Cancel a pending request (if supported)	Request cancelled; order updated
Full and partial refund (if using the Refund API)	Refund status checked; no duplicate refund sent while pending

The integration team will confirm any additional scenarios that apply to your solution.

Step 7: UAT Demo and Sign-off

When your integration is complete, reply on the same email thread to schedule a UAT demo.
During the demo, you run the success and failure scenarios on your application in UAT. PhonePe checks your integration and confirms that fallbacks are in place for missed callbacks, pending payments and status API errors.
If changes are needed, PhonePe shares feedback, and you fix and re-demo the affected scenarios.
When all scenarios pass, PhonePe issues UAT sign-off within 24 hours of the successful demo.

Step 8: Receive Production Credentials

Your production Merchant ID is activated through PhonePe’s merchant onboarding process. Your account manager/Onboarding Team will confirm when this is done.
PhonePe generates your production salt key and salt index within 24 hours of the production Merchant ID being activated.
You will receive an automated email from [email protected] containing the production salt key and salt index. Store them securely on your server.
The integration team will email you the UAT sign-off confirmation and the production API URLs.

For the Provider or Aggregator model, production keys are created for your Provider ID, and each merchant’s Merchant ID is mapped to it by PhonePe. Depending on your solution, PhonePe also configures your production callback URL, and settings such as UTR or bank details in callbacks, refund enablement, and the metadata schema for Integrated Static QR.

Step 9: Go Live

Production readiness checklist:

Production base URL configured: https://mercury-t2.phonepe.com
Production Merchant ID, salt key and salt index in place; no UAT values left in configuration
X-PROVIDER-ID set to your production Provider ID (Provider or Aggregator model)
Production callback URL shared with PhonePe and reachable over HTTPS (if using static callbacks)
Status API fallback and polling active
Credentials stored server-side only; all API calls made from your backend
A first low-value live transaction completed end to end (payment, status and callback), and a refund tested if applicable

Step 10: After Go-Live

Monitor: Watch for transactions stuck in pending and for failed callbacks on your server.
Reconcile: Use the status APIs and the Comprehensive Transaction Recon API to match PhonePe transactions with your orders.
Troubleshoot: See Troubleshooting: Callback & Payment Status.
New Merchant IDs or stores: Ask your account manager. The integration team then sets up keys, provider mapping and callbacks for the new Merchant ID.
Key rotation: If you suspect your salt key has been exposed, email the integration team right away to deactivate it and issue a new one.

Getting Help

Email [email protected], or reply on your integration email thread, with these details:

Issue Report Template

Environment:            UAT / Production
Solution and API:
Merchant ID:
Provider ID (if any):
Sample transaction ID(s):
Time of issue:          date, time and timezone
HTTP status and code:
errorId (if present):   from the "message" field
Request and response:   with the salt key and X-VERIFY removed
Screenshot of the error (if any):
What you expected:
What happened:

Never share your salt key, full card numbers or PINs. PhonePe will never ask for your salt key.