Troubleshooting

Symptoms

API returns 400 with INVALID_SIGNATURE error code.

Diagnosis

1. Are you using the correct Secret Key (not API Key)?
2. Is the field order correct? Must be: merchantId|merchantTxnId|amount|currency|timestamp
3. Is the amount in paise (integer, not rupees)?
4. Is the timestamp a Unix timestamp in seconds (not milliseconds)?
5. Is the output lowercase hex?

1// WRONG: amount in rupees, ms timestamp
2const input = `${mid}|${txn}|999|INR|${Date.now()}`;
3crypto.createHmac('sha256', API_KEY) // wrong key!
4  .update(input).digest('base64'); // wrong format!

1// CORRECT: paise, seconds, SECRET key, hex
2const input = `${mid}|${txn}|99900|INR|${ts}`;
3crypto.createHmac('sha256', SECRET_KEY)
4  .update(input).digest('hex');

Symptoms

API returns 400 with REQUEST_EXPIRED or INVALID_TIMESTAMP.

Causes

1. REQUEST_EXPIRED — Timestamp is older than 5 minutes. Your server clock may be out of sync.
2. INVALID_TIMESTAMP — Timestamp is missing or more than 1 minute in the future.
3. Using milliseconds instead of seconds (e.g., Date.now() instead of Math.floor(Date.now() / 1000)).

Solution

1. Use Math.floor(Date.now() / 1000) in JavaScript (seconds, not milliseconds)
2. Use int(time.time()) in Python
3. Use time() in PHP
4. Sync your server clock with NTP: sudo ntpdate pool.ntp.org

Symptoms

API returns 400 with a customer field validation error.

Validation Rules

Solution

• Validate these fields on your frontend before calling the API
• All three fields are required — they cannot be empty
• For phone: strip any country code prefix (+91) and spaces before sending

Diagnosis

1. Is your webhook URL registered in Dashboard → Settings → Webhooks?
2. Is the URL publicly accessible (not localhost)?
3. Is it HTTPS? (required for production, TLS 1.2+)
4. Does your server return 200 within 10 seconds?
5. Is your firewall blocking incoming requests from SabPaisa IPs?
6. Has the circuit breaker been triggered? (>50% failure rate pauses delivery for 5 min)
7. Does your URL return a 301/302 redirect? Redirects are not followed and count as failures.

Testing Locally

Use ngrok to expose your local server:

1ngrok http 3000
2# Copy the HTTPS URL and register it in Dashboard

Symptoms

Transaction shows PENDING or PROCESSING but never reaches a terminal state.

Auto-Expiry Rules

Solution

Use the Transaction Enquiry API or webhooks to monitor status:

1async function pollStatus(txnId) {
2  const res = await fetch(`/api/v2/payments/${txnId}/status`);
3  const data = await res.json();
4
5  const terminal = ['SUCCESS','FAILED','EXPIRED','TIMEOUT','CANCELLED'];
6  if (terminal.includes(data.status)) return data;
7
8  await new Promise(r => setTimeout(r, 3000));
9  return pollStatus(txnId);
10}

Common Mistakes

1. Using JSON.stringify(req.body) instead of the raw request body (exact bytes)
2. Using hex digest instead of base64
3. Using the wrong secret (API Key vs Webhook Secret)
4. Not checking timestamp freshness (5 min window)
5. Not using constant-time comparison (crypto.timingSafeEqual)
6. Reading the header as X-Webhook-Signature instead of X-SabPaisa-Signature

1// WRONG: parsed body + hex + wrong header
2const sig = req.headers['x-webhook-signature'];
3const body = JSON.stringify(req.body);
4crypto.createHmac('sha256', secret)
5  .update(`${ts}.${body}`)
6  .digest('hex');

1// CORRECT: raw body + base64 + right header
2const sig = req.headers['x-sabpaisa-signature'];
3const body = req.body.toString('utf8');
4crypto.createHmac('sha256', secret)
5  .update(`${ts}.${body}`)
6  .digest('base64');

Cause

SabPaisa guarantees at-least-once delivery. In rare cases (network issues, race conditions), you may receive the same webhook more than once. This is normal behavior, not a bug.

Solution

1. Use the idempotency_key field from the payload (format: {txn_id}_{status})
2. Before processing, check if this key has already been handled (database or Redis lookup)
3. If already processed, return 200 OK without re-processing
4. Store processed keys for at least 24 hours

Rate Limits

Solution

Implement exponential backoff with jitter:

1async function retryWithBackoff(fn, retries = 3) {
2  for (let i = 0; i <= retries; i++) {
3    try { return await fn(); }
4    catch (e) {
5      if (i === retries || e.status !== 429) throw e;
6      const delay = Math.min(
7        1000 * 2 ** i + Math.random() * 1000,
8        30000
9      );
10      await new Promise(r => setTimeout(r, delay));
11    }
12  }
13}

Causes

• Total refunds exceed original transaction amount
• Refund amount not in paise
• Transaction older than 180 days

Solution

Check remaining refundable amount before issuing:

1// Check remaining refundable amount first
2const refunds = await fetch(
3  `/api/v2/refunds/transaction/${txnId}`,
4  { headers: { 'X-Api-Key': API_KEY } }
5).then(r => r.json());
6
7const remaining = refunds.originalAmount - refunds.totalRefunded;
8if (refundAmount > remaining) {
9  throw new Error(`Max: ${remaining} paise`);
10}

Cause

merchantTxnId must be unique per payment attempt. You are reusing an existing ID.

Solution

Append timestamp to make IDs unique per attempt:

1// Unique per attempt, linked to your order
2const merchantTxnId = `ORD_${orderId}_${Date.now()}`;

Symptoms

• API returns 401 UNAUTHORIZED despite keys looking correct
• Payments work in staging but fail in production
• Checksum passes in staging but fails in production

Diagnosis

1. Staging URL: staging-sb-merchant-api.sabpaisa.in — Production URL: merchant-api.sabpaisa.in
2. Staging keys only work on staging URLs, and vice versa
3. Staging relaxes checksum and timestamp validation — production enforces strictly

Solution

Use environment variables to switch between environments:

1# Switch between staging and production
2SABPAISA_ENV=staging       # or "production"
3SABPAISA_API_KEY=your_staging_key
4SABPAISA_SECRET_KEY=your_staging_secret
5
6# Your code picks the right base URL:
7# staging    → https://staging-sb-merchant-api.sabpaisa.in
8# production → https://merchant-api.sabpaisa.in

Symptoms

• Requests hang for 30+ seconds before failing
• Intermittent ECONNRESET or ETIMEDOUT errors
• 504 GATEWAY_TIMEOUT from the API

Solution

1. Set a 30-second timeout on all API requests
2. Retry on 5xx errors with exponential backoff (max 3 retries)
3. For payment status checks, use webhooks or the Transaction Enquiry API instead of repeated requests
4. If the issue persists, check your server's DNS resolution and outbound firewall rules

1const response = await fetch(url, {
2  signal: AbortSignal.timeout(30000), // 30s timeout
3  headers: { 'X-Api-Key': API_KEY }
4});

Symptoms

• Customer enters UPI ID but gets "VPA not found" on the checkout page
• UPI collect request fails immediately

Common Causes

1. Customer typo in UPI ID (e.g., rahul@ppaytm instead of rahul@paytm)
2. UPI handle does not exist or is deactivated
3. Customer's bank UPI service is down

Solution

• Show clear validation message: "Please check your UPI ID and try again"
• Offer alternative methods (QR code, intent) as fallback
• For sandbox testing, use success@upi, failure@upi, or timeout@upi

Symptoms

• Card details accepted but OTP page fails to load
• Customer sees blank iframe or "page cannot be displayed"
• RuPay card gets OTP page instead of redirect

Causes & Solutions

Symptoms

• UNABLE_TO_VERIFY_LEAF_SIGNATURE or CERT_HAS_EXPIRED
• cURL error: "SSL certificate problem"

Solution

1. Never disable SSL verification in production (verify=False, rejectUnauthorized: false)
2. Ensure your server has up-to-date CA certificates: sudo update-ca-certificates
3. Check that your server's clock is accurate (TLS certificates validate against current time)
4. If using a proxy or CDN, ensure it is not stripping the certificate chain