Quick Start Partner API 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 Get Client ID and Secret from Dashboard.
- Whitelisted redirect URL: Your callback URL registered with PayU
- OAuth scope enabled: Contact your Key Account Manager (KAM) to enable OAuth onboarding
Integration 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. Exchange it immediately for merchant credentials. For more infor
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
- UPI S2S (Server-to-Server) - Direct UPI integration for seamless payments
Choose the integration method based on your requirements.
Hosted Checkout Integration
For detailed steps to integrate, refer to Hosted Checkout Integration
Sample Request
curl --location --request POST \
'https://test-partnerapilayer.payu.in/apilayer/partner/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ROTATED_BEARER_TOKEN>' \
--data-raw '{
"txnid": "nY3tkz3vciHFGTjblyFeycL2Zn1m",
"amount": 1090.33,
"productinfo": "whatsapp",
"firstname": "Manikanta",
"reseller_id": "83fe-eb64-021844d8-9397-26535b1bf0c2",
"merchant_id": "8238480",
"phone": 7036722360,
"hash": "52f45927e221a16bd5372709516de5110c06c55e0057f8a18a3b9b9f2c2f176870af276274709910f27d7c5df44822777542e3d4b86f29e8304e17fcb373133c",
"lastname": "CHeruku",
"email": "[email protected]",
"curl": "<YOUR_CANCEL_URL>",
"furl": "<YOUR_FAILURE_URL>",
"surl": "<YOUR_SUCCESS_URL>",
"udf1": "whatsapp"
}'Sample Response
{
"redirectUri": "https://apitest.payu.in/public/#/35de666bac018494a06205addba2962cdb8d03ca9c2fa7954807098709f1b6dc"
}UPI S2S Integration
For detailed steps, refer to UPI S2S Integration API.
Sample Request
curl --location --request POST 'https://test-partnerapilayer.payu.in/apilayer/partner/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 9d2ab8e1b99aa02f6b827af5b5000b277d9cb1cd037acb7cb31436a5b0da4f74' \
--data-raw '{
"txnid": "nY3tkz3vciHFGTjblyFeycL2Zn1m",
"amount": 1090.33,
"productinfo": "whatsapp",
"firstname": "Manikanta",
"reseller_id": "83fe-eb64-021844d8-9397-26535b1bf0c2",
"merchant_id": 8238480,
"phone": 7036722360,
"hash": "5aadceaf6bec9158ccba8ec0dab32debcacbfd50e3587c077fa11107a5be0ac26712fae230522afb8908d068122c02f2d5c733a46c33ace0f66e5cc9d2ae4714",
"lastname": "CHeruku",
"email": "[email protected]",
"curl": "https://www.google.com",
"furl": "https://www.google.com",
"surl": "https://www.youtube.com",
"txn_s2s_flow": "4",
"s2s_device_info": "ewew",
"s2s_client_ip": "ewew"
}'Sample Response
{
"metaData": {
"message": null,
"referenceId": "024d9afbdbf85bd35b25649ccf983e16ee3d4646c2cdcffada88bd2df371fd43",
"statusCode": null,
"txnId": "nY3tkz3vciHFGTjblyFeycL2Zn1m",
"txnStatus": "pending",
"unmappedStatus": "pending"
},
"result": {
"paymentId": 403993715529028543,
"merchantName": "Merchant",
"merchantVpa": null,
"amount": "1090.33",
"intentURIData": "pa=&pn=&tr=403993715529028543&tid=PPPL403993715529028543290523133325&am=1090.33&cu=INR&tn=UPI Transaction for PPPL403993715529028543290523133325",
"acsTemplate": "PGh0bWw+PGJvZHk+PGZvcm0gbmFtZT0icGF5bWVudF9wb3N0IiBpZD0icGF5bWVudF9wb3N0IiBhY3Rpb249Imh0dHBzOi8vdGVzdC5wYXl1LmluLzAyNGQ5YWZiZGJmODViZDM1YjI1NjQ5Y2NmOTgzZTE2NGQ0YTUxYzYzNjcyODAxNjRkMDlkNDg2YjRkYWI1ZmEvaW50ZW50U2VhbWxlc3NIYW5kbGVyLnBocCIgbWV0aG9kPSJwb3N0Ij48aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJ0b2tlbiIgdmFsdWU9IjE2NTIyQTgxLTUwMjYtMUUyRi0zNDFCLTJFQ0MyQ0Y5RTE1QyI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYW1vdW50IiB2YWx1ZT0iMTA5MC4zMyI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0ibWlocGF5aWQiIHZhbHVlPSIwMjRkOWFmYmRiZjg1YmQzNWIyNTY0OWNjZjk4M2UxNmVlM2Q0NjQ2YzJjZGNmZmFkYTg4YmQyZGYzNzFmZDQzIj48aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJkaXNhYmxlSW50ZW50U2VhbWxlc3NGYWlsdXJlIiB2YWx1ZT0iMSI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0icGF5ZWVWcGEiIHZhbHVlPSIiPjxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InBheWVlTmFtZSIgdmFsdWU9Ik1lcmNoYW50Ij48aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJhZGRpdGlvbmFsQ2hhcmdlcyIgdmFsdWU9IjAiPjxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InRyYW5zYWN0aW9uRmVlIiB2YWx1ZT0iMTA5MC4zMyI+PC9mb3JtPjxzY3JpcHQgdHlwZT0ndGV4dC9qYXZhc2NyaXB0Jz4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIHdpbmRvdy5vbmxvYWQ9ZnVuY3Rpb24oKXsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBkb2N1bWVudC5mb3Jtc1sncGF5bWVudF9wb3N0J10uc3VibWl0KCk7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIDwvc2NyaXB0PjwvYm9keT48L2h0bWw+",
"otpPostUrl": "https://test.payu.in/ResponseHandler.php"
}
}Verify Payment
Upon receiving the response, PayU recommends you performing a reconciliation step to validate all transaction details.
You can verify your payments using either of the following methods:
Configure the webhooks to monitor the status of payments.
Webhooks enable a server to communicate with another server by sending an HTTP callback or message.
These callbacks are triggered by specific events or instances and operate at the server-to-server (S2S) level.
Know how to manage Webhooks for Payments.
Environment
| Test Environment | https://test.payu.in/merchant/postservice.php?form=2 |
| Production Environment | https://info.payu.in/merchant/postservice.php?form=2 |
Note: The hash logic for Verify Payment API is:
sha512(key|command|var1|salt) sha512
Sample request
curl --request POST
--url 'https://test.payu.in/merchant/postservice?form=2'
--header 'Content-Type: application/x-www-form-urlencoded'
--data key=JPM7Fg
--data command=verify_payment
--data var1=IhfgcZnXR4o4nB
--data hash=a0ae79fdd66c875af6e9b21c4a67f1822deb00f2df5e9f0b1948f3222f536a9bf741b24efbb1874ca0f84f76b036e6c0d641581d0100f7abe4aeed2f3264f5c9
Sample response
If credit card payment is made, the response is similar to the following:
{
"status":0,
"msg":"0 out of 1 Transactions Fetched Successfully",
"transaction_details":
{
"IhfgcZnXR4o4nB":
{
"mihpayid":"Not Found",
"status":"Not Found"
}
}
}If txnID is not found, the response is similar to the following:
{
"status":0,
"msg":"0 out of 1 Transactions Fetched Successfully",
"transaction_details":
{
"IhfgcZnXR4o4nB":
{
"mihpayid":"Not Found",
"status":"Not Found"
}
}
}Response parameters
| Parameter | Description | Example |
|---|---|---|
| status | This parameter returns the status of web service call. The status can be any of the following:
| 0 |
| msg | This parameter returns the reason string. | For example, any of the following messages are displayed:
|
| transaction_details | This parameter contains the response in a JSON format. For more information refer to JSON fields description for transaction_details parameter . | |
| request_id | PayU Request ID for a request in a Transaction. For example, a transaction can have a refund request. | 7800456 |
| bank_ref_num | This parameter returns the bank reference number. If the bank provides after a successful action. | 204519474956 |
To learn more about the possible error codes and their description, refer to Error Codes.
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 8 days ago
