What API rate-limit protections should we build before launching a new integration with Checkout.com?

• Start with Boundary Testing (Cap Limits)

Simulate transactions that hit just below, at, and above the new per-transaction and daily caps.
For example: ₹9,99,999 (should succeed), ₹10,00,001 (should fail). Then process refunds for those successful ones and confirm the system doesn’t exceed the aggregate daily reversal limit. This ensures your refund logic respects NPCI caps in both directions.

• Validate Partial Refunds

Insurance payments often get partially refunded when policy terms change. Test partial refunds for both small (e.g., ₹5,000) and large (e.g., ₹2 lakh) cases and check that your platform correctly posts only the refunded portion to the ledger and updates the customer balance without duplicating entries.

• Simulate Auto-Reversals

Sometimes UPI transactions fail mid-flight but the customer’s account is debited. NPCI and PSPs auto-reverse those within T+1. Test that your platform recognizes these incoming reversals, matches them to the original transaction (via RRN/UPI Ref ID), and updates both the customer and insurer accounts correctly.

• Chargeback Scenarios

Even though UPI technically doesn’t have chargebacks like cards, disputes can still be raised (especially for duplicate debits or policy cancellations). Test dispute handling workflows, when the insurer rejects or accepts the claim and verify how your ledger adjusts the amount (credit to buyer, debit to insurer).

• Refund Timing Compliance

UPI refunds have strict time windows (typically must be initiated within 24 hours for failed debits, or up to 5 days for policy cancellations). Test how your platform behaves if the refund window expires it should show an error, not attempt a refund call that NPCI will reject.

• Settlement Date Consistency

For refunds processed after midnight, ensure your ledger records them under the correct settlement date, not the original transaction date. This keeps your daily reports and GST reconciliation clean.

• Cross-Bank Handle Testing

Insurance premiums can use multiple PSP handles (@axis, @hdfcbank, @icici, etc.).
Test refunds across these handles because refund acknowledgments may vary slightly between banks. Some banks send delayed confirmations for high-value reversals.

• Duplicate Refund Protection

Make sure your refund job or API doesn’t retry on a delayed acknowledgment and issue double refunds. You can test this by intentionally delaying the PSP’s success callback and observing if your retry logic behaves correctly.

• Negative Balance Handling

In rare cases, a reversal might hit after the insurer’s share has already been settled.
Test that your system logs this as a negative insurer payable and handles it in the next settlement run, not as an ad-hoc manual adjustment.

• Reporting & Alerts Validation

Run test cases where multiple refunds hit your threshold (say >₹5 lakh refunded in a day). Confirm your finance team gets an alert and that your reconciliation report correctly shows total UPI inflows, refunds, and pending reversals separately.

If you’re running a subscription billing engine that handles insurance premiums via UPI, the new NPCI category-wise limits (effective Sept 15, 2025) mean your finance team needs better visibility into daily usage, otherwise you’ll hit caps mid-day and scramble to fix payments manually.
Here’s what I’d suggest from experience (we had to do this for our fintech billing stack):

• Daily Limit Warnings

Set up an alert when you’ve used about 80–90% of your daily UPI cap for insurance transactions.
It’s a simple sum of today’s successful payments vs the category cap. This gives your team time to pause auto-debits or route new payments to netbanking/cards before hitting the hard stop.

• Hard Limit Blocks

If a payment attempt will exceed the daily cap or the per-transaction cap, block it right away.
Send an alert to finance + support so they can notify the customer with alternate payment options.

• Settlement Lag Alerts

Keep an eye on how long it takes for settlements to hit your account.
If payments stay pending beyond 2–4 hours, trigger an alert, sometimes PSPs (like banks) delay insurance premium settlements during high load hours.

• Refund Spike Alerts

If you suddenly see a jump in refunds or reversals (say >5% of transactions in a day), that’s a red flag, it could mean duplicate charges or a UPI handle issue.

• Unsettled Amount Check

By end of day, compare how much you collected vs how much got settled.
If there’s a mismatch above your tolerance level, alert your reconciliation team before closing the books.

• PSP Handle Failures

Sometimes one UPI handle (like @axis or @icici) has downtime.
Track failures per handle, and if more than 10% of attempts start failing for 15+ mins, route traffic to a backup handle.

• Purpose Code Check

Make sure every transaction is tagged with the correct purpose code for insurance, this saves you a lot of audit pain later.
Alert if any payment goes out with a missing or wrong code.

• Reconciliation Mismatch

Cross-check your internal records vs PSP/bank reports.
If the difference exceeds 0.5% or ₹X (whatever threshold makes sense for your business), raise an alert.

• Daily Counter Reset

Double-check that your daily counters reset at midnight, because NPCI caps are per calendar day.
If it doesn’t reset, you’ll accidentally reject valid transactions or, worse, exceed the limit unknowingly.

• Latency/Timeout Monitor

Track UPI response times. If you’re seeing more than 2-second averages or 5% timeouts, send an alert to your devops/finance team, this affects success rates during peak hours.

Canonical merchant metadata

• Maintain a merchant_profile that includes: MCC / NPCI category, verified flag (yes/no), sponsor bank/PSP IDs, and the official daily & per-txn caps for that category.
• Keep this data synced daily from your PSP or acquirer (don’t hardcode assumptions).

Keep real-time daily usage counters

• Track upi_volume_today per merchant (and optionally per merchant+PSP handle) in a fast store (Redis). Increment only after final success confirmation (webhook or settlement ack).
• Persist an authoritative copy in your DB for audits.

Pre-debit validation flow (run BEFORE initiating UPI collect)
When a subscription payment is due:

• Lookup merchant category & cap: cap_txn, cap_day = (verified ? high_cap : normal_cap).
• Read used_today = upi_volume_today and remaining = cap_day - used_today.
• If amount <= min(cap_txn, remaining) → proceed with UPI collect.
• If amount > min(cap_txn, remaining) → do not fire the UPI collect. Instead route to fallback (card, netbanking) or auto-split logic (if supported).

Support for splits / deferred attempts

• If you allow auto-split: compute compliant legs (each ≤ per-txn cap and within remaining daily allowance), create a payment_plan record with leg IDs, and execute legs sequentially (prefer sequential to avoid race conditions).
• If you allow scheduling: queue remaining amount for next valid window and notify customer (don’t auto-debit without consent if policy requires).

Real-time sync with PSPs & webhooks

• Rely on PSP webhooks for PAYMENT_SUCCESS, PAYMENT_FAILED, REFUND, REVERSAL. Only increment the upi_volume_today on a confirmed success webhook (or settlement confirmation).
• If webhooks are lost, reconcile via periodic pull or settlement file to avoid drifting counters.

Race conditions & concurrency protection

• Use optimistic locking or atomic Redis ops (INCRBY with check) when reserving remaining capacity just before initiating collect: reserve → call PSP → on success commit, on failure release.
• Idempotency keys per subscription+attempt so retries won’t double-count.

Fallback UX & orchestration

• If pre-check fails, surface a clear, friendly message: UPI limit reached for today — choose card, netbanking, or schedule. Offer one-tap fallback with invoice/policy prefilled.
• For partial-success (split legs), show progressive updates: ₹X of ₹Y paid via UPI; remaining ₹Z — pay now with card or we’ll retry tomorrow.

Mandate / autopay rules

• For UPI AutoPay mandates, verify that mandate is valid and that the bank supports multi-leg/large value AutoPay (some banks differ). If a mandate would breach daily cap, don’t attempt — schedule or prompt for alternate method.

Reconciliation & accounting hooks

• Persist PSP txn refs and map every successful leg to the subscription invoice. Reconcile by UPI ref/UTR.
• Distinguish Received (Pending settlement) GL vs Settled GL; only finalize revenue when settlement/confirmation arrives (or per your revenue rules).

Notifications & audit trail

• Send pre-debit notification where required. Log pre-check result, decision, API payloads, PSP response codes, and who/what fallback was chosen. Keep this for compliance and dispute resolution.

Monitoring & alerts

• Alert when failed due to limit events spike. Add dashboards: daily cap usage per merchant, split success rate, number of fallbacks, and reconciliation mismatches.

Edge cases & tests

• Test concurrent debits that together exceed remaining allowance.
• Test midnight boundary (cap reset) and cross-day splits.
• Simulate webhook loss and settlement lag to ensure counters reconcile.
• Test refunds: refunded amount should decrement upi_volume_today if PSP semantics require (verify with PSP whether refunds free up cap).

Policy & UX decisions to finalize

• Decide if you will auto-split or force fallback when over cap. (Auto-split is smoother but more complex.)
• Decide whether to block subscription processing or schedule retries when cap is hit.

Testing refunds and chargebacks for insurance premiums under the new UPI cap structure involves verifying compliance with new mandates, simulating different scenarios, and confirming system responses through multiple checkpoints. The process must account for the new Bima-ASBA (Applications Supported by Blocked Amount) guidelines from the IRDAI and updated chargeback rules from the National Payments Corporation of India (NPCI).

Exporting UPI reference IDs for insurance premium payments into your GST e-invoice PDF presupposes a cooperating flow of mobile app's checkout and invoicing backend wherein payment data gets embedded cleanly and compliantly in the final invoice. Here is the simplest, audit-friendly way to do it:

Your app should seize the UPI transaction reference ID (UTR or NPCI reference number) after the customer makes a UPI payment through the payment gateway or PSP callback. Now store that ID together with other invoice metadata, tax invoice number, GSTIN, payment method, and amount, in your ERP or invoicing service. The important thing is to consider this UPI reference ID as part of the payment details object linked to that invoice, not merely a transaction log entry.

Subsequently, while creating the GST e-invoice JSON (the format that is sent to the IRP for verification), the field in Payment Information or the extra information section (like PayeeRefNo or OtherPaymentInfo) should be filled with the UPI reference ID and clearly marked, e.g., UPIRefNo: 1234567890ABCDEF. Once the IRP has validated it and provided the Invoice Reference Number (IRN) and QR code, you can then display both the IRN and the UPI reference ID in your PDF template.

For better understanding and compliance with the law, the UPI reference ID must be visible: either

• Under the Payment Details section (under the mode of payment), or
• In a separate Transaction Details block showing Payment Mode: UPI and Reference ID: 1234567890ABCDEF.

If you are employing a PDF library (such as ReportLab, wkhtmltopdf, or iText), modify your template so that it automatically retrieves the UPIRefNo field whenever the payment mode is UPI.

Lastly, ensure that this field is in sync with your GST audit trail since auditors frequently cross-verify invoice payments with the UPI reference ID mentioned in bank statements, and thus having it integrated into your e-invoice PDF makes reconciliation easy.