Try it: live desk at https://postmark-preflight.fly.dev (choose Open the judge desk, no password), second deployment on Render at https://postmark-auv9.onrender.com, code at https://github.com/aarav1656/postmark.

The case

Small sellers lose PayPal disputes while holding proof, because the proof is not in PayPal's shape. "i lost the Paypal chargeback after having all the proofs" (r/paypal). "PayPal refunded buyer $1,700, let him keep everything, charged me a dispute fee" (r/paypal, 425 comments). "Buyer filed chargeback on PayPal $8200 USD" (r/PokemonInvesting, 510 comments).

PayPal's Seller Protection page spells out what proof of delivery means: "An online and verifiable tracking number" and "An address for the recipient that matches the shipping address on the Transaction Details page". A wrong unit number on a label is enough to lose. Postmark builds the case file for one parcel at the only moment it can still be fixed: the post office counter.

The counter, before the parcel leaves

A seller lists an item with a photo, title, price and description. Each listing gets a public item page with a Buy with PayPal button. Postmark creates the PayPal order server-side from the listing price with the item attached, and captures it on return only when the order's custom_id belongs to that listing. A seller can also add an existing PayPal order by id.

The paid order lands on the desk as the next parcel to check, with its item photo, buyer and delivery address. A summary strip shows the amount at risk: every order still unshipped or carrying a label that breaks Seller Protection.

Seller desk: next parcel to check and amount at risk The seller desk: the next parcel to check leads, with the amount at risk totalled above it.

Exhibit A: the address PayPal holds

Postmark stores the order, capture id, amount, buyer, item and the exact shipping address PayPal holds on the order. That address is the reference every label is judged against, because it is the one PayPal compares in a dispute.

The buyer path runs the same way a real customer meets it. The Kodak Duaflex II listing (photo CC0, Wikimedia Commons) was bought through its public item page with a sandbox card. PayPal reads order 1NY33979BE5961643 back as COMPLETED with capture 1ND42730D9394441J COMPLETED for 68.00, shipping to Jordan Ellis in San Francisco, and the order arrives on the desk as the next parcel to check.

Public item page with Buy with PayPal A public item page: the buyer pays with PayPal and the order carries the listing with it.

Exhibit B: the label photo

A phone-first ship screen opens the camera. Gemini vision through OpenRouter (google/gemini-2.5-flash, temperature 0) reads carrier, service, tracking number, recipient, every address line, signature marking, confidence and field boxes into a Zod-validated schema, and highlights each field on the photo. The photo and the extraction stay with the order as evidence.

For judges without a parcel in hand, any sandbox order prints a test label to its own PayPal address, plus a second copy with the wrong unit number. Both run through the same vision call a real photo takes.

Exhibit C: tracking, read back from PayPal

Tracking numbers are checked against USPS, UPS, FedEx and DHL formats. On PROTECTED, or an explicit recorded "ship anyway", Postmark posts the tracker to the PayPal order, reads the order back and shows the tracker id once PayPal returns it.

On https://postmark-preflight.fly.dev against PayPal sandbox: order 6WL217372G5125037 reads back COMPLETED with capture 2BF87082EJ6705914 COMPLETED for 60.00. Posting tracking produces tracker 2BF87082EJ6705914-94003946480000000000, read back from the PayPal order as SHIPPED.

The same holds for a signed-in PayPal wallet buyer: order 67M81832LE5500531 reads back COMPLETED with capture 5MS21058TU4642358 COMPLETED for 68.00, and Send tracking to PayPal produces tracker 5MS21058TU4642358-94003825030000000000, read back as SHIPPED.

The verdict: AT RISK or PROTECTED

The verdict is never the model's call. Both addresses are normalized (US postal suffixes, directionals, unit designators, state names, punctuation, ZIP+4) and compared field by field in deterministic, unit-tested code. "Apartment 4B", "Apt 4B" and "Unit 4B" match; "4B" and "999" do not.

The result lands like a rubber stamp: PROTECTED, or AT RISK with a redline showing the label line against the PayPal line and the policy sentence it breaks. On the live run, the wrong-unit label stamps AT RISK (unit 4B against 999) and the matching label stamps PROTECTED.

Label stamped PROTECTED, tracking read back from PayPal The verdict: label stamped PROTECTED, with tracking read back from the PayPal order.

The tracking validator is proven able to fail: we broke it to accept every value, three negative cases went red, and restoring it turned them green.

When the buyer says it never arrived

A reconciler lists PayPal disputes and matches each one to a stored order through the dispute's seller transaction id. For a match, Postmark assembles the evidence packet: the label photo, the tracking number, the address match and the tracker timestamp. It drafts seller notes grounded only in that stored evidence; the prompt receives the packet and the output schema leaves no room for facts outside it. The seller reviews, and Postmark submits the packet to PayPal with the label photo attached. The photo taken at the counter is the photo Postmark sends with its dispute answer.

Test and stale orders leave the desk and its totals with one click, and restore the same way. PayPal keeps the order.

Why now

PayPal's upcoming policy update adds "PayPal Checkout - Agentic Virtual Card" orders to the list of transactions ineligible for Seller Protection (https://www.paypal.com/us/legalhub/paypal/upcoming-policies-full). As more checkout paths fall outside that cover, the proof a seller controls carries more weight: a shipping address that matches the PayPal order and a tracking number PayPal can verify. Postmark checks both at the counter, before the parcel leaves.

Built on

PayPal's APIMatic-generated Server SDK. Orders v2 create, capture and get run through @paypal/paypal-server-sdk 2.5.0 (src/paypal-orders.ts), with typed requests and responses on the money path.

PayPal APIs:

Call Purpose
POST /v1/oauth2/token Client credentials token
POST /v2/checkout/orders Checkout from a listing: server-set price, item line, listing custom_id
POST /v2/checkout/orders/{id}/capture Capture on return, after checking custom_id matches the listing
GET /v2/checkout/orders/{id} Import an order, read back capture and trackers
POST /v2/checkout/orders/{id}/track Post the verified tracking number
GET /v1/customer/disputes, GET /v1/customer/disputes/{id} Reconcile and read disputes
POST /v1/customer/disputes/{id}/provide-evidence Multipart submission with the stored label photo
POST /v1/notifications/verify-webhook-signature Verify incoming dispute webhooks

Every mutation runs through a persisted operation record with its own PayPal-Request-Id, so a retry after a timeout never double-captures or double-posts.

Rules, not the AI. Gemini vision via OpenRouter reads the label; deterministic code decides the verdict.

Hosting. Fly.io with a persistent volume for label and listing photos, and a second live deployment on Render.

Stack. TypeScript on Node 24, Hono, SQLite, sharp for listing photos, label thumbnails and label rendering, React 19, Vite, Vitest, Zod. The amount at risk and the archive filter live in one tested function (src/domain/board.ts); listing upload, the public item read and archive/restore are exercised through the real server, SQLite and sharp in test/listings.test.ts.

Try it as a judge

Open https://postmark-preflight.fly.dev and choose Open the judge desk. No password. Print the test label for an order, then its wrong-unit copy, and watch one stamp PROTECTED and the other AT RISK. Or buy the demo item with PayPal from its public item page and watch the order arrive on the desk.

Built With

Share this project:

Updates

Submission history