Testing and Go Live - OAuth Flow Partner Integration

Prerequisites:

• Partner Client ID and Client Secret (test environment)
• Whitelisted redirect URL (test environment)
• Access to PayU Partner Portal (test mode)

Contact your PayU Key Account Manager (KAM) to:

• Enable OAuth onboarding for your partner account
• Obtain test environment Client ID and Secret
• Whitelist your test redirect URL(s)

How to Download Credentials:

1. Log in to PayU Partner Portal (test environment)
2. Navigate to Merchant Integration → Partner Integration
3. Click Download Credentials
4. Save Client ID and Client Secret securely

API: Validate Auth Code and Client API

https://onboarding.payu.in/app/account/signup?reseller_id={{reseller_id}}&state={session state}

https://onboarding.payu.in/app/account/signup?reseller_id=11f1-1078-ee249a86-9fdf-0aad783eb813&state=1513493

curl --location 'https://testdashboard.payu.in/oauth/validate-auth-code' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "ABC123",
    "client_secret": "your_client_secret",
    "auth_code": "XYZ789ABC123"
}'

{
    "access_token": "e6ff7e34b704be2b14c8ae3c0e776597df4ae7de9e12d3e4c79781fcbbf2c4bb",
    "token_type": "Bearer",
    "expires_in": 7199,
    "refresh_token": "356fe080daa69438e0c2d3b0a80b3fe4aa3f78b264e6092e95e4429ae59486a7",
    "scope": "credentials_using_oauth create_payment_links read_payment_links update_payment_links delete_payment_links",
    "created_at": 1709198191,
    "user_uuid": "11ed-933c-d307ba06-b71a-0a64ecf8a4cc"
}

{
    "client_id": "INVALID",
    "client_secret": "your_client_secret",
    "auth_code": "valid_auth_code"
}

{
    "status": 0,
    "msg": "Invalid client credentials"
}

{
    "client_id": "ABC123",
    "client_secret": "INVALID",
    "auth_code": "valid_auth_code"
}

{
    "status": 0,
    "msg": "Invalid client credentials"
}

{
    "client_id": "ABC123",
    "client_secret": "your_client_secret",
    "auth_code": "EXPIRED_OR_INVALID"
}

{
    "status": 0,
    "msg": "Invalid auth code"
}

{
    "client_id": "ABC123",
    "client_secret": "your_client_secret",
    "auth_code": "ALREADY_USED_CODE"
}

{
    "status": 0,
    "msg": "Auth code already used"
}

API: Get Merchant Credentials API

Use Case: Retrieve credentials at a later time if needed

curl --location 'https://testdashboard.payu.in/oauth/get-merchant-credentials' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "ABC123",
    "client_secret": "your_client_secret"
}'

{
    "status": 1,
    "msg": "Success",
    "merchant_key": "mK3j2L9p",
    "salt": "sA7x9B2c"
}

{
    "client_id": "INVALID",
    "client_secret": "INVALID"
}

{
    "status": 0,
    "msg": "Invalid client credentials"
}

{
    "status": 0,
    "msg": "No merchant found for this partner"
}

After receiving merchant credentials via OAuth, test payment collection using the Partner API Layer. Use the access_token received from the Validate Auth Code API as the Bearer token.

curl --location --request POST \
'https://test-partnerapilayer.payu.in/apilayer/partner/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_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"
}'

{
    "redirectUri": "https://apitest.payu.in/public/#/35de666bac018494a06205addba2962cdb8d03ca9c2fa7954807098709f1b6dc"
}

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"
}'

{
    "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",
        "otpPostUrl": "https://test.payu.in/ResponseHandler.php"
    }
}

Test onboarding multiple merchants through OAuth:

Test Steps:

1. Onboard Merchant A via OAuth
2. Store Merchant A's access_token and user_uuid
3. Onboard Merchant B via OAuth
4. Store Merchant B's access_token and user_uuid
5. Verify both sets of credentials work independently

Validation Points:

• Each merchant has a unique access_token and user_uuid
• Tokens stored separately and correctly associated via user_uuid
• Payments for Merchant A use Merchant A's Bearer token
• Payments for Merchant B use Merchant B's Bearer token
• No credential cross-contamination

1. Build and open the authorization URL
2. Register new test merchant or login with existing credentials
3. Grant authorization to partner app
4. Receive auth code in redirect
5. Exchange auth code for credentials via Validate Auth Code API
6. Store access_token and user_uuid securely
7. Submit test payment to Partner Payments API using Bearer token
8. Verify payment success via redirectUri
9. Validate payment callback on SURL

Expected Duration: 3–5 minutes

Validation Points:

• All steps complete without errors
• access_token received and stored
• Payment successful with Bearer token auth
• Callback received with valid data

1. Complete initial OAuth flow for a merchant
2. Store credentials
3. Later, initiate OAuth flow again for same merchant
4. Verify auto-redirect with new auth code
5. Exchange new auth code for credentials
6. Verify user_uuid matches previously stored record

Validation Points:

• Re-authorization works smoothly
• Merchant not asked for consent again
• Same user_uuid returned
• No duplicate merchant records

1. Prepare list of 10 test merchants
2. Send OAuth links to each
3. Track completion status
4. Store all access_token and user_uuid values
5. Test payment for each merchant using their respective Bearer token

Validation Points:

• All merchants onboarded successfully
• Each has a unique access_token and user_uuid
• Parallel processing works
• No credential mix-ups

1. Start OAuth flow
2. Receive auth code
3. API call fails (simulate network error)
4. Retry auth code exchange
5. Verify success on retry

Validation Points:

• Retry successful
• Auth code still valid within expiry
• access_token received
• No duplicate processing

Symptoms: Authorization page shows error or doesn't load

Possible Causes:

• Invalid or missing reseller_id
• Client account not enabled for OAuth
• state parameter malformed or missing
• OAuth not enabled for partner account

Solution:

1. Verify reseller_id is correctly constructed with encoded Merchant ID and email
2. Contact PayU KAM to confirm OAuth is enabled
3. Ensure state carries a valid encoded session value
4. Verify using the test environment URL for testing

Symptoms: Error message: "Redirect URL not whitelisted"

Possible Causes:

• Redirect URL not whitelisted in Partner Portal
• URL encoding mismatch (encoded vs decoded)
• HTTP vs HTTPS mismatch
• Trailing slash mismatch

Solution:

1. Log in to Partner Portal → Settings → OAuth Configuration
2. Add exact redirect URL to whitelist (including protocol and path)
3. Ensure URL in authorization request matches exactly
4. Use HTTPS for all redirect URLs
5. Be consistent with trailing slashes

Examples:

✅ Correct: https://partner.example.com/callback
❌ Wrong: http://partner.example.com/callback (HTTP instead of HTTPS)

✅ Correct: https://partner.example.com/callback/
❌ Wrong: https://partner.example.com/callback (missing trailing slash if whitelisted with it)

Symptoms: "Invalid auth code" error when calling Validate Auth Code API

Possible Causes:

• Auth code already used
• Auth code expired
• Incorrect auth code copied from URL
• Special characters not handled properly

Solution:

1. Extract auth code immediately from redirect URL
2. Exchange auth code within the expiry window of receiving it
3. Use auth code only once
4. Handle URL decoding properly if auth code contains special characters
5. Generate new auth code by repeating OAuth flow

Symptoms: API returns success but no access_token or user_uuid

Possible Causes:

• Merchant not fully onboarded
• KYC pending for merchant
• Merchant account not activated

Solution:

1. Check merchant status in PayU dashboard
2. Ensure merchant completed KYC
3. Wait for merchant approval (if under review)
4. Contact PayU support if merchant shows as active but tokens not received

Symptoms: Partner Payments API returns 401 Unauthorized or hash mismatch error

Possible Causes:

• Using an expired or invalid access_token as Bearer token
• Incorrect Authorization header format
• Hash string parameter order incorrect
• Extra spaces in hash string

Solution:

1. Verify the access_token from OAuth is valid and not expired
2. Use the format: Authorization: Bearer <access_token>
3. Check hash string parameter order:

   key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||SALT

4. Trim all parameters to remove spaces
5. Refresh the access token using the refresh_token if expired

Symptoms: Payment completed but SURL/FURL not triggered

Possible Causes:

• SURL/FURL not publicly accessible
• Firewall blocking PayU servers
• Incorrect URL in payment request
• Server timeout during callback

Solution:

1. Verify SURL/FURL are publicly accessible (use external tools to test)
2. Whitelist PayU IP ranges in firewall
3. Ensure URLs use HTTPS
4. Check server logs for incoming requests
5. Implement Verify Payment API as fallback
6. Return HTTP 200 OK quickly in callback handler

Symptoms: Wrong merchant credentials stored or retrieved

Possible Causes:

• Session management issues
• state parameter not used or not validated
• Concurrent OAuth flows not handled
• Cache issues

Solution:

1. Use state parameter in authorization URL to bind sessions:

   https://onboarding.payu.in/app/account/signup?reseller_id={{reseller_id}}&state=SESSION_ID

2. Verify state parameter in callback matches the original session
3. Store access_token immediately after receiving, keyed to user_uuid
4. Use unique state values to track each OAuth flow
5. Implement proper session management

Symptoms: Auth code rejected even when exchanged quickly

Possible Causes:

• Auth code expired (short expiry window)
• Clock skew between servers

Solution:

1. Exchange auth code immediately after redirect — do not store or delay
2. Ensure server clocks are synchronized (NTP)
3. Generate a new auth code by restarting the OAuth flow

1. Parallel Processing

   • Process multiple OAuth flows concurrently
   • Use asynchronous API calls where possible
   • Implement queuing for token storage

2. Token Caching

   • Cache access_token securely for its expires_in duration
   • Use refresh_token to obtain new access tokens without re-authorizing
   • Use Redis or similar for session and token management

3. Database Optimization

   • Index user_uuid and client_id columns
   • Use connection pooling
   • Optimize token retrieval queries

4. API Call Optimization

   • Implement exponential backoff for retries on the Partner Payments API
   • Set appropriate timeouts (30 seconds recommended)
   • Handle 429 Too Many Requests with backoff logic

5. Monitoring

   • Track OAuth flow completion rates
   • Monitor API response times
   • Set up alerts for high error rates
   • Track token refresh success rates

Contact PayU support in these scenarios:

• OAuth not enabled for your partner account
• Redirect URL whitelisting issues
• Merchant tokens not received despite successful OAuth flow
• Repeated API failures (not related to your implementation)
• Security concerns or suspected compromise

• Partner Support Email: [email protected]
• Technical Support: Navigate to help.payu.in or send an mail with complete issue details (including mid) to [email protected]
• Key Account Manager: (provided during onboarding)

When contacting support, include:

1. Partner Client ID (never share Client Secret)
2. Timestamp of issue
3. Error messages received
4. API request/response (redact sensitive data such as tokens)
5. Steps to reproduce
6. Environment (test/production)