← library
No user OAuth
Payments / UPI payment gateway (India)·agent-generated · deepseek-v4.1-flash·checked 2026-10-28
difficulty
4/5

No user-delegated OAuth: the only published flow is a merchant client_credentials token (self-serve once your Business account and V2 keys exist), while acting for PhonePe users means Switch partner onboarding plus app review, with no published timeline.

First working connection
~1-2 hours of coding after keys exist (inferred)
Production / approved
Days-weeks: KYC + possible support ticket + URL whitelisting (inferred); Switch review adds weeks
Composio managed OAuth
Bring your own app
Not in Composio's managed-OAuth list — you'll need your own OAuth app (or it isn't a Composio toolkit yet).
who does itagent 3you 4provider 0
evidencetested 4sourced 18inferred 13
◆ agent run10 pages read17/25 quotes verified verbatim57s$0.016deepseek-v4.1-flash

01Pick your path

Merchant Payment Gateway (client_credentials)
when Your agent pays/collects on behalf of your business, not on behalf of an individual PhonePe user.
→ Server-to-server token + Standard Checkout for your own business. No end-user OAuth consent; the token carries merchant-level rights only.
PhonePe Switch (in-app user flow)
when You need a user-scoped session inside the PhonePe app (travel, food, shopping categories).
→ Merchant app hosted inside PhonePe app with SSO flow (fetchAuthToken, access token, user details). Requires partner onboarding and app review submission.
Payment Links / no-code plugins
when You want collection fast and can accept dashboard/ticket gating instead of API-level auth.
→ Collect money without owning the auth flow; Payment Links via API needs a use-case approval and a role assigned to your account.

02Time & effort

Hands-on work
~2 workdays – ~7 workdays
Waiting on others
2 weeks – 9 weeks
You're actually working
4% of elapsed time
Phases
6
start↑ first working connection, then production pathproduction
  1. DEVMerchant account + KYC1–3 daysinferred[S10]Sources state an active PhonePe Business account is a prerequisite but give no KYC duration.
  2. DEVSupport ticket for V2 credentials/roleswait 1–5 dayssourced[S4]Conditional: skip if Developer Settings already shows client_id/client_secret/client_version. Ticket turnaround is inferred.
  3. DEVToken fetch + refresh logic30–90 minutesinferred[S6]Endpoint and parameters are documented; coding time is an estimate.
  4. DEVSandbox end-to-end (pay, webhook, status)2–6 hoursinferred[S7][S10]Four documented steps: token, create payment, PayPage, verify via webhook or Order Status.
  5. PRODGo live: whitelist URL, live keys, webhook1–3 daysinferred[S4]Whitelisting is done 'on our end' per troubleshooting docs; production review time is not stated.
  6. PRODSwitch onboarding + app review (only user-auth path)wait 2–8 weeksinferred[S5]Switch docs list 'Submitting your App for review' and 'Process of going live' but publish no SLA or criteria.
agent can do it you waiting on providerbar widths ∝ √time, so short tasks stay visible

03Steps

0/7 done

Get a working connection

  1. Confirm what auth PhonePe actually offersagentinferred[S6]

    Both /.well-known/openid-configuration and /.well-known/oauth-authorization-server return 404 on api.phonepe.com and developer.phonepe.com. There is no standards OAuth authorization-code flow to point an agent at; the documented auth is a client_credentials token for merchants.

    ↗ developer.phonepe.com/payment-gateway/website-integration/standard-checkout/api-integration/api-reference/authorization
  2. Create the merchant account and locate Developer Settingsyousourced ❝[S4][S10][S6]

    Get the merchant account first — credentials live behind it. Then open Dashboard → Developer Settings and confirm you see client_id, client_secret and client_version (the V2 trio). If the dashboard only shows salt keys, you are on the deprecated V1 flow.

    “Ensure that you are using the correct Credentials(V2) which are present on the PhonePe Dashboard under ’Developer Settings’.” — [S4] verified verbatim
    ◆ prepared by agent · PhonePe Business sign-up
    open ↗
    https://developer.phonepe.com/
  3. File a ticket if the V2 keys or the role are missingyousourced ❝[S4]

    The documented path to V2 credentials or extra API roles (custom checkout, Payment Links) is a support ticket to the integration team; credentials are issued per integrationType. Include your merchant ID, flow and sandbox/production environments.

    “You need to raise a support ticket to the integration team in order to release PG V2 credentials.” — [S4] verified verbatim
  4. Implement the token call and refresh windowagentsourced ❝[S4][S6]

    POST form-encoded client_id/client_version/client_secret/grant_type=client_credentials. Cache access_token and refresh off expires_at (epoch seconds) at least 5 minutes before expiry — expires_in comes back null. Use the O-Bearer prefix on every later call.

    “Ensure you are using a complete valid access token. We recommend generating a new access token at least 5 minutes before your current one is set to expire..” — [S4] verified verbatim
    ◆ prepared by agent · Token fetch + refresh helper
    import time, requests

TOKEN_URL = "https://api-preprod.phonepe.com/apis/pg-sandbox/v1/oauth/token"
# prod: https://api.phonepe.com/apis/identity-manager/v1/oauth/token
_cache = {"token": None, "exp": 0}

def get_token():
    if _cache["token"] and time.time() < _cache["exp"] - 300:  # refresh ~5 min early
        return _cache["token"]
    r = requests.post(
        TOKEN_URL,
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        data={
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "client_version": CLIENT_VERSION,
            "grant_type": "client_credentials",
        },
        timeout=15,
    )
    r.raise_for_status()
    d = r.json()
    _cache["token"] = d["access_token"]
    _cache["exp"] = d["expires_at"]  # epoch seconds; expires_in is null
    return _cache["token"]

# then: headers={"Authorization": f"O-Bearer {get_token()}", "Content-Type": "application/json"}
  5. Run one sandbox payment end to endagentinferred[S7][S10]

    Sandbox base: https://api-preprod.phonepe.com/apis/pg-sandbox/. Create payment → invoke PayPage → verify via webhook (checkout.order.completed / failed, pg.refund.completed / failed) or Order Status API. Rely only on root-level payload.state, not a nested field.

Make it production-ready

  1. Whitelist the production URL and configure the webhookyousourced ❝[S4][S10]

    Swap in the identity-manager + /apis/pg base URLs, register your exact production domain/sub-domain (one URL per merchant ID), and point the dashboard webhook at an HTTPS URL with no IP or port. Keep Order Status polling as the fallback.

    “Ensure you have created a valid webhook url, with no IP address or port number in it and https method and accept post json data.” — [S4] verified verbatim
  2. Ask your BD contact about Switch SSO (the only user-auth path)youinferred[S5][S4]

    If you genuinely need user-level sessions, the only documented route is Switch: merchant apps hosted inside PhonePe with an SSO flow and an app review submission. There is no published Apply button in the fetched docs — go through your BD representative / support ticket.

    ◆ prepared by agent · Switch access request draft
    Subject: Switch onboarding + SSO for a third-party app

Hi PhonePe partner team,

We are an existing PhonePe merchant (merchant ID: XXXX) building an in-app experience for the "<category>" section of PhonePe Switch. Our app is a <React Native / PWA / M-Site> build.

We would like to (a) get Switch onboarding prerequisites, (b) confirm what the SSO flow (fetchAuthToken → access token → user details) exposes and what user consent is shown, and (c) the app-review checklist and expected timeline for going live.

Use case: <one paragraph, transaction volume estimate, screenshots of the flow>.

Thanks,
<name>, <company>

04Requirements, scopes & nuances

You'll need

  • ▸An active PhonePe Business merchant account (sign-up + business KYC). sourced ❝[S10]
  • ▸Client_ID, Client_Secret and Client_Version from the PhonePe Business Dashboard → Developer Settings. sourced ❝[S10][S6]
  • ▸A backend server to hold credentials (browser calls fail with CORS). sourced ❝[S4]
  • ▸One registered/whitelisted HTTPS domain or sub-domain for production; localhost is not accepted. inferred[S4]
  • ▸A webhook URL on the dashboard: HTTPS, no IP/port, accepts POST JSON, returns an acknowledgement. sourced ❝[S4]
  • ▸For user-level auth inside the PhonePe app: a Switch app (React Native, PWA or M-Site) submitted for review. sourced ❝[S5]

Gotchas

  • !The Authorization header prefix is 'O-Bearer <token>' (with the space), not 'Bearer'; wrong prefix causes 401/API Mapping Not Found. sourced ❝[S4]
  • !The token response returns expires_in: null — schedule refresh off expires_at (epoch seconds) and regenerate ~5 minutes before expiry. inferred[S6][S4]
  • !Only one URL can be whitelisted per merchant ID, and you whitelist either a domain or a sub-domain, not both. sourced ❝[S4]
  • !V1 salt_key/salt_index credentials are deprecated and cannot be generated; any tutorial using them is dead. sourced ❝[S4]
  • !Webhook URL must be HTTPS, contain no IP address or port, accept POST JSON, and return an acknowledgement — and you still need Order Status API as fallback. sourced ❝[S4]
  • !Token and payment calls must run from your backend; browser calls hit CORS errors. sourced ❝[S4]
Scope / permissionTierNoteEvidence
client_credentials grant (no scope parameter)restrictedToken request takes only client_id, client_version, client_secret, grant_type. There is no scope list and no user consent screen — the token carries your merchant's full PG rights.inferred[S6]
Payment Links API rolegatedGated: requires sharing a business use case with the integration team; role is assigned after approval.sourced ❝[S4]
Switch SSO user detailsgatedUser identity inside the PhonePe app via fetchAuthToken + Get User Details; only for merchants onboarded to Switch.inferred[S5]

05If you get blocked

✕There is no self-serve OAuth/consent flow for third-party apps acting on behalf of PhonePe users; the only published OAuth is a client_credentials merchant token.inferred[S6][S7][S5]

→ Treat PhonePe as a merchant-side payment rail (agent acts for your business, not for the end user), or apply to PhonePe Switch if you truly need user identity inside the PhonePe app.

✕Dashboard may show no V2 credentials (client_id, client_secret, client_version) for your account or flow.sourced ❝[S4]

→ Open a support ticket to the integration team; credentials are issued per integrationType/flow. V1 salt keys cannot be reissued.

✕Production calls fail with 'Something went wrong' / missing QR when the URL is not whitelisted or is localhost.sourced ❝[S4]

→ Whitelist the real registered domain/sub-domain before go-live and never test production from localhost.

06Evidence: what was tested, sourced, and still uncertain

$ probes: live GETs with a dummy client_id, no credentials
✓ Discovery document (/.well-known/openid-configuration) → 404
https://api.phonepe.com/.well-known/openid-configuration
not published
∴ No OIDC discovery on the API host — you cannot auto-configure an OIDC client (issuer, authorization endpoint, scopes). You must hardcode the token URL from the docs.
✓ Discovery document (/.well-known/oauth-authorization-server) → 404
https://api.phonepe.com/.well-known/oauth-authorization-server
not published
∴ No RFC 8414 authorization-server metadata on the API host — no evidence of a standards-compliant authorization-code / PKCE endpoint for third-party apps.
✓ Discovery document (/.well-known/openid-configuration) → 404
https://developer.phonepe.com/.well-known/openid-configuration
not published
∴ No OIDC discovery on the developer portal either; documentation is HTML-only, no machine-readable auth metadata.
✓ Discovery document (/.well-known/oauth-authorization-server) → 404
https://developer.phonepe.com/.well-known/oauth-authorization-server
not published
∴ No OAuth metadata on the portal host; agent-driven client registration or scope discovery is not possible — read the docs and file a support ticket instead.

Sources read

  1. [S1] PhonePe Business Developer Documentation | Integration Guide official
  2. [S2] Payment Gateway | PhonePe Business Developer Documentation official
  3. [S3] Payment Gateway | PhonePe Business Developer Documentation | Integration Guide official
  4. [S4] Troubleshooting | PhonePe Business Developer Documentation | Integration Guide official
  5. [S5] Switch | PhonePe Business Developer Documentation | Integration Guide official
  6. [S6] Authorization | PhonePe Business Developer Documentation official
  7. [S7] Integration Steps | PhonePe Business Developer Documentation official
  8. [S8] Offline Integration official
  9. [S9] Introduction | PhonePe Business Developer Documentation official
  10. [S10] Introduction to Website Checkout official
  11. [composio] Composio — Managed OAuth apps directory official
  12. [probe] Live HTTP probes run by the agent (dummy client_id, no credentials) probe

Still uncertain

  • ? Sources never state approval durations for merchant KYC, V2 credential tickets, URL whitelisting, or Switch app review — all waits here are inferred.
  • ? Whether PhonePe offers any 'Sign in with PhonePe' style user-delegated OAuth to arbitrary third-party apps is not shown in any fetched source; the planner's 'unclear' is really 'not published'. Ask PhonePe before promising user-level auth.
  • ? Switch pages were fetched only as a table of contents — user-consent behaviour of its SSO flow (fetchAuthToken / Get User Details) and onboarding criteria are unverified.
  • ? Scope/role granularity is undocumented: the token appears merchant-wide, so an agent holding it can do anything the merchant can (payments, refunds) — no least-privilege options are described.
  • ? Whether new merchants automatically get V2 credentials or must always raise a ticket is ambiguous in the troubleshooting doc.
  • ? Generated automatically; no app was registered and no review was submitted.