Testing and Troubleshooting Partner Integration

This guide provides comprehensive testing procedures, common error resolutions, debugging techniques, and test data for all Partner Payments integration methods: Hosted Checkout, UPI Intent, and UPI TPV.

Testing Overview by Integration Method

Before diving into specific tests, understand which testing steps apply to your integration:

Step 1: Pre-Integration Validation

1.1 Verify OAuth Credentials

Test: Generate access token using the 3-step flow as in Get Access Token - Partner Integration

Expected Result:

1. Received the auth_code on the redirect URI

2. Validate this auth_code using the Validate Auth Code and Client API.

   You will receive an accesss_token.

3. Use the access token in the Partner Payment APIs.

Validation Checklist:

• All three OAuth steps complete successfully
• Final access token contains all required scopes
• Token expiry time (expires_in) is typically 3600 seconds
• Token is cached and reused until expiry

Common Failures: See Error: Auth token is not valid below

Step 2: Test Each Integration Method

2.1 Hosted Checkout Testing

{
  "merchant_id": "8739528",
  "reseller_id": "your-partner-uuid",
  "txnid": "HC_TEST_001",
  "amount": "100.00",
  "productinfo": "Test Product",
  "firstname": "Test",
  "email": "[email protected]",
  "phone": "9876543210",
  "surl": "https://yoursite.com/success",
  "furl": "https://yoursite.com/failure",
  "curl": "https://yoursite.com/cancel",
  "hash": "<computed_hash>"
}

{
  "status": "success",
  "redirectUri": "https://test.payu.in/checkout?token=abc123xyz...",
  "txnid": "HC_TEST_001"
}

mihpayid=<PayU_Transaction_ID>
txnid=HC_TEST_001
status=success
amount=100.00
productinfo=Test Product
firstname=Test
[email protected]
hash=<response_hash>
...

2.2 UPI Intent Testing

{
  "merchant_id": "8739528",
  "reseller_id": "your-partner-uuid",
  "txnid": "UPI_INTENT_001",
  "amount": "250.00",
  "productinfo": "UPI Test",
  "firstname": "Customer",
  "email": "[email protected]",
  "phone": "9123456789",
  "txn_s2s_flow": "4",
  "s2s_client_ip": "192.168.1.100",
  "s2s_device_info": "Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36",
  "hash": "<computed_hash>"
}

{
  "status": "success",
  "txnid": "UPI_INTENT_001",
  "intentURIData": "upi://pay?pa=payu@icici&pn=PayU&tr=UPI_INTENT_001&am=250.00&cu=INR&tn=Payment..."
}

2.3 UPI TPV Testing

{
  "merchant_id": "8739528",
  "reseller_id": "your-partner-uuid",
  "txnid": "TPV_TEST_001",
  "amount": "500.00",
  "productinfo": "TPV Payment",
  "firstname": "Borrower",
  "email": "[email protected]",
  "phone": "9988776655",
  "txn_s2s_flow": "4",
  "s2s_client_ip": "203.0.113.50",
  "s2s_device_info": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0)",
  "beneficiarydetail": "{\"ifscCode\":\"SBIN0001234\",\"accountNumber\":\"12345678901\",\"accountHolderName\":\"BORROWER NAME\"}",
  "hash": "<computed_hash>"
}

{
  "status": "success",
  "txnid": "TPV_TEST_001",
  "intentURIData": "upi://pay?pa=payu@icici&pn=PayU&tr=TPV_TEST_001&am=500.00...",
  "bankcode": "INTTPV",
  "api_version": "6"
}

mihpayid=<PayU_Transaction_ID>
txnid=TPV_TEST_001
status=success
amount=500.00
bankcode=INTTPV
mode=UPI
unmappedstatus=captured
hash=<webhook_hash>

Step 3: Webhook Testing

3.1 Configure Partner Webhooks

Required Webhook URLs:

• partner_webhook_success — Triggered on successful payment
• partner_webhook_failure — Triggered on failed payment
• partner_webhook_cancelled — Triggered when customer cancels payment

Configuration:
Contact PayU support to register your partner webhook URLs. Provide:

• Your reseller_id (partner UUID)
• HTTPS URLs for all three webhook types
• IP whitelist (if required for your firewall)

3.2 Webhook Hash Verification

All webhooks from PayU include a hash parameter for verification.

Reverse Hash Formula:

client_secret|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|merchant_id

Note: Five pipes after status, then reverse order of request parameters

Verification Steps:

1. Extract parameters from webhook POST body
2. Compute reverse hash using formula above
3. Compare computed hash with webhook hash parameter
4. Case-sensitive comparison — hashes must match exactly

Example (Python):

import hashlib

def verify_webhook_hash(webhook_data, client_secret):
    hash_string = (
        f"{client_secret}|{webhook_data['status']}||||||"
        f"{webhook_data.get('udf5', '')}|{webhook_data.get('udf4', '')}|"
        f"{webhook_data.get('udf3', '')}|{webhook_data.get('udf2', '')}|"
        f"{webhook_data.get('udf1', '')}|{webhook_data['email']}|"
        f"{webhook_data['firstname']}|{webhook_data['productinfo']}|"
        f"{webhook_data['amount']}|{webhook_data['txnid']}|"
        f"{webhook_data['merchant_id']}"
    )
    
    computed_hash = hashlib.sha512(hash_string.encode('utf-8')).hexdigest()
    return computed_hash == webhook_data['hash']

# Usage
if verify_webhook_hash(webhook_data, client_secret):
    # Process webhook
    pass
else:
    # Reject webhook
    pass

Validation Checklist:

• Webhook arrives within 5–10 seconds of payment
• All expected fields are present (mihpayid, txnid, status, amount, hash)
• Hash verification passes
• Webhook is idempotent (handle duplicate webhooks)

3.3 Webhook Testing Checklist

For Each Integration Method:

Step 4: Payment Verification API Testing

4.1 Call Verify Payment API

Endpoint: POST https://test-partnerapilayer.payu.in/verifyPayment

Test Payload:

{
  "merchant_id": "8739528",
  "txnid": "TPV_TEST_001"
}

Expected Response (Success):

{
  "status": "success",
  "mihpayid": "403993715529111111",
  "txnid": "TPV_TEST_001",
  "amount": "500.00",
  "productinfo": "TPV Payment",
  "firstname": "Borrower",
  "email": "[email protected]",
  "mode": "UPI",
  "bankcode": "INTTPV",
  "unmappedstatus": "captured",
  "payment_source": "payu"
}

4.2 Reconcile Webhook vs Verify API

Validation Checklist:

• mihpayid matches in both webhook and verify response
• txnid matches original request
• status and unmappedstatus are consistent
• amount matches original request
• For TPV: bankcode is INTTPV
• No discrepancies between webhook and verify API

Reconciliation Logic:

IF webhook.status == verify_api.status
  AND webhook.mihpayid == verify_api.mihpayid
  AND webhook.amount == verify_api.amount
THEN
  Mark transaction as confirmed
ELSE
  Flag for manual review

Common Errors and Resolutions

Error: Invalid hash

Error Message:

Could not validate hash

Cause:
The payment request hash computed by your system doesn't match PayU's computed hash.

Resolution:

1. Verify the hash formula:

   merchant_id|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||client_secret

   Note: Six consecutive pipes (||||||) between udf5 and client_secret

2. Use client_secret, not salt — Partner Payments API requires client_secret (from OAuth credentials)

3. Check for empty fields — Empty fields should be represented as empty strings between pipes

4. Verify SHA-512 hex output — Ensure your hash is lowercase hexadecimal (128 characters)

5. For UPI TPV: Ensure beneficiarydetail is NOT included in hash calculation

Debug Example (Java):

String hashString = merchantId + "|" + txnid + "|" + amount + "|" + productinfo + "|" +
                   firstname + "|" + email + "|" + udf1 + "|" + udf2 + "|" + udf3 + "|" +
                   udf4 + "|" + udf5 + "||||||" + clientSecret;

System.out.println("Hash String: " + hashString);
// Expected: 8739528|TXN001|518.02|Payment|||||||||||whatsapp||||||YOUR_CLIENT_SECRET

String hash = sha512Hex(hashString);
System.out.println("Computed Hash: " + hash);
System.out.println("Hash Length: " + hash.length()); // Should be 128

Error: Auth token is not valid

Error Message:

Auth token is not valid

Cause:

• Access token has expired (default expiry: 3600 seconds)
• Token doesn't have the required scopes
• Token was generated for different environment (UAT vs production)
• Token is missing from the Authorization header

Resolution:

1. Regenerate the token — Complete all three OAuth steps:

   • Step 1: Password grant with reseller credentials
   • Step 2: Request authorization code for merchant
   • Step 3: Exchange code for final access token

2. Verify scopes:

   scopes=create_payment_links partner_payment_links partner_payments

3. Check header format:

   Authorization: Bearer YOUR_ACCESS_TOKEN

4. Implement token caching:

import time

class TokenCache:
    def __init__(self):
        self.access_token = None
        self.expiry_time = 0
    
    def get_token(self):
        if time.time() >= self.expiry_time:
            # Regenerate token
            self.access_token = self._generate_new_token()
            self.expiry_time = time.time() + 3600  # 1 hour
        return self.access_token

Error: Transaction not found

Error Message:

Transaction not found / No data found for given transaction details

Cause:
Transaction has not yet been persisted in PayU's system. This can happen immediately after initiating a payment.

Resolution:

1. Wait 2–3 seconds before calling Verify Payment API
2. Implement retry logic with exponential backoff
3. Verify txnid is correct and matches original request

Retry Logic Example (Python):

import time
import requests

def verify_payment_with_retry(merchant_id, txnid, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            'https://test-partnerapilayer.payu.in/verifyPayment',
            json={'merchant_id': merchant_id, 'txnid': txnid}
        )
        
        if response.status_code == 200:
            data = response.json()
            if data.get('status') != 'Transaction not found':
                return data
        
        # Exponential backoff: 2s, 4s, 8s
        wait_time = 2 ** attempt
        time.sleep(wait_time)
    
    raise Exception(f"Transaction {txnid} not found after {max_retries} retries")

Error: partner payment webhook not present/enabled

Error Message:

partner payment webhook not present/enabled for given merchant

Cause:
Partner-level webhooks are not configured in PayU's system for your reseller_id.

Resolution:

1. Contact PayU Support to configure partner webhooks
2. Provide the following:
   • Your reseller_id (partner UUID)
   • Webhook URLs (success, failure, cancel)
   • Whether webhooks should be enabled globally for all your merchants

Important: Partner webhooks are configured at the partner level (reseller), not individual merchant level.

Error: s2s_client_ip or s2s_device_info is mandatory

Error Message:

s2s_client_ip and s2s_device_info are mandatory when txn_s2s_flow is 4

Cause:
UPI Intent and UPI TPV flows (txn_s2s_flow=4) require customer IP address and device information for security and fraud prevention.

Resolution:

1. Capture customer IP address:

   • From HTTP headers: X-Forwarded-For or REMOTE_ADDR
   • Send as string in s2s_client_ip parameter

2. Capture device user-agent:

   • From HTTP header: User-Agent
   • Send as string in s2s_device_info parameter

Example (Node.js/Express):

app.post('/initiate-payment', (req, res) => {
  const clientIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
  const deviceInfo = req.headers['user-agent'];
  
  const paymentPayload = {
    merchant_id: '8739528',
    txnid: 'TXN001',
    amount: '100.00',
    txn_s2s_flow: '4',
    s2s_client_ip: clientIp,
    s2s_device_info: deviceInfo,
    // ... other parameters
  };
  
  // Send to PayU API
});

Error: Could not validate HMAC header

Error Message:

Could not validate HMAC header signature

Cause:
HMAC signature validation failed for QR/omnichannel payment requests.

Resolution:

1. Verify all required headers are present:

   • X-Payu-Signature
   • X-Payu-Timestamp
   • X-Payu-Nonce

2. Check timestamp — Must be within ±5 minutes of current server time

3. Confirm signing key — Use the correct HMAC secret provided by PayU

Log Patterns for Debugging

Use these grep patterns to locate relevant log entries:

Hash Validation Failures:

grep -i "hash.*invalid\|could not validate hash" app.log

Webhook Send/Receive:

grep -i "webhook.*sent\|partner_webhook" app.log

Payment Verification Calls:

grep -i "verifyPayment\|verify.*payment" app.log

Transaction Not Found Errors:

grep -i "transaction not found\|no data found" app.log

S2S Flow Errors:

grep -i "s2s_client_ip\|s2s_device_info\|txn_s2s_flow" app.log

OAuth Token Issues:

grep -i "auth token.*not valid\|token.*expired\|401" app.log

Test Data

UAT Credentials

Sample Transaction IDs

Use descriptive, unique transaction IDs for easy tracking:

HC_UAT_20240315_001    (Hosted Checkout)
UPI_INTENT_20240315_001 (UPI Intent)
TPV_UAT_20240315_001   (UPI TPV)

Sample Customer Data

{
  "firstname": "TestUser",
  "email": "[email protected]",
  "phone": "9876543210"
}

Sample UDF Values

{
  "udf1": "session_12345",
  "udf2": "app_android",
  "udf3": "v2.1.0",
  "udf4": "",
  "udf5": ""
}

Sample Beneficiary Details (UPI TPV)

{
  "ifscCode": "SBIN0001234",
  "accountNumber": "12345678901",
  "accountHolderName": "TEST ACCOUNT HOLDER"
}

End-to-End Integration Checklist

Use this checklist to validate your complete integration before going live:

OAuth Flow

• Step 1: Reseller password grant succeeds
• Step 2: Merchant authorization code obtained
• Step 3: Final access token contains all required scopes
• Token caching and refresh logic implemented

Payment Initiation

• Hash generation follows correct formula
• client_secret used (not merchant salt)
• All mandatory parameters included
• For S2S: s2s_client_ip and s2s_device_info captured
• For TPV: beneficiarydetail excluded from hash

Hosted Checkout (if applicable)

• redirectUri returned successfully
• Customer redirect to PayU works
• Hosted page loads with correct branding
• Test payments complete successfully
• Customer redirected to surl/furl based on outcome

UPI Intent/TPV (if applicable)

• intentURIData returned in response
• UPI app launches correctly on mobile device
• Payment details pre-filled in UPI app
• Customer can authenticate and complete payment
• For TPV: Account validation works (success and failure scenarios)

Webhook Handling

• Partner webhooks configured in PayU system
• Webhook URLs are HTTPS and publicly accessible
• Webhook hash verification implemented
• Idempotency handling prevents duplicate processing
• Webhook arrival time acceptable (< 10 seconds)
• For TPV: bankcode=INTTPV validated

Payment Verification

• Verify Payment API called after webhook
• Response reconciled with webhook data
• mihpayid, txnid, amount, status match
• Retry logic handles "transaction not found" errors
• Final payment status persisted in your system

Error Handling

• Hash validation errors logged and debugged
• Token expiry handled with automatic refresh
• Transaction not found errors retry with backoff
• Invalid webhook signatures rejected
• All errors logged with sufficient context

Reconciliation

• Daily reconciliation process in place
• Webhook vs Verify API discrepancies flagged
• Manual review process for failed/stuck transactions
• Settlement reports downloaded from PayU dashboard

Going Live Checklist

Before switching to production:

Credential Updates

• Production client_id and client_secret obtained
• Production merchant_id and reseller_id configured
• Production OAuth endpoints updated in code
• Production API endpoints updated (https://partnerapilayer.payu.in)

Final Validation

• Conduct live transaction in production (small amount)
• Verify production webhook delivery
• Confirm production Verify Payment API works
• Validate production reconciliation process
• Check production settlement in PayU dashboard

Infrastructure

• Webhook URLs whitelisted on firewall
• SSL certificates valid for all callback URLs
• Load balancing configured (if high volume expected)
• Monitoring and alerting set up for payment failures

Documentation

• API integration document updated
• Runbook created for common errors
• Contact information for PayU support documented
• Escalation process defined for critical issues

Support

For unresolved issues or technical questions, contact PayU Partner Support with:

Required Information:

• Your reseller_id (partner UUID)
• Merchant ID(s) involved
• Integration method (Hosted Checkout / UPI Intent / UPI TPV)
• Detailed error description
• Sample txnid exhibiting the issue
• Timestamp of the transaction
• Full error message and relevant logs
• Steps to reproduce (if applicable)

Support Channels:

• Partner Portal: https://partner.payu.in/support
• Email: [email protected]
• Phone: [Contact information from PayU]

Related Documentation

• Partner Payments Overview
• Hosted Checkout Integration Guide
• UPI Intent Integration Guide
• UPI TPV Integration Guide
• Getting Access Token (OAuth)
• Verify Payment API