Partner OAuth Integration
Onboard a merchant using Co-Branded OAuth flow with a few API calls. The Co-Branded OAuth onboarding flow allows partners to onboard merchants seamlessly using OAuth 2.0 authorization. This approach provides a branded experience where merchants authenticate directly with PayU, and partners receive the merchant credentials securely.
Prerequisites
Before you begin, ensure you have:
- Partner credentials: Client ID and Client Secret. For more information, refer to Download Client Credentials.
- Whitelisted redirect URL: Your callback URL registered with PayU
- OAuth scope enabled: Contact your Key Account Manager (KAM) to enable OAuth onboarding
Onboarding Workflow
Flow diagram
Co-Branded (OAuth) Onboarding or OAuth Workflow (technical workflow) involves the steps as illustrated in the following diagram:
Steps involved in flow
The merchant’s workflow involves the following steps:
- Merchant clicks on the link at the partner website and gets redirected to PayU for onboarding.
- After onboarding on PayU, they are asked to give consent to their partner for sharing their credentials.
- On acceptance, the merchant is redirected to the URL specified in the partner account.
Example: If the redirect URL is https://abc.com, the merchant will be redirected to the following URL:
https://abc.com?auth_code=${code}&merchantId=${mid}
Note: The steps to get the merchant credentials require only two APIs. This removes the entry of merchant key and salt on a partner website. PayU recommends this for the seamless onboarding of merchants.
- From the above authorization code, call valid Auth code and client API_._ For more information, refer Validate Auth Code and Client.
{{hub_base_url}}/oauth/token
Partner will get access token in response that is used in Parter Payments.
Merchant Sign-Up Workflow with Co-Branded Onboarding
Steps involved in Co-Branded Onboarding
To sign up a merchant using OAuth:
- Navigate to the OAuth link appended with the new email id in the following format:
https://onboarding.payu.in/app/account/signup?reseller_id={PayU partner identifier}&state={state}Where <Merchant ID> is substituted with PayU partner identifier and state with current state of the session.
For example:
The Merchant Sign-up page is displayed.
- Enter the merchant’s phone and password.
- Click Next.
Note: If the mobile number already exists, the following message is displayed.
- Enter the OTP sent to the mobile number that was entered by you in Step 1.
- Enter the OTP sent to your email ID.
- Select any of the following roles:
- Business Owner
- Developer
- Customer
A list of questions is displayed on the What are you looking for from PayU? page similar to the following screenshot:
- Provide input for each question on the What are you looking for from PayU? page.
A welcome message is displayed similar to the following screenshot.
- Click Activate Account.
The Complete your full KYC page, similar to the following screenshot is displayed. For more information on completing your KYC, refer to Activate Account
Merchant Login Workflow with Co-Branded Onboarding
Steps involved in Login Co-Branded Onboarding
The merchant login workflow with Co-Branded (OAuth) Onboarding involves:
- Navigate to the OAuth link appended with the new email id in the following format:
https://onboarding.payu.in/app/account?reseller_id=<Merchant ID>&email=<Merchant mail ID to sign-up>Where <Merchant ID> is substituted with reseller ID and <Merchant mail ID to sign-up> is substituted with merchant mail ID to sign-up.
For example:
The Merchant Login page is displayed.
-
Enter the merchant password and click Verify.
The Authorize Your Account page is displayed.
-
Click Allow access to the account to provide consent.
A confirmation message is displayed, similar to the following screenshot:
- Click Back to<app name> app.
Enable Co-Branded Onboarding [One-Time]
This is enable Co-Branded Onboarding (OAuth) for partners.
Steps to Enable Co-Branded Onboarding
The following are the major steps involved to enable Co-Branded Onboarding (OAuth) for partners:
- Create a partner account at https://partner.payu.in if required. For more information, refer to Register a Partner Account
- Request enablement of OAuth with your PayU Key Account Manager. You need to ensure that the following OAuth scope is configured for your account.
Scope name: credentials_using_oauth- Configure the URLs in the application. For more information, refer to Configure URLs and Logo.
- Update the brand logo and theme colour for the onboarding journey and save.
Note: Brand Logo should be in jpg/jpeg, less than 5MB in size, and width and height should be 90 pixels. For more information on configuring the brand logo, refer to Configure URLs and Logo.
-
Show case the onboarding URL details at your website so that your merchants can sign up:
https://onboarding.payu.in/app/account/signup?reseller_id={{reseller_id}}&state={{state}}Where, the placeholders are:
- reseller_id: PayU partner identifier
- email: optional prefilled merchant email
- state: partner-generated session or correlation value
Note: The following environment or base URLs must be used based on the Test or Production environment:
| Test | <https://uat-onboarding.payu.in> |
| Production | <https://onboarding.payu.in> |
- Merchants can perform any of the following steps:
- For merchants who need to register, refer to Workflow for Co-Branded Onboarding
- For merchants who have already registered, refer to Workflow for Co-Branded Onboarding
The partner can pass the email of the merchant in the URL and the user will be taken to the Sign-in or Signup page. For example:
https://onboarding.payu.in/app/account/signup?reseller_id=66ed-fc3c-512f47ed-ac95-4319452fbd89&state=Uqnr5ge22UHere, the state parameter is the unique identifier of the session. Once the merchant is redirected beck to your platform, PayU will post the merchant id, auth code & the same state parameter to your configured redirect URL.
Sample Oauth Callback payload
After the successful completion of the oauth, PayU will trigger a callback to Partner's callback URL which will consist the Merchant ID that was created during the signup, the authcode, & the state parameter that was sent in the Oauth link.
https://xn6vqico31.execute-api.ap-south-1.amazonaws.com/prod/webhook/payu?auth_code=ce38ce1370c46e6830067d2726f3e254b0ea1d271788300ac9e4f347e9587aeb&merchantId=8235901&reseller_id=11ec-ccfb-4a042936-a698-0a696b110fde&state=nullIntegration Flow
flowchart TD
A[Start: Partner obtains <br> Client ID & Secret] --> B[Redirect merchant to <br> PayU Authorization Page]
B --> C[Merchant logs in <br> & <br> grants consent]
C --> D[PayU redirects to Partner <br> with auth_code]
D --> E[Partner validates <br> auth_code]
E --> F[Receive merchant <br> key & salt]
F --> G[Merchant can now <br> collect payments]
style A fill:#e1f5ff
style G fill:#d4edda
Steps to Integrate
Construct the OAuth authorization URL with client_id and encoded redirect_url to send merchants to PayU
Redirect the merchant to PayU where they log in, complete KYC, and grant consent
Receive a single-use auth_code on your redirect_url after merchant authorization
Use the obtained merchant credentials to integrate payment flows via Hosted Checkout, Pre-Built Checkout, or UPI S2S
Step 1: Build the OAuth URL
Construct the authorization URL to redirect merchants to the PayU login page.
URL Format:
| Environment | URL |
|---|---|
| Test | https://uat-onepayuonboarding.payu.in/app/account/signup/reseller_uuiid={PayU partner identifier ID}&state={state} |
| Production | https://onepayuonboarding.payu.in/app/account/signup/reseller_id={reseller_uuiid}&state={session state}&email={partner email address} |
Required Parameters:
reseller_id: It contains reseller UUID. For more information on how to obtain UUID, refer to Download Client Credentials.state: It is a custom field. It is optional.email(optional): It contains the partner email address. It is optional.
Sample OAuth URL
https://onboarding.payu.in/app/account/signup?reseller_id=66ed-fc3c-512f47ed-ac95-4319452fbd89&state=1513493Step 2: Redirect Merchant to Authorization Page
Redirect the merchant to the authorization URL constructed in Step 1. The merchant will:
- Log in to PayU (or create a new account).
- Complete KYC if not already done.
- Grant authorization to your partner application.
For detailed steps, refer to Activate Account.
Step 3: Receive Authorization Code
After successful authorization, PayU redirects the merchant back to your redirect_url with an authorization code.
Callback URL Format:
https://onboarding.payu.in/app/account/signup?reseller_id={PayU partner identifier}&state={session state}Example:
https://onboarding.payu.in/app/account/signup?reseller_id=11f1-1078-ee249a86-9fdf-0aad783eb813&state=1513493
Important:The
auth_codeis single-use and expires after a short period. For more information, refer to Validate Auth Code and Client. If theauth_codehas expired, use the Refresh Token API. For more information, refer to Refresh Token API.
Step 4: Collect Payments
After you complete the above steps, the merchant can start collecting payments. You can integrate using:
- Hosted Checkout - Redirect customers to PayU's payment page. For detailed steps to integrate, refer to Hosted Checkout Integration
- UPI S2S (Server-to-Server) - Direct UPI integration for seamless payments. For detailed steps, refer to UPI S2S Integration API.
Choose the integration method based on your requirements.
Next Steps
✅ Test your integration: Use the test environment credentials to verify the OAuth flow. For more information, refer to Testing and Go Live - Partner Integration
✅ Review API documentation: Validate Auth Code API | Get Merchant Credentials API
✅ Go Live: Contact your KAM to enable production OAuth and whitelist your redirect URLs
📚 For complete details on OAuth onboarding, see the Co-Branded OAuth Documentation.
Updated 7 days ago
