--- page_title: Partner Integration Overview product: JUSPAY Unified Dashboard page_source: https://juspay.io/in/docs/dashboard/docs/oauth-20-flow-for-dashboard-apis/partner-integration-overview llms_txt: https://juspay.io/in/docs/llms.txt product_llms_txt: https://juspay.io/in/docs/dashboard/llms.txt --- # Partners Integration Overview _Let merchants authorize your application to access their Juspay account — securely, with scoped, revocable permissions and no credential sharing._ ## **Overview** This guide explains how a partner application integrates with Juspay to access merchant accounts on behalf of those merchants. The integration uses the OAuth 2.0 Authorization Code flow: a merchant grants your application a specific, revocable set of permissions on their Juspay account, and your application receives a scoped access token in return. Once a merchant authorizes your application, you can call Juspay APIs on their behalf using the issued access token. Each call is validated against both the token and the specific permission it carries. **With this integration, a partner can be granted permission to:** * **Read** — view orders, order details, order status, refund details, and refund status. * **Act** — initiate payment requests and issue refunds against eligible transactions, where explicitly enabled. > **Note** > The exact set of operations available to your application is configured per OAuth client and confirmed during onboarding. ## **How Authorization Works** You direct the merchant to Juspay's hosted authorization page. The merchant logs in to Juspay, reviews the requested permissions, and approves. Juspay redirects back to your application with a short-lived authorization code, which your backend exchanges for an access token and a refresh token. **At a glance:** 1. **Build the authorization URL** with your `client_id`, `redirect_uri`, `scope`, and a random `state` value, then redirect the merchant to it. 2. **Merchant approves** on Juspay's consent screen. Login and consent happen entirely on Juspay — you never see merchant credentials. 3. **Receive the authorization code** via an HTTP 302 to your `redirect_uri`, carrying the code and the `state` you sent. Validate `state` before continuing. 4. **Exchange the code for tokens** from your backend using the Generate Token API. You receive an `access_token` and a `refresh_token`. 5. **Call Juspay APIs** with the access token in the `Authorization` header. 6. **Refresh before expiry** using the Refresh Token API — no merchant action required. > **Note** > The request and response specifications for the [Generate Token](https://juspay.io/in/docs/dashboard/docs/oauth-20-flow-for-dashboard-apis/generate-refresh-token-api), [Refresh Token](https://juspay.io/in/docs/dashboard/docs/oauth-20-flow-for-dashboard-apis/generate-refresh-token-api), and [Revoke Token](https://juspay.io/in/docs/dashboard/docs/oauth-20-flow-for-dashboard-apis/revoke-token-api) APIs are documented on the dedicated pages in this section. ### **Authorization Request** #### Shell Code Snippet: ```shell GET https://portal.juspay.in/ec/v2/authorize?client_id= &redirect_uri= &scope=&state= ``` ### **Query Parameters** | Parameter | Description | |---|---| | client_id | Your public OAuth client identifier, issued by Juspay during client creation | | redirect_uri | Where Juspay redirects the merchant after they allow or deny. Must exactly match a URI registered for the client; wildcards are not permitted. HTTPS only. | | scope | The scope of access being requested for this authorization. | | state | An opaque, random value you generate per request. Juspay returns it unchanged on the callback; validate it to protect against CSRF. | ### **Successful Callback** On approval, Juspay issues an HTTP 302 to your `redirect_uri` with the authorization code and the original state: #### Shell Code Snippet: ```shell ?code=&state= ``` > **Warning** > The authorization code is single-use and expires in 5 minutes. Exchange it from your backend; do not expose the client_secret in browser or mobile code. ### **Exchange the Code for Tokens** Once you receive the authorization `code` on your `redirect_uri`, your backend exchanges it for an access token and refresh token by calling the [generate/refresh token API](https://juspay.io/in/docs/dashboard/docs/oauth-20-flow-for-dashboard-apis/generate-refresh-token-api). The response contains the `access_token` and `refresh_token`. > **Note** > The same generate/refresh token API is later used to refresh an expiring access token, with action=refresh_token. ### **What the Merchant Sees** On Juspay's hosted consent screen the merchant reviews your application's name and logo, the plain-language list of permissions being requested, and chooses Allow or Deny. Because login and consent occur on Juspay, the merchant's credentials are never exposed to your application. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Screenshot%202026-06-14%20at%208.04.29%E2%80%AFPM.png) *Authorization Request Page* ### **Token Details** | Property | Value | |---|---| | Token type | Bearer token, passed in the Authorization header | | Access token expiry | 90 days (7,776,000 seconds) | | Refresh token | Issued alongside the access token; use it to obtain a new token pair before the access token expires | | Revocable | Yes - by the merchant at any time from their Juspay dashboard | > **Warning** > When a merchant revokes access, all active access tokens and refresh tokens for that merchant-client authorization are invalidated immediately. Subsequent API calls return 403. ### **Handling Common Scenarios** | Scenario | What Happens | How to Handle | |---|---|---| | Merchant is already connected to Client | Juspay returns a new token when you attempt to re-authorize the same merchant | No action needed. Re-authorization is safe; use the returned token. | | Merchant revokes access | Partner's API calls start returning 403 Forbidden. All active access tokens and refresh tokens issued for that merchant-client authorization are invalidated. | Prompt the merchant to re-authorize through the same OAuth flow. | | Access token expires | API calls return 401 Unauthorized | Use the refresh_token to get a new access_token without requiring merchant action. If the refresh fails, prompt re-authorization. | | Merchant denies on consent screen | Juspay redirects to redirect_uri with error=access_denied | Surface a message explaining the connection was not completed. Allow merchants to retry. | | Authorization code not exchanged within 5 minutes | Token exchange returns 400 invalid_grant | Restart the authorization flow from Step 1. This is a safe retry. | ## **Credentials & Setup** ### **What Juspay Provides** * **Partner onboarding** - your organization is set up as a partner, and you can onboard your own users. * **Client management** - create multiple OAuth clients (client_id + client_secret pairs), each with its own set of API permissions; view, modify, or delete clients. The client_id and client_secret themselves cannot be changed. * `client_id` - public client identifier; include it in every authorization URL. * `client_secret` - confidential credential for token requests. Juspay stores only a hash; it cannot be recovered if lost. ### **What You Provide (per client)** * `redirect_uri` - exact-match HTTPS URI; wildcards not permitted. * **Client name** - shown on the consent screen (" is requesting access to your Juspay account"). * **Logo URL** - publicly accessible PNG (128×128 recommended) for the consent screen. * **Selection of operations** - the operations this client should be permitted to perform. > **Warning** > Exchange the authorization code from your backend only. The client_secret must never appear in frontend, browser, or mobile code. Sandbox and production credentials are separate — a sandbox authorization does not grant production access, and vice versa. --- ## See Also - [Monitoring Boards](https://juspay.io/in/docs/dashboard/docs/analytics/monitoring-boards) - [Generate/Refresh token API](https://juspay.io/in/docs/dashboard/docs/oauth-20-flow-for-dashboard-apis/generate-refresh-token-api)