PhonePe Payment Gateway API (PG v2)
PhonePe PG v2: O-Bearer token, Standard Checkout payments, order status, refunds, UPI collect/QR/intent and payment links.
PaymentsGuided#payments#upi#india#refunds#payment-links#checkout
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
PhonePe Payment Gateway (PhonePe PG) lets Indian businesses take UPI, cards, net banking and wallet payments. This guided collection covers the current PG v2 APIs: an OAuth client-credentials token, Standard Checkout (PhonePe-hosted payment page), order status, refunds, the mobile SDK order token, Custom Checkout (UPI collect, QR and intent on your own UI) and payment links.
Get credentials
- Sign up as a merchant at business.phonepe.com and complete onboarding (KYC is needed for production).
- In the PhonePe Business Dashboard turn Test Mode on, open Developer Settings and copy the Client ID, Client Version and Client Secret for sandbox. Turn Test Mode off to see production keys.
- Paste them into the secret variables
clientId,clientSecretandclientVersion. - Set
redirectUrlto a page on your site (it only tells you the customer came back; it is not proof of payment).
Authentication
POST /v1/oauth/token (form-encoded, grant_type=client_credentials) returns access_token with an expires_at time. Send it on every call as Authorization: O-Bearer <token> (this collection does that from accessToken). Fetch a new token before it expires. Partner/platform integrations must also send X-MERCHANT-ID with the end merchant's ID.
Base URLs (sandbox first)
| Environment | authUrl (token) | baseUrl (everything else) |
|---|---|---|
| Sandbox | https://api-preprod.phonepe.com/apis/pg-sandbox | https://api-preprod.phonepe.com/apis/pg-sandbox |
| Production | https://api.phonepe.com/apis/identity-manager | https://api.phonepe.com/apis/pg |
Run order
- 1. Start here: get a token.
- 2. Standard Checkout: create a payment, open
checkoutUrlin a browser, pay with a sandbox instrument, then check order status. - 3. Refunds on a completed order. Folders 4-6 are optional: mobile SDK, Custom Checkout (must be enabled on your account) and payment links.
IDs (merchantOrderId, merchantRefundId, paylinkOrderId) are generated by pre-request scripts, so every send is a new order.
Testing in sandbox
Sandbox amounts must be between Rs 1 and Rs 1000. Cards and net banking redirect to a simulator page where you choose Success, Failure or Pending (bank OTP 123456, net banking bank SBIN with user/password test). For UPI intent and collect, install the PhonePe Test app and configure a result template. See UAT sandbox.
Webhooks
Configure them in Dashboard > Developer Settings > Webhook. Events: checkout.order.completed, checkout.order.failed, pg.refund.completed, pg.refund.failed. Verify either the HMAC checksum headers or the SHA-256 of your configured username:password in Authorization, answer 2xx within a few seconds, and treat duplicates idempotently. Use event and payload.state.
Common errors
| Code | Meaning / fix |
|---|---|
401 | Token missing, expired or from the other environment; fetch a new one |
400 BAD_REQUEST | Invalid body, or merchantOrderId reused |
INVALID_MERCHANT_ORDER_ID | No order with that ID in this environment |
500 in sandbox custom flows | Test app template not configured |
Order FAILED, errorCode e.g. INVALID_MPIN | Customer-side failure; see errorContext |
Older API
The earlier PG v1 API (/pg/v1/pay with an X-VERIFY SHA-256 checksum built from a salt key) is no longer documented: its old reference pages now redirect to the v2 docs. Build new integrations on v2 as in this collection.
Links
- Standard Checkout integration steps
- API reference: authorization
- Error codes
- Payment links API
- Pricing (MDR) is agreed per merchant; see phonepe.com/business-solutions/payment-gateway.
Endpoints 18
1. Start here
- POSTGet an access token (O-Bearer)
{{authUrl}}/v1/oauth/tokenExchanges your client ID, client version and client secret for an access token using the OAuth client-credentials grant. Every other request in this…
2. Standard Checkout
- POSTCreate a payment (Standard Checkout)
/checkout/v2/payCreates a checkout order and returns the PhonePe-hosted payment page URL. Send the customer's browser to redirectUrl (or open it in the iframe PayPage); after… - POSTCreate a payment showing only some methods
/checkout/v2/paySame call as Create a payment, plus paymentFlow.paymentModeConfig to limit which methods the checkout page shows for this one order. This example uses the V2… - POSTCreate a payment with the customer's phone prefilled
/checkout/v2/payCreates a Standard Checkout order and passes prefillUserLoginDetails.phoneNumber so the PhonePe login step already shows the customer's mobile number. Useful… - GETCheck order status
/checkout/v2/order/{{merchantOrderId}}/statusReturns the order's current state (PENDING, COMPLETED or FAILED) and its payment attempts. Call it when the customer returns to your redirect URL, and keep… - GETCheck order status with every attempt
/checkout/v2/order/{{merchantOrderId}}/statusSame status call with details=true, so paymentDetails lists every attempt on the order (a customer may fail with one UPI app and succeed with a card). Use it…
3. Refunds
- POSTRefund an order
/payments/v2/refundStarts a full or partial refund against a completed order. originalMerchantOrderId is your merchantOrderId from the paid order; the pre-request script creates… - GETCheck refund status
/payments/v2/refund/{{merchantRefundId}}/statusReturns a refund's state (PENDING, COMPLETED or FAILED) by your merchantRefundId. A completed UPI refund lists the UTR under splitInstruments[].rail; a failed…
4. Mobile SDK
- POSTCreate an order token for the mobile SDK
/checkout/v2/sdk/orderFor Android, iOS, Flutter or React Native apps: your backend creates the order here and passes the returned token (with orderId) to the PhonePe SDK in the…
5. Custom Checkout (UPI on your own UI)
- POSTValidate a UPI ID (custom checkout)
/v2/validate/upiChecks whether a VPA or UPI number can receive a collect request, before you raise one. Custom Checkout APIs must be enabled on your account. Send type: VPA… - POSTRaise a UPI collect request (custom checkout)
/payments/v2/payCustom Checkout: sends a collect request to the customer's UPI ID; they approve it in their UPI app. Uses /payments/v2/pay with paymentFlow.type: PG and… - POSTCreate a UPI QR (custom checkout)
/payments/v2/payCustom Checkout: creates an order paid by scanning a dynamic UPI QR. Render qrData as a QR code on your own page (or use intentUrl on mobile). In sandbox,… - POSTStart a UPI intent payment on Android (custom checkout)
/payments/v2/payCustom Checkout: returns an intentUrl your Android app opens with the UPI app the customer picked. deviceContext.deviceOS is ANDROID here, and… - GETCheck order status (custom checkout)
/payments/v2/order/{{merchantOrderId}}/statusStatus for orders created through /payments/v2/pay (collect, QR, intent, card, net banking). Same response shape and details / errorContext query options as…
6. Payment links
- POSTCreate a payment link
/paylinks/v1/payCreates a shareable link (paylinkUrl, on phon.pe) for collecting money without a website checkout, for example over chat or invoices. The pre-request script… - GETCheck payment link status
/paylinks/v1/{{paylinkOrderId}}/statusReturns the link's state: ACTIVE (no successful payment yet), COMPLETED, FAILED, EXPIRED or CANCELLED, with paymentDetails for each attempt. details=true… - POSTResend a payment link by SMS or email
/paylinks/v1/notifyAsks PhonePe to send (or resend) an existing payment link to the customer over SMS and/or email. Returns the paylinkUrl and orderId. There is a cap on… - POSTCancel a payment link
/paylinks/v1/{{paylinkOrderId}}/cancelDeactivates an unpaid link so nobody can pay through it any more. Returns state: CANCELLED. A link already in a final state (completed, expired or cancelled)…
API details
- Base URL
https://api-preprod.phonepe.com/apis/pg-sandboxhttps://api.phonepe.com/apis/pghttps://api.phonepe.com/apis/identity-manager- Authentication
- OAuth 2.0 (client credentials flow)
- Operations
- 18 operations on 18 pathsPOST 13GET 5
- Main resources
- 1. Start here 12. Standard Checkout 53. Refunds 24. Mobile SDK 15. Custom Checkout (UPI on your own UI) 56. Payment links 4
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the PhonePe Payment Gateway API (PG v2) in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the PhonePe Payment Gateway API (PG v2) collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (client credentials flow). Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get an access token (O-Bearer)” (POST {{authUrl}}/v1/oauth/token), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the PhonePe Payment Gateway API (PG v2)?
PhonePe PG v2: O-Bearer token, Standard Checkout payments, order status, refunds, UPI collect/QR/intent and payment links. It is listed under Payments and has 18 endpoints.
Who publishes the PhonePe Payment Gateway API (PG v2)?
It is listed from PhonePe's public API description (an OpenAPI document), not published by PhonePe on Swastik Codes. Anyone who controls phonepe.com can claim the profile by adding a DNS TXT record.
What is the base URL of the PhonePe Payment Gateway API (PG v2)?
Its description lists 3 base URLs: https://api-preprod.phonepe.com/apis/pg-sandbox, https://api.phonepe.com/apis/pg, https://api.phonepe.com/apis/identity-manager. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the PhonePe Payment Gateway API (PG v2)?
With OAuth 2.0 (client credentials flow).
How many endpoints does the PhonePe Payment Gateway API (PG v2) have?
18 operations on 18 paths (13 POST, 5 GET). The largest groups are 1. Start here, 2. Standard Checkout, 3. Refunds, 4. Mobile SDK.
Is forking the PhonePe Payment Gateway API (PG v2) free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.