Partner documentation
Connect your POS to Perx loyalty
You send us sales. We run the loyalty — points, stamp cards, rewards, and the merchant's own rules. Most integrations are one webhook.
Perx is a loyalty platform used by merchants across the Maldives. Once your product is connected, every completed sale at a Perx merchant automatically earns that customer points and advances their stamp cards, using rules the merchant configures in their own dashboard. You implement no loyalty logic of your own.
There are two ways in. On the Generic tier you send Perx’s canonical payload to a shared endpoint and no Perx engineering is required — you can be live in days. On the Featured tier Perx writes a native adapter for the payload your product already emits, so your product needs no Perx-specific sending code at all. Compare the tiers →
Quickstart→
Send your first signed sale to UAT and watch it earn points. Twenty minutes.
Integration tiers→
Generic or Featured — who builds the payload mapping, and what each tier gets you.
Authentication→
HMAC request signing, the four headers, and the 300-second replay window.
API reference→
Every endpoint, field and error, generated from the OpenAPI spec.
Signature playground→
Paste a secret and a body, get the exact signature Perx expects. Runs in your browser.
Certification→
The checklist you have to pass before your vendor slug is enabled in production.
What you can build
The integration has three layers. Each one is independently useful, so ship them in order rather than waiting to build everything.
- Earn — post each completed sale. This is one endpoint, it needs no changes to your checkout screen, and it is the whole integration for most vendors.
- Redeem — let the cashier look up a customer’s rewards and apply one as a discount at the till. Interactive, so it does touch your checkout UI.
- Catalog — push your item list so merchants can build “buy 5 coffees, get one free” against a real menu instead of typing item names.
Redemption, refunds and catalog sync are implemented and in review, but not yet enabled in production. Their request and response shapes are final — build against them now and your Perx contact will confirm the enablement date. Earn is available today.
Before you start
You will need three things from Perx, and one thing from each merchant.
- A vendor slug — your permanent lowercase identifier, e.g.
acmepos. - A UAT merchant and store to develop against.
- A named technical contact for the build.
- From each merchant, at connection time: a webhook secret they generate in their Perx dashboard and paste into your product, per store.
You never hold credentials for a merchant’s Perx account. Ready? Start with the quickstart →