Getting started
Integration tiers
Two ways to connect. The difference is who writes the payload mapping — you, or us.
| Generic | Featured | |
|---|---|---|
| Who maps the payload | You | Perx |
| What you send | Perx’s canonical payload | Your own native payload, unchanged |
| Endpoint | POST /webhooks/generic | POST /webhooks/{your-slug} |
| Perx engineering | None — no code ships for you | A native adapter, per provider |
| Time to live | Days, self-serve once approved | Scheduled onto the Perx roadmap |
| Listed in the merchant directory | No — merchants add you as a generic connection | Yes, with logo and one-click connect |
| Guided setup UI | No | Yes — location picker, credential validation |
| Catalog sync | Optional, you push | Yes, Perx pulls from your API |
| Redemption at till | Supported | Supported |
| Cost | Free | Commercial agreement |
Generic — you conform to us
You build one webhook sender that emits the canonical Perx payload and signs it. Perx ships no code for you: your integration works the moment a merchant creates a connection and pastes their secret into your settings screen.
This is the right choice if you have a handful of shared merchants, want to ship now, or your payload maps cleanly. It is also the right place to start even if you expect to end up Featured — connections migrate without merchants re-onboarding.
Featured — we conform to you
Perx writes a native adapter that reads your existing webhook payload as-is, so your product needs no Perx-specific sending code at all. The merchant just points your existing webhook config at a Perx URL. In exchange you get:
- A dedicated endpoint and your own identity in Perx reporting.
- A listing in the Perx merchant dashboard’s Integrations directory, with a guided setup flow — including a store picker that calls your API, so merchants never type a raw location ID.
- Catalog sync: Perx pulls your item catalog on a schedule, so merchants build item-level stamp rules against a real menu.
- Joint go-to-market — your integration is discoverable to every Perx merchant.
What Perx needs from you
- Public webhook documentation, or a written spec of the order-completion payload (and ideally refunds).
- At least three real, redacted sample payloads: one with a customer, one without, and one refund.
- Your webhook authentication scheme — static header, HMAC signature or mTLS are all supported. Tell us which, and how the secret is provisioned.
- Sandbox access, plus catalog and location API docs if you want catalog sync and the store picker.
- A named technical contact for the build and for breaking-change notice.
Getting promoted
A Generic vendor is promoted on evidence of demand — typically three or more shared merchants live, or a signed partner agreement. Talk to us before building if you expect volume.
Promotion does not restart onboarding. Existing merchant connections keep working; the switch is a flag on the Perx side plus an endpoint change on yours.