feat: add com.razorpay.upi UPI Intent payment handler

[paraskathuria-dev]

Summary

Introduces a complete UCP payment handler specification for UPI Intent payments via Razorpay (com.razorpay.upi), bringing Indian UPI support into the UCP ecosystem.

UPI (Unified Payments Interface) is India's real-time bank-to-bank payment system managed by NPCI. This handler uses the UPI Intent flow — the platform deep-links the buyer into their preferred UPI app (Google Pay, PhonePe, Paytm, BHIM, etc.) which authorizes the payment. The resulting cryptographic proof from the Razorpay SDK is submitted at checkout.

What's included

Handler spec (docs/specification/razorpay-upi-payment-handler.md):

• Full participant table (Business, Platform, Razorpay as PSP)
• Step-by-step payment protocol with ASCII flow diagram
• Business integration: Razorpay Order creation, HMAC signature verification, payment capture
• Platform integration: SDK initialization, UPI Intent flow, checkout completion
• Security considerations table
• End-to-end test checklist + signature verification code sample

JSON Schemas (source/handlers/razorpay-upi/):

• schema.json — root handler schema for com.razorpay.upi
• types/business_config.json — key_id, environment, merchant_name
• types/platform_config.json — upi_apps (optional app constraint)
• types/response_config.json — runtime config including razorpay_order_id
• types/upi_intent_instrument.json — upi_intent instrument with available_upi_intent_instrument declaration
• types/razorpay_payment_credential.json — razorpay_payment_proof credential (payment_id + order_id + HMAC signature)

Navigation (mkdocs.yml): handler added to nav and llmstxt plugin.

Key design decisions

Decision	Rationale
No tokenization endpoint	UPI doesn't transfer raw payment credentials. The Razorpay HMAC-SHA256 proof is verified locally by the business using their key_secret — no token storage or detokenize API needed.
razorpay_order_id as binding	The business creates a Razorpay Order before responding to checkout and embeds the order_id in response_config. The credential must reference this exact ID, tying the payment proof to the checkout and preventing replay attacks.
Manual capture (payment_capture: 0)	Gives the business the opportunity to verify the HMAC signature before funds are committed. Capture only proceeds after successful verification.
UPI Intent only	UPI Collect is being discontinued. This handler covers Intent exclusively.

How it differs from the processor-tokenizer pattern

The com.razorpay.upi handler is structurally closer to Shop Pay (dev.shopify.shop_pay) than to the processor-tokenizer example — it uses a single fixed instrument type (upi_intent) with no card-brand-style constraints, and the credential is a payment proof rather than a stored token. The key addition is razorpay_order_id in response_config, which serves as the UCP checkout binding and is created by the business backend before returning the checkout response.

Test plan

• Validate JSON schemas against JSON Schema draft 2020-12
• Verify /.well-known/ucp business profile declaration parses correctly
• Create a Razorpay test order (rzp_test_* keys) and confirm order_id format matches schema pattern ^order_[A-Za-z0-9]+$
• Initialize Razorpay SDK with key_id + razorpay_order_id from response_config; confirm intent flow opens
• Confirm SDK callback delivers {razorpay_payment_id, razorpay_order_id, razorpay_signature}
• Verify HMAC-SHA256 signature using the reference Python snippet in the spec
• Confirm binding check rejects a credential with a mismatched razorpay_order_id
• Confirm checkout complete payload matches upi_intent instrument schema
• Confirm mkdocs builds without errors (mkdocs build)

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[shiv9091]

Given this only includes merchant VPA and amount, how could user confirm that they are indeed paying for the right items?

[shiv9091]

Since the intent_uri is passed through the Agent/Platform, what prevents a malicious app or a compromised Agent from tampering with the Payee VPA (pa) or Merchant Code (mc) before the user reaches the bank app? Does the protocol provide a way for the Merchant to cryptographically sign the URI itself?

[shiv9091]

Does the handler mandate a system chooser for the upi:// intent? If a malicious app registers itself as the default handler for UPI intents, it could 'mimic' a bank app UI to steal the user's PIN. How does the protocol ensure the user has landed on a genuine, trusted Bank/TPAP surface?