UPI Payment Integration

What this skill does

Use this skill to help users build, review, or troubleshoot UPI integrations that are safe for production.

Covered flows:

• UPI collect requests
• UPI intent payments
• UPI QR payments (static/dynamic)
• UPI autopay / e-mandate recurring payments

Disclaimer

This skill provides implementation and operational guidance only. It does not execute payments, move funds, or replace legal/compliance review. Payment regulations, provider APIs, limits, and policies may change; always verify against the latest official PSP, RBI, and NPCI documentation before production use.

Use at your own risk. The skill author/publisher/developer is not liable for direct or indirect loss, fraud, chargebacks, penalties, downtime, or other damages arising from use or misuse of this guidance.

Always validate in sandbox/staging before production and never share secrets or private keys in chat.

Setup

On first use, read setup.md and confirm:

• provider and environment (sandbox vs production)
• credentials availability in secret manager
• webhook endpoint and verification strategy
• database/reconciliation ownership

Source freshness

• Last verified date: 2026-03-19
• Before production changes, re-check provider docs and current RBI/NPCI circulars.

Source validation checklist

• [ ] Confirm chosen PSP's latest webhook event semantics and retry policy.
• [ ] Confirm latest UPI transaction limits and mandate policy for your use case.
• [ ] Confirm current signature verification/auth requirements from provider docs.
• [ ] Confirm current settlement and reconciliation report fields from provider dashboard.
• [ ] Confirm any newly introduced compliance/legal requirements with your legal/compliance team.

Core operating principles

1. Treat payment lifecycle as asynchronous
• API response is not final truth.
• Webhook + reconciliation determine final status.

1. Make every write idempotent
• De-duplicate by event ID / provider payment ID / merchant request ID.
• Reprocessing the same webhook must be safe.

1. Persist before processing
• Store raw webhook payload and headers first.
• Process in a retriable job/queue.

1. Reconcile continuously
• Poll or fetch status for PENDING, timed-out, or disputed records.
• Close state gaps between app DB, PSP dashboard, and settlement reports.

1. Keep compliance explicit
• Follow RBI authentication and risk controls.
• Keep consent and cancellation paths clear for recurring mandates.

Mandatory implementation checklist

Use this checklist in every implementation/review:

• [ ] Payment state machine exists (CREATED, PENDING, SUCCESS, FAILED, EXPIRED, REFUNDED as applicable).
• [ ] Unique merchant-side request ID/correlation ID is generated and stored.
• [ ] Webhook signature verification is implemented.
• [ ] Raw webhook body is stored before business logic.
• [ ] Duplicate webhook delivery is handled safely.
• [ ] Out-of-order events are handled safely.
• [ ] Retry policy exists for provider/network failures.
• [ ] Reconciliation job exists for stale PENDING records.
• [ ] Refund and reversal flows are explicit.
• [ ] Alerting exists for failure spikes and webhook downtime.
• [ ] Mandate create/pause/cancel paths are implemented and visible to users.

Standard workflow (for the agent)

When user asks for UPI help, do this:

1. Identify integration mode
• Collect vs intent vs QR vs mandate.

1. Map current architecture
• Client request path
• Backend order/payment records
• Provider API call
• Webhook receiver
• Reconciliation worker

1. Enforce reliability controls
• Idempotency keys
• Signature validation
• Event dedupe
• Retries and dead-letter handling

1. Validate business correctness
• No shipment/service unlock before durable success
• Correct handling of late success after apparent failure
• Correct handling of duplicate attempts

1. Validate compliance and customer UX
• Authentication and risk controls
• Consent and cancellation clarity for mandates
• Clear customer-visible status and support trace IDs

Webhook handling rules

• Always verify signature using provider secret.
• Use raw request body for signature validation; do not mutate/parse first.
• Acknowledge quickly (2xx) after durable receipt.
• Process asynchronously.
• Never assume strict event ordering.
• Build handlers as idempotent upserts, not one-time inserts.

Error handling and reconciliation rules

• On timeout, mark local payment as PENDING_RECON (or equivalent), not immediate failure.
• Reconcile by provider payment ID and merchant request ID.
• If provider says success after client saw failure, trust reconciled final state and repair downstream records.
• Log every status transition with source (api, webhook, recon).

Recurring mandate (Autopay) rules

• Treat mandate creation as a first-class object with lifecycle states.
• Store mandate ID, start/end dates, frequency, max amount, and status.
• Support pause/cancel from product UI and backend admin.
• Send pre-debit reminders where required by provider/framework.
• On recurring debit failures, retry only within allowed policy; avoid silent repeated debits.

Compliance and policy guardrails

• Follow RBI authentication expectations (minimum two factors, with dynamic factor requirements where applicable).
• Keep evidence logs for user consent and mandate actions.
• Protect personal/payment data with least-privilege access and retention policy.
• Keep customer grievance paths clear (transaction reference IDs, support response playbook).

Output format

When responding to a user request, return:

1. Architecture or fix plan
2. Concrete code/database changes
3. Failure-mode checks
4. Test plan (happy path + retries + duplicates + out-of-order events + reconciliation)

References

• First-use checklist: setup.md
• Release workflow: launch-playbook.md
• See reference.md for policy and operational notes.
• See examples.md for implementation templates and edge-case patterns.
• See validation-checklist.md for release readiness checks.
• See failure-handling.md for incident and recovery patterns.

Related skills

• upi-go-live-checklist for phase tracking and launch gates
• upi-payment-ux-ops for customer messaging and support operations