OryvaPay documentation

Overview

OryvaPay is an AI verification layer that checks an agent's order against the buyer's intent before PayPal captures the money.

A shopping agent builds a cart. The buyer approves a PayPal payment with intent: AUTHORIZE, so the funds are held, not taken. OryvaPay then reads the order PayPal actually received, compares every line with what the buyer asked for, and tells PayPal to capture the payment or void the authorization. Every step is written to a tamper evident Intent Record that both buyer and merchant can use as evidence.

Live demo: Verify a purchase. Source: github.com/rwemmie/oryvapay.

The problem

AI agents now shop for people. The payment can be perfectly valid while the purchase is not what the buyer asked for.

When a buyer approves a payment, the authorization proves consent to pay. It does not prove that the order the merchant charged matches what the buyer wanted. Things slip into an agent built checkout:

• Add on warranties and protection plans nobody asked for
• Surprise subscriptions and repeat billing
• Hidden service or handling fees
• A price change after the buyer approved the quote
• Delivery terms that miss the buyer's deadline
• The wrong item, color, size or quantity

Then the hard question: who pays when an agent buys the wrong thing? Dispute rules were written for humans pressing a buy button.

Google's AP2 specification defines mandates and receipts that can serve as dispute evidence, but leaves detailed dispute resolution, evidence retrieval and retention outside its scope. OryvaPay works on the step before that: checking the order while the money is still only held.

How it works

1. Buyer intent. The buyer writes what they want in plain words. AI turns it into constraints: product, color and size, quantity, max total, merchant, delivery deadline, and whether subscriptions, add ons and service fees are allowed. The buyer reviews and approves them.
2. Agent builds a cart. A shopping agent picks a merchant from the demo catalog and builds an itemized cart.
3. PayPal authorize. OryvaPay creates a PayPal order with intent: AUTHORIZE and every line item. The buyer approves in the PayPal popup and OryvaPay authorizes the order. Funds are held.
4. Verify. OryvaPay reads the order back from PayPal and runs rule checks plus an AI review against the approved constraints.
5. Capture or void. PASS captures. BLOCK voids the authorization and releases the money. In Approval mode the buyer decides.
6. Fix order. After a block, the agent rebuilds the cart without what was flagged. That is a new PayPal order and a new approval, recorded as attempt 2.

Built on PayPal

PayPal is the payment rail for the whole flow. OryvaPay never touches card data; the buyer approves in PayPal.

PayPal is a trademark of PayPal, Inc. OryvaPay is an independent hackathon project and runs in the PayPal sandbox only.

Verification engine

Verification uses the order PayPal returns, not what the agent claims it bought. Two kinds of checks run on every order.

Rule checks

Deterministic checks for anything numeric or exact:

Sneaky charges detector

AI check

The AI reviews meaning: does the item charged actually match the product the buyer described (product_match)? It also writes the plain words explanation shown to the buyer. The live demo uses openai/gpt-oss-120b on Groq through an OpenAI compatible API. If no AI key is set, a local heuristic runs instead and the UI says so.

Modes

Intent Records and the hash chain

Each purchase gets an Intent Record such as IR-20261112-23E2BF. It stores the buyer's words, the approved constraints, every cart attempt with product links, PayPal order, authorization and capture IDs, and the verdict with every check.

Every event is chained with SHA-256:

hash = sha256(prevHash + canonicalJSON({ seq, type, at, data }))

Event types: request_received, constraints_approved, agent_cart_built, paypal_order_created, buyer_approved_authorization, verification_result, payment_captured, authorization_voided, buyer_decision, agent_cart_rebuilt. Changing any past event breaks the chain, and the record page shows where. Each record has a buyer view and a merchant view.

Evidence Pack

Every record can be exported as a printable Evidence Pack at /record/{id}/evidence (save as PDF from the browser) or as JSON at /api/records/{id}/download (format oryvapay.intent-record.v1). It includes the request, constraints, each line charged with its product page, the PayPal IDs, the verdict and the hash chain, so a merchant can show the charged order matched the buyer's own approved intent.

API reference

{ "paypalLive": true, "aiLive": true, "paypalEnv": "sandbox",
  "paypalClientId": "...", "aiModel": "openai/gpt-oss-120b",
  "scenarios": {...}, "modes": {...}, "demoVideo": null }

{ "request": "Black running shoes, size 10, under $80, by Friday" }

{ "constraints": { "product": { "category": "running shoes",
  "attributes": { "color": "black", "size": "10" } }, "quantity": 1,
  "maxBudget": 80, "allowedMerchants": [], "deliveryDeadline": "...",
  "recurringAllowed": false, "extrasAllowed": false,
  "serviceFeesAllowed": false, "parsedBy": "ai" } }

{ "request": "...", "constraints": {...}, "mode": "strict",
  "tolerance": 5, "scenario": "warranty" }

{ "id": "IR-20261112-23E2BF", "status": "OPEN", "attempts": [ { "n": 1,
  "cart": { "items": [ { "sku": "SL-AERO-BLK-10",
  "url": "/store/stridelab/aero-runner-black", ... } ] } } ] }

{ "id": "6TF029115U822433D", "approveUrl": "https://www.sandbox.paypal.com/checkoutnow?token=..." }

{ "authorizationId": "1AL2357750936571K", "status": "CREATED",
  "amount": { "currency_code": "USD", "value": "87.98" } }

{ "id": "...", "status": "BLOCKED", "attempts": [ { "verification": {
  "verdict": "BLOCK", "failedChecks": ["addons", "budget"], ... } } ],
  "chain": { "valid": true, "events": 7 } }

{ "approve": true }

Full record

Full record with a new attempt

{ "ok": true }

Pages: /app, /records, /record/{id}, /record/{id}/evidence, /store/{merchant}/{slug} (demo store product pages).

Testing in the PayPal sandbox

Everything runs in the PayPal sandbox. No real money moves.

1. Open Verify a purchase, keep the example request, pick a scenario and a mode, and approve the rules.
2. Click the PayPal button. In the PayPal window, log in with a PayPal sandbox buyer account, or choose Pay with Debit or Credit Card and use a PayPal sandbox test card such as 4032 0393 1798 4658 with any future expiry, any 3 digit CVV and a US billing address. PayPal may ask you to create a sandbox account with a password; any test email and password work.
3. After approval, OryvaPay authorizes, verifies and captures or voids automatically. The Protection Plan scenario in Strict mode shows a block; then use Fix order to see the clean attempt captured.
4. If the popup is blocked, use "Open PayPal in this tab".

Self hosting

git clone https://github.com/rwemmie/oryvapay
cd oryvapay && npm install
npm start                # http://localhost:3000
npm test                 # end to end test (BASE=http://localhost:3000)

Without PayPal keys OryvaPay runs a simulated PayPal; without an AI key it uses a local heuristic. The UI always says which is active.

Limitations

• PayPal sandbox only. No real money, and PAYPAL_ENV=live has not been tested.
• The hosted demo runs on a free tier with no disk, so Intent Records reset on every deploy or restart. Download the JSON or Evidence Pack to keep one.
• Records are stored in a JSON file, not a database.
• The shopping agent and the StrideLab and PeakGear stores are demo simulations with a small catalog. Product images are AI generated renders of unbranded products.
• Card payments go through PayPal's own approval window; direct card processing is not enabled on the sandbox merchant.

Roadmap

• Persistent storage for Intent Records
• Accept agent mandates and receipts in the AP2 format as intent input
• Merchant webhooks when a payment is blocked
• More sneaky charge categories and per buyer rules
• Live PayPal environment after review