Going live
Merchant onboarding
What a merchant does to connect you, and what your settings screen needs to ask for.
The merchant's five steps
- In Perx: Settings → Integrations → Add connection. Choose your product, enter their store/location ID, save.
- Copy the generated webhook secret.
- In your product: paste the secret and confirm the store ID — per store.
- Ring a test sale with a Perx member’s phone number.
- Confirm in Perx: Loyalty → Transactions shows the sale within seconds.
This is the most common onboarding mistake. A merchant with three branches must create three connections, each with its own secret and store ID, or every sale will be attributed to one outlet and branch-scoped rewards will misfire.
What your settings screen should have
| Element | Why |
|---|---|
| Perx webhook secret | Masked password field. Must be editable without redoing setup, because merchants rotate secrets. |
| Store / location ID | Pre-fill from your own store record where you can — merchants mistype these. |
| Enable / disable toggle | Lets a merchant stop sending without deleting their configuration. |
| Test connection button | Sends a signed sale.voided no-op and shows the result. Catches clock skew and copy-paste errors before go-live, not after. |
| Last delivery status + last error | Turns "is it working?" into something the merchant can answer themselves. |
The Test connection button
Build this. It is a small amount of work and it removes most of your first-week support load. Send a sale.voided event — Perx accepts and ignores it, so it is a genuine no-op that still exercises the full path: DNS, TLS, headers, signature, connection lookup.
Map the result to plain language rather than showing the raw status:
| Result | What to show the merchant |
|---|---|
200 | Connected. Sales from this store will now earn Perx points. |
401 | Perx rejected the credentials. Check the secret and store ID were copied correctly. |
Network error | Could not reach Perx. Check outbound internet access from this machine. |
When a connection breaks
A 401 on a previously working connection means the merchant rotated or removed the secret. Surface it as an actionable notice — “Perx connection needs attention” with a link to your settings screen — and stop retrying those events. Only the merchant can fix it, and a queue silently filling up helps nobody.