UPI Payment Integration

Design and implement robust UPI payment integrations (collect, intent, QR, and autopay mandates) with production-grade webhook handling, idempotency, reconci...

Security Scan

The skill's stated purpose (implementing UPI payment integrations) matches the instructions and the small set of requested environment variables and binaries; nothing requested appears disproportionate or unrelated to the task.

Purpose & Capability

Name/description, required env vars (UPI_PROVIDER_KEY_ID, UPI_PROVIDER_KEY_SECRET, UPI_WEBHOOK_SECRET, UPI_MERCHANT_ID) and required binaries (curl, jq) are all appropriate and expected for building/troubleshooting UPI integrations. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

SKILL.md focuses on designing/implementing UPI flows, webhook verification, idempotency, reconciliation, and operational checklists. It instructs storing raw webhook payloads, verifying signatures, and using idempotent processing — all within scope. It does not instruct reading unrelated files or exfiltrating data. It warns not to share secrets in chat.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest-risk install surface (nothing is written to disk by the skill itself).

Credentials

Requested env vars are directly tied to UPI provider integrations. The number of required variables is minimal and justified. Optional recommendations (DATABASE_URL, UPI_ENV) are sensible but not required. No unrelated secrets are requested.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent system privileges or modify other skills/config. Autonomy (model invocation) is allowed by default but not combined with other red flags here.

Assessment

This skill appears coherent for UPI integration guidance. Before using it: do not paste real provider secrets or private keys into chat; keep the declared env vars in a secure secret manager and grant access to runtime agents only with least privilege; test all flows in sandbox before production; enforce webhook signature verification and IP allowlisting on your endpoints; and review the provider / RBI / NPCI documentation the skill references. If you plan to grant the agent runtime access to environment variables or secret manager credentials, verify who/what can trigger the agent autonomously and restrict that access. If you need higher assurance, ask the publisher for the origin/source of the skill bundle (it lists an external homepage but source is unknown).

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.

2. Make every write idempotent

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

3. Persist before processing

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

4. Reconcile continuously

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

5. 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.

2. Map current architecture

   • Client request path
   • Backend order/payment records
   • Provider API call
   • Webhook receiver
   • Reconciliation worker

3. Enforce reliability controls

   • Idempotency keys
   • Signature validation
   • Event dedupe
   • Retries and dead-letter handling

4. Validate business correctness

   • No shipment/service unlock before durable success
   • Correct handling of late success after apparent failure
   • Correct handling of duplicate attempts

5. 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