feat: add com.razorpay.upi.circle UPI Circle payment handler

[paraskathuria-dev]

Summary

Adds the com.razorpay.upi.circle payment handler for delegated UPI payments (UPI Circle / NPCI delegation framework).

UPI Circle lets a buyer authorize a platform to make UPI payments on their behalf within pre-configured mandate limits — no per-transaction MPIN, no buyer interaction at payment time.

Architecture

Follows the credential-before-Complete-Checkout pattern (same as com.google.pay and dev.shopify.shop_pay). Razorpay serves dual roles: Credential Provider (issues cryptograms) and PSP (processes the delegated debit).

Platform             Razorpay (Credential Provider)
   │                              │
   │── fetch cryptogram ─────────>│   (one-time cryptogram for delegate_id)
   │<─ { cryptogram, expires_at } │
   │
   │              Business (UCP)
   │── Complete Checkout ────────>│   (upi_circle instrument + upi_circle_cryptogram credential)
   │<─ completed ─────────────────│   (straight to completed — no escalation)

Participants (UCP terminology)

Participant	Role
Business	Advertises handler config; processes cryptogram via Razorpay; responds completed
Platform	Discovers handler; fetches cryptogram from Razorpay; submits Complete Checkout
Razorpay (PSP)	Processes delegated debit via NPCI; fires webhook to business
Razorpay (Credential Provider)	Issues one-time cryptograms for established delegation mandates

Design Decisions

Decision	Choice	Rationale
Credential type	upi_circle_cryptogram	Cryptogram is single-use and time-limited — distinct from VPA-input credentials
Instrument field	delegate_id	Persistent mandate reference — like a card vault token; actual VPA resolved by PSP
business_config fields	business_id + environment only	Mandate limits are enforced by NPCI/bank at delegation layer, not UCP config
response_config fields	environment only	Per-txn/monthly limits are mandate-level, not UCP config parameters
Delegation setup	Out-of-band, not part of UCP	One-time bilateral integration between Platform and Razorpay — analogous to saving a card on ChatGPT

Files Changed

New schemas (shopping layer):

• source/schemas/shopping/types/upi_circle_instrument.json — upi_circle instrument with delegate_id, display.delegator_name, display.masked_vpa
• source/schemas/shopping/types/upi_circle_credential.json — upi_circle_cryptogram credential with cryptogram, delegate_id, expires_at

New handler:

• source/handlers/razorpay-upi-circle/schema.json — top-level handler schema for com.razorpay.upi.circle
• source/handlers/razorpay-upi-circle/types/business_config.json — business_id + environment
• source/handlers/razorpay-upi-circle/types/platform_config.json — environment
• source/handlers/razorpay-upi-circle/types/response_config.json — environment
• source/handlers/razorpay-upi-circle/types/upi_circle_instrument.json — handler-level available instrument wrapper

New specification doc:

• docs/specification/razorpay-upi-circle-payment-handler.md — full handler spec: delegation setup (out-of-band), payment flow, business/platform/PSP integration guides, error handling table, security considerations

Test plan

• Schema validation: upi_circle_instrument.json extends payment_instrument.json via allOf, no additionalProperties: false, no redeclared base fields
• Schema validation: upi_circle_credential.json extends payment_credential.json via allOf, type discriminator is upi_circle_cryptogram
• Handler schema: com.razorpay.upi.circle declared correctly in schema.json
• business_config validates: accepts { "business_id": "...", "environment": "test" } and rejects missing required fields
• platform_config validates: accepts { "environment": "production" } and rejects unknown enum values
• response_config validates: accepts { "environment": "test" } — no limit fields present
• Spec doc: delegation setup section is clearly marked as out-of-band / outside UCP
• Spec doc: payment flow diagram shows credential fetch BEFORE Complete Checkout (no escalation step)
• Spec doc: error handling table covers mandate-expired, cryptogram-replayed, limit-exceeded cases
• mkdocs build completes without errors

🤖 Generated with Claude Code

[shiv9091]

Can you please add more details on -

1. How are you solving for Agent hallucination for the commerce items, given it is not shown on the trusted surface?
2. How are you capturing user consent for order confirmation and payment?
3. How would PSP verify that the user has indeed confirmed for the purchase for specific set of items and for a specific merchant and amount?
4. What is preventing Agent to pay to anyone in this mechanism?
5. Will the TPAP/PSP app be forced to open for every transaction to show a system-level confirmation UI, or is this intended to be a fully backgrounded flow?
6. How does the protocol distinguish between a human click and an Agent-simulated click to ensure "User Presence" during a delegated payment trigger?

[paraskathuria-dev]

Thanks for the comments @shiv9091

Q1. How are you solving for Agent hallucination for the commerce items, given it is not shown on the trusted surface?
A1. The business owns the checkout state. The agent can only complete a checkout the business created — it can't inject items into a cart. If the agent hallucinates, the business's checkout won't match, and the user catches the mismatch at the review step. This happens before Razorpay is even in the picture, razorpay only get involved after the user has confirmed the order on a trusted.

Q2. How are you capturing user consent for order confirmation and payment?
A2. Razorpay captures consent at the delegation layer; UCP handles it at the transaction layer. Delegation setup (one-time): The user opens their UPI app, enters MPIN, and sets mandate limits themselves. Razorpay acts as the TPAP facilitating this — but we never see the user's MPIN or bank credentials. That interaction is entirely between the user and their bank. Once complete, the delegate_id represents standing consent. The user can revoke it from their UPI app. Consent is by mandate, the user pre-authorizes a spending, and each payment within it is legitimate under that standing authorization.

Q3. How would PSP verify that the user has indeed confirmed for the purchase for specific set of items and for a specific merchant and amount?
A3. Razorpay verifies at three checkpoints in our role as PSP:

• At cryptogram issuance — We only issue a cryptogram for an active delegate_id with a valid mandate. No active mandate means no cryptogram, which means no payment can proceed. This is our first gate.
• At debit processing via NPCI — When we submit the debit request, NPCI validates the amount against the mandate's per-transaction and monthly limits. Over the limit, the transaction is rejected at the banking layer.
• Via UCP checkout binding — The credential is bound to a specific checkout_id, so it can't be replayed at a different merchant or for a different order. If AP2 mandates are active, there's also cryptographic proof that the user approved that exact checkout.

Q4. What is preventing Agent to pay to anyone in this mechanism?
A4. The agent doesn't pick the payee. The business creates the checkout with a specific merchant and amount. The agent can only complete that checkout, it can't redirect payment to a different destination through UCP. Razorpay only processes the debit for the payee the business specified. Razorpay acts as a payment provider for UPI Circle as a payment method. Guidelines are provided by NPCI.

Q5. Will the TPAP/PSP app be forced to open for every transaction to show a system-level confirmation UI, or is this intended to be a fully backgrounded flow?
A5. User needs to As the TPAP, Razorpay's role in the transaction is entirely server-side:

• Platform calls our API → gets a cryptogram (no user interaction).
• Business calls us to process → we debit via NPCI (server-to-server)
• Transaction completes — no app switch, no MPIN, no QR code
  User interaction would be during creating the mandate token for consecutive debits. This is where the intent is provided and user can be involved.

Q6. How does the protocol distinguish between a human click and an Agent-simulated click to ensure "User Presence" during a delegated payment trigger?
A6. The key idea is that the user’s intent at the time of creating a UPI mandate is what authorizes all future payments, not individual transaction clicks. The mandate is set up directly by the user through secure authentication like MPIN or biometrics, making it a deliberate, human-approved action. Once created, it becomes a cryptographic authorization that defines what payments are allowed, while strict limits ensure safety at the banking layer. Instead of verifying every transaction, the system relies on the fact that the user explicitly consented upfront to a controlled payment pattern and can modify or revoke it anytime.

If you want to know more about UPI Circle, here are some reference

1. https://razorpay.com/blog/what-is-upi-circle/
2. www.npci.org.in/product/upi-circle.
3. www.bhimupi.org.in/upi-circle