How it uses PayPal
Each line is real code, in the file named. A test fails if the code leaves that file. PayPal sandbox, no real charge. Everything that keeps families safe stays free.
- The shelf has PayPal's v6 button wired to order and capture routes; a person paid through it in the sandbox on Nov 8, 2026app/queue/paypalSdk.ts
- Creates the optional shop plan's sandbox productserver/paypal/subscriptions.ts
- Creates a sandbox billing plan at the price in SHOP_PLANserver/paypal/subscriptions.ts
- Creates a shop subscription with an HMAC custom_idserver/paypal/subscriptions.ts
- Reads subscription status from PayPal on return and on verified billing eventsserver/paypal/subscriptions.ts
- Cancels a subscription when the shop owner asksserver/paypal/subscriptions.ts
- Names BILLING.SUBSCRIPTION.ACTIVATED as an event that triggers a fresh PayPal readserver/shop/subscription.ts
- Names BILLING.SUBSCRIPTION.CANCELLED as an event that triggers a fresh PayPal readserver/shop/subscription.ts
- Names BILLING.SUBSCRIPTION.SUSPENDED as an event that triggers a fresh PayPal readserver/shop/subscription.ts
- Names BILLING.SUBSCRIPTION.EXPIRED as an event that triggers a fresh PayPal readserver/shop/subscription.ts
- Routes billing events to the subscription read only after the webhook signature checkserver/paypal/webhookHandler.ts
- Reads the shop's sales from Transaction Search, across windows, and reports any window that failedserver/paypal/transactions.ts
- Reads the capture from PayPal again before any refund, and again to reconcileserver/paypal/refunds.ts
- Reads PayPal's Disputes API before each refundserver/paypal/disputes.ts
- Sends the demo shop's refunds through PayPal Agent Toolkit, server sideserver/paypal/toolkitRefund.ts
- Sends one request id per refund, so a retry gets the same refund backserver/paypal/client.ts
- Reads the refund back from PayPal to reconcile itserver/paypal/refunds.ts
- For the demo shop, that read goes through PayPal's Server SDK, with a real time limit and one layer of retriesserver/paypal/sdkRefundRead.ts
- Verifies each webhook's signature and certificate before believing itserver/paypal/webhooks.ts
- Puts a sale in the queue when a verified capture webhook arrivesserver/demo/liveCatch.ts
- A buyer can log in and pay on PayPal's own page, and the order is read back from PayPal and must match before it is capturedserver/demo/liveCatch.ts
- Is built to follow the 48-hour deletion rule, and purges hourly at 46 hoursserver/privacy/retention.ts
- The lasting ledger holds a PayPal id only as a keyed hash (HMAC). Raw ids sit only in tables purged at 46 hoursserver/privacy/recordKey.ts
- Sandbox only: webhook certificates are accepted from PayPal's sandbox hosts, and the API base is the sandboxserver/paypal/client.ts
Where you see each call
On a demo shop, the queue and each refund page also list what the app just asked PayPal, under What this app asked PayPal.
| Call | Where you see it |
|---|---|
| GET /v1/reporting/transactions | The queue's line that says what was searched, when a demo shop starts |
| POST /v2/checkout/orders | Buy this as a family, Buy with a PayPal sandbox login, and the shopping agent's Approve on PayPal |
| GET /v2/payments/captures/:id | Review refund, on a sale after the recall |
| GET /v1/customer/disputes | Review refund, which won't go on while the buyer has a dispute open |
| POST /v2/payments/captures/:id/refund | The refund button, through PayPal Agent Toolkit for the demo shop |
| GET /v2/payments/refunds/:id | Check it against PayPal, through PayPal's Server SDK for the demo shop |
| Webhook: PAYMENT.CAPTURE.COMPLETED | A new card in the queue, with nothing pressed |
What PayPal's data does not do
Nothing PayPal returns goes to Claude or Channel3. Claude reads CPSC's public text and the shop's own item titles. Sales join to those items here, by order number, SKU or exact title. Tests plant PayPal values in the database and check they are in no request Claude would receive from the recall check, the record check, the question writer, the follow-up adviser or Studio. The shopping agent reads what the person typed, public listing titles and brands, with common price formats taken out of titles, and what its recall check found, and no PayPal table. One more test plants them and finds none in the market searches the recall sweep sends to Channel3. Each test reads what would be sent, with the service it checks replaced by a stand-in. All but Studio's run in CI; Studio's is a local Playwright test.
What a person decides
A person approves every refund, and every notice unless they turn on preparing them for one recall. Either way they send each notice from their own mail. The agent has no refund tool, and the mail is opened in the shop's own account. See the safety checks.