Agent-ready checkout for any PayPal merchant

How an agent order flows

1. Discover. The buyer agent reads /.well-known/ucp: REST endpoint, capabilities (checkout, fulfillment, discount, order) and payment handlers.
2. Build the cart. POST /checkout-sessions and PUT updates. The agent sends item ids, an address and discount codes; the merchant prices everything (integer cents) and answers ready_for_complete when nothing is missing.
3. Pay. POST /checkout-sessions/{id}/complete with a payment instrument. The merchant calls MCPal charge (or hold with "dev.mcpal.settlement": "authorize"). The MCPal orderRef is derived from the checkout id, so a retried complete can never charge twice.
4. Policy. Totals at or above $250.00 stop at the merchant's approval rule: the checkout answers requires_escalation with a continue_url, and nothing is charged.
5. After the sale. GET /orders/{id} shows the order with PayPal's ids. The merchant ships (capture_hold), releases (void_hold) or refunds (refund) through /orders/{id}/ship|release|refund.

A buyer agent buys coffee

The demo merchant is Coffee Club Supply. A gpt-4.1-mini agent (temperature 0) is told: “Buy two bags of coffee for under $40 in total, shipped. Ship to Sam Sandbox, 2211 N First St, San Jose, CA 95131, US (email sam.sandbox@personal.example.com). Pay with my saved PayPal sandbox payment instrument: handler_id mcpal_paypal_sandbox, type card, credential { type: token, token: sandbox-wallet-token }. Use a discount code if the merchant advertises one. Pick the cheapest shipping. Do not complete the purchase if the total is $40.00 or more.” Its only tools are the UCP operations above; it never sees PayPal or MCPal.

Recorded run, Thu, 12 Nov 2026 15:39:27 GMT (4 tool calls). Full transcript: docs/agentic-commerce-proof.md.

Official UCP conformance suite: 55 passed, 14 failed, 9 skipped (78 tests)

Run on 2026-11-12 against this site with the suite's own runner (conformance @ 1201fb7, ucp-sdk 0.4.6). Every one of the 14 failures is in a feature this demo merchant does not implement and lists below as unsupported: order webhooks to the platform (7), platform-written order updates via PUT /orders (4) and the shipping-simulation endpoint (3). Checkout lifecycle, idempotency, totals, discounts, validation, fulfillment structure and card credentials all pass. Raw output and fixtures: docs/ucp-official.

Spec-derived checks

UCP spec-derived checks (our implementation of the UCP conformance modules), not the official suite run. Checks re-implemented in test/ucp-conformance.test.ts from the source of github.com/Universal-Commerce-Protocol/conformance at commit 1201fb78e85217c5f2df060066ccbb0a1d1dce0b and the UCP schemas at commit 98607bc53f6f5e43ec15b9f96b82cba4912f0fe4. The official Python suite was not executed: running its code (and installing ucp-sdk 0.4.6) was blocked by this environment's permission policy. To run it yourself: clone the conformance repo, then SERVER_URL=https://mcpal.vercel.app uv run pytest with a conformance_input.json naming bag_house_blend_12oz / bag_panama_geisha_4oz and test_fixtures.json with AGENT10 (10%), BEANS20 (20%), FIVEOFF (5.00). local: 54/54 passed · production: 54/54 passed. Unsupported modules are listed as unsupported, not counted as passes. Details: docs/ucp-conformance.md.

Endpoints

Headers: UCP-Agent (required; a version newer than 2026-04-08 gets 422), Idempotency-Key (same key + same body replays the first answer; a different body gets 409), Request-Id. Payment handlers: mcpal_paypal_sandbox and the conformance suite's mock_payment_handler; the token fail_token simulates a decline.

curl -s https://mcpal.app/.well-known/ucp

curl -s -X POST https://mcpal.app/ucp/v1/checkout-sessions \
  -H 'UCP-Agent: profile="https://agent.example/profile"' \
  -H "Idempotency-Key: $(uuidgen)" -H 'content-type: application/json' \
  -d '{"line_items":[{"item":{"id":"bag_house_blend_12oz"},"quantity":2}],
       "discounts":{"codes":["AGENT10"]},
       "fulfillment":{"methods":[{"type":"shipping","destinations":[{"id":"d1",
         "street_address":"2211 N First St","address_locality":"San Jose",
         "address_region":"CA","postal_code":"95131","address_country":"US"}],
         "groups":[{"selected_option_id":"std-ground"}]}]}}'

# then, with the returned id:
curl -s -X POST https://mcpal.app/ucp/v1/checkout-sessions/<id>/complete \
  -H 'UCP-Agent: profile="https://agent.example/profile"' \
  -H "Idempotency-Key: $(uuidgen)" -H 'content-type: application/json' \
  -d '{"payment":{"instruments":[{"id":"i1","handler_id":"mcpal_paypal_sandbox",
       "type":"card","credential":{"type":"token","token":"sandbox-wallet-token"}}]}}'

The demo merchant

Shipping: Standard ground (5-7 business days) $5.99 (free from $50.00) · Express (2 business days) $14.99 · International express (5-10 business days) $29.99. Discount codes: AGENT10, BEANS20, FIVEOFF (AGENT10 is the one the profile advertises). Hosted-demo cap: $500.00 per checkout.

Terms: this is a demo merchant. Nothing ships.

Privacy: buyer names, emails and addresses sent to the demo are stored with the checkout session in private storage and used only to render it.

Not supported (yet)

• Order webhooks to the platform, request/response signatures (RFC 9421) and the conformance suite's simulate-shipping hook.
• Platform-written order updates (PUT /orders/{id}), stored customer address books, AP2 mandates, verified token binding.
• Real card or wallet credentials: every accepted instrument settles with PayPal's published test card. Card numbers are never forwarded.
• MCP and A2A transports for UCP; the REST binding only.
• ACP: delegated payment (the PSP vault-token flow), order webhooks to the agent platform and signed requests. The ACP endpoints share the UCP engine, so the same handler settles them.

Every merchant decision is in the decision log (source “merchant checkout (UCP)”).