One call tells you whether an agent purchase would reach you, and what to fix if
it wouldn’t.
Or press Test your integration on the Website integration page of your
console. Both run exactly the same checks.
What you get back
ok is false if any check fails. A warn never fails the run.
The checks
psp_linked checks more than “is it linked”
A provider link can exist while its stored credential is unreadable — rotated,
revoked, or written under an identity we can’t read. That stays invisible until
your first real charge fails. This check resolves the credential, so you find out
now. It never reads the secret’s value.
webhook_delivers sends a real delivery
Not a simulation. It signs a webhook.test event and puts it through the normal
pipeline, and your endpoint must return 2xx.
This is the check that replaces clicking through the buyer page in a frame: it
exercises your signature verification and raw-body handling headlessly.
It delivers to every active endpoint, not just one — so an endpoint that
silently rejects deliveries can’t hide behind a healthy one. Each run therefore
sends a webhook.test to all of them, production included. Don’t wire this into
something that runs frequently.
Pre-launch shops are not broken shops
The day before your first drop, nothing is on sale — and that is exactly when
people run this for the first time. catalog_sellable warns in that case
rather than failing, and says “this is normal before a drop”, so ok stays
true. An agent will queue a watch and buy when sales open.
It only fails if the shop has no tiers at all, which really does mean there is
nothing to sell.
stock_present is a warning worth reading
A queued agent watch only fires when we see availableCount ≥ the quantity it
wants. If your stock update never reached us, we still see 0, and the watch
silently never fires at the drop.
This warns when a tier is on sale and we see zero. It stays quiet for tiers
whose sale hasn’t opened yet — those are legitimately zero.
It never buys anything
That’s a guarantee, not a limitation:
- our event log is append-only and is the billing source of truth, so a test
purchase would bill you for a test, permanently;
- it would move your own sales totals, success rate and purchase-attempt counts —
the numbers you’re checking;
- a hold decrements real stock, so a test could make a real ticket unsellable.
A run writes no event, no purchase attempt, no payment intent, and no hold.
So a green run does not prove a charge will authorize. It proves the wiring a
charge depends on is in place. The scope field in the response says so.
What it does NOT check
Worth knowing so a green run isn’t read as broader than it is. Each of these
comes from a real integration that hit it:
- That your
tierId mapping is current. We can’t see your side. If your
mapping table is stale, a purchase can fulfil the wrong tier — resolve
fulfilment on tierId and quantity from the payment row, never by matching
the amount to a price.
- That
buyerRef resolves to a real buyer on your side. If that mapping is
missing, tickets can silently land on a fallback account.
- That your embed origin is registered for the framed modal. Without it the
authorize page redirects instead of framing.
When to run it
- After first setup, before you expect an agent purchase.
- After rotating a webhook secret or a provider key.
- After changing your webhook URL or its middleware.
- When a buyer says an agent didn’t buy — together with
the watch lookup.
