# Razor Dvara

**v0.1.0 · updated 2026-08-22 · gated agentic checkout for COD commerce**

> "I am trying to setup payment methods where I want to charge extra amount for COD Orders."
> — merchant on Shopify Community, Jan 1 2025 ([thread](https://community.shopify.com/t/cod-razorpay/383889), zero replies)

COD is still ~half of Indian e-commerce orders. It also drives most of the returns: Tier-2/3 markets see 58–64% COD but 76–83% of RTO volume (bepragma.ai, Jun 2026). Every failed delivery costs ₹180–240 in logistics alone.

Razor Dvara lets merchants set COD rules once. AI buyers get structured answers. The audit trail proves what happened.

## What this does

| Tool | What it answers |
|------|----------------|
| `cod_fee` | Should COD be allowed? What fee applies? Which rule fired? |
| `partial_cod` | How much should the buyer prepay before delivery? |
| `offer_orchestrator` | Which existing dashboard offer should attach to this order? |
| `rto_risk` | How risky is this delivery? What drives the score? |
| `serviceability_check` | Can we deliver here? Is the backend healthy? |

Every response includes `reason_code` and `rule_id`. Every decision appends to an audit trail. If the backend dies, the edge cache serves stale data with a degraded flag and completes the order prepaid-only.

## Architecture

```
AI buyer / checkout agent
         |
         | MCP (streamable HTTP)
         v
+-------------------------------------------+
| Razor Dvara MCP Server                    |
| 5 tools · zero overlap w/ official 45    |
+-------------------+-----------------------+
                    |
                    v
+-------------------------------------------+
| Policy Engine (src/gates/)                |
| merchant caps · PIN rules → reason + ID  |
+-------------------+-----------------------+
                    |
                    v
+-------------------------------------------+
| Audit Trail (Cloudflare D1)              |
| sequence numbers · UTC · append-only    |
+-------------------+-----------------------+
                    |
                    v
+-------------------------------------------+
| SWR Edge Cache                           |
| 8s origin timeout → stale fallback       |
| degraded flag → fail-closed COD          |
+-------------------------------------------+

Shopify side: Payment Customization Function
  keyed on dvara.cod.eligible metafield
  hides COD when any cart line ineligible
```

Full architecture with protocol lineage: [docs/architecture.md](docs/architecture.md)

## Honest constraints

- Offers are dashboard-create-only. We attach existing offer IDs; we don't mint them.
- RTO/COD Intelligence is dashboard-only with no public API. Our scorer uses calibrated weights from published industry rates — it's not ML.
- Serviceability is an inbound contract we implement ourselves. Magic Checkout's documented 10-second hard kill is the SLA we guarantee.
- Test mode only (`rzp_test_` keys). No real money moves.

## NOT building

- Chat UI — this is infrastructure between agents and money actions, not a conversational product.
- Real ML for RTO scoring — calibrated weights without delivery-outcome data would produce misleading precision.
- Offer creation via API — Razorpay doesn't expose it; pretending otherwise would be dishonest.
- Production deployment — buildathon prototype on test keys.

## Evidence

Every claim maps to a checkable artifact: [docs/EVIDENCE.md](docs/EVIDENCE.md)

## Tests

```bash
pnpm install
pnpm test
```

36 tests across 7 files covering rule evaluation, risk scoring, serviceability,
cache degradation, Shopify function behavior, and end-to-end pipeline determinism.