Verify Passport — what your customer sees

Quick reference

• The customer-facing verification surface lives at /verify (lookup entry) and /verify/[uid] (the passport card itself). Both routes are public — no login needed.
• The lookup accepts three identifier forms: the current UUID v4 public_uid (unenumerable, generated from issuance onwards), the legacy NXP-XXXXXX short form, and a numeric legacy identity number. All three resolve to the same passport card; the legacy forms are being sunsetted but still work for already-issued pieces.
• Customers arrive at the page from a QR sticker on the piece or its certificate, a printed certificate with the UID typed in the verification block, the aftercare email you sent at issuance, or a receipt link. Whichever entry point they use, the result is the same single passport card.
• The passport card renders: a Verified Authentic badge, the passport UID in a coloured chip, the piece title, issuance metadata (issued by, issued on), the primary image if one is attached, structured specifications (metal, stone, ring), provenance fields if you filled them in, current ownership state if recorded, and the event history timeline.
• The page never exposes private customer details — even if you set a current_owner_name on the passport, the page renders only the public fields you chose to surface; private records on your jeweller-side customer profile do not leak through.

What your customer walks through

1. How the customer receives the UID

When you issue a passport (see Issue a passport), the system mints a UID and ties it to the piece. The customer ends up with the UID through one of four channels:

• A QR sticker on the physical piece or its certificate. The QR encodes the/verify/[uid] deep-link. Scanning with any phone camera lands the customer directly on the passport card.
• The printed certificate. A passport certificate prints with the UID in a verification block — the customer (or a future buyer who receives the certificate at resale) can type the UID into /verify manually.
• The aftercare or post-issuance email. If you set up the aftercare automation, the email contains a direct link to the passport card.
• A receipt link. When the piece sold with a passport attached, the digital receipt references the passport URL alongside the line item.

The UID stays on the piece for life — when a piece changes hands at resale, the new owner uses the same UID and you can transfer ownership state on the passport (see Ownership transfer).

2. The lookup landing page

Customers arriving at /verify (rather than via a deep-link or QR) see a centred portal card with the Nexpura wordmark, a passport-verification headline, a short explainer card laying out what verification confirms and what it doesn't expose, an input for the passport identity number, and a Verify Passport button. The placeholder shows the modern identifier shape (NX-EN-04219 is the example) and the helper text explains where the customer can find the number — on the digital passport, QR certificate, receipt, or aftercare email.

On submit, the page navigates to /verify/[uid] where the passport card itself renders. Customers scanning a QR skip this step entirely — the QR deep-links straight into the card.

3. The passport card

The card at /verify/[uid] renders a dark hero strip with the Nexpura wordmark and the “Digital Jewellery Passport” eyebrow, followed by a stack of cards on a soft ivory background. What the customer sees, top to bottom:

• Verified Authentic badge. A green pill at the top of the first card — the at-a-glance confirmation that this is a real passport on Nexpura.
• Passport UID. Rendered in a mint chip beneath the badge — the exact identifier that was looked up, so the customer can confirm they're looking at the right piece.
• Title and jewellery type. The piece name and category, plus the optional description if you filled one in at issuance.
• Issued by. Your business name, sourced from the tenant profile. This is the trust attribution — “this passport was issued by this jeweller” — and the customer's anchor for who originated the record.
• Primary image. If you uploaded a primary image at issuance (or on a later edit), it renders below the issuance card.
• Specifications. A grid of structured fields grouped by metal, stone, and ring. Only the fields you filled in render — empty sections collapse cleanly. The labels are the same vocabulary as the jeweller-side issuance form (metal type / colour / purity / weight; stone type / shape / carat / colour / clarity / origin / certificate; ring size / setting).
• Provenance. Maker name, made-in country, year made — the historical attribution fields. Renders only if you filled in at least one.
• Ownership. Renders only if you set current ownership on the passport — the displayed owner name and the purchase date. This is the light-touch ownership-state surface; private customer records on your customer-of-record do not leak through.
• History timeline. Every event recorded against the passport — issuance, ownership transfers, lost / stolen / recovered reports, repair events, authentication events — in chronological order, each with a coloured indicator dot, the event label, the date in the issuing tenant's timezone, and any optional notes you attached at the time.
• Passport Issued footer. The original issuance date as the bottom-of-page anchor, plus a “Verified by Nexpura” trust ribbon.

4. Timezone-correct dates

Every date on the passport card — issuance, purchase date, event timestamps — renders in the issuing tenant's timezone, not the server's UTC. A Sydney jeweller's passport shows dates in Australian time regardless of where the customer opens it; a New York jeweller's shows Eastern. The customer reads the passport in the seller's frame of reference, which keeps the record consistent with the take-in slip and the certificate the customer was handed at issuance.

5. The not-found and rate-limited states

A UID that doesn't resolve — wrong format, a passport that was never issued, a passport that was marked private (is_public = false), a soft-deleted passport — surfaces the same branded not-found card: “Passport Not Found. This passport does not exist or is private. If you believe this is an error, please contact your jeweller.” The card stays on-brand rather than throwing a generic 404.

Rate-limited lookups (per-IP cap on the lookup endpoint to defend against the UID namespace being scraped) return the same not-found card — the customer never sees a rate-limit page directly. This is intentional: the not-found shape doubles as the rate-limit response so scraping doesn't learn anything from the response distinguishing “wrong UID” from “you've been throttled.”

Common questions

Troubleshooting