Yapo for developers
Connect your loyalty card with the rest of your business. The API is read-only: no outside system can add stamps or change data. Real-time notices arrive through signed webhooks.
Authentication
The business owner creates a token in their dashboard, under Integrations, and chooses what it can read: customers, cards, activity, programs, locations or feedback. The token is shown only once; keep it like a password.
Send it on every request in the `Authorization: Bearer yapo_ext_…` header. A revoked token stops working immediately.
Endpoints
All are GET and return JSON. Lists are paginated with an opaque cursor: request the next page with `?cursor=` and the `nextCursor` value; when it is null, you are done. `limit` accepts up to 100. Lists show what was recorded up to one minute ago, so an incremental sync never skips an entry that was committed late.
- /v1/ext/customers and /v1/ext/customers/{id}: name, email, phone, segment, tier, promotions consent and sign-up form answers (scope: customers).
- /v1/ext/cards?customerId=: balance, tier and pass state (scope: cards).
- /v1/ext/ledger?since=&cardId=: activity in recording order, ideal for syncing (scope: activity).
- /v1/ext/programs: programs and their current rules (scope: programs).
- /v1/ext/locations: locations (scope: locations).
- /v1/ext/feedback: NPS feedback (scope: feedback).
curl https://yapowallet.com/v1/ext/customers?limit=50 \
-H "Authorization: Bearer yapo_ext_…"
# Siguiente página: ?cursor=<nextCursor>
# Movimientos nuevos desde una fecha: /v1/ext/ledger?since=2026-10-01T00:00:00ZLimits and errors
Up to 120 requests per minute are allowed from each IP; above that you get 429. Errors follow problem+json with a readable `code`: `missing_scope`, `invalid_token`, `invalid_cursor` or `not_found`.
Webhooks
Under Integrations, add your system’s https URL and choose the events. We send a JSON POST for each event, almost instantly. If your system does not answer 2xx within 10 seconds, we retry with growing delays for 24 hours. Events are kept for 7 days. If a destination fails for 3 days in a row, we disable it and email the owner.
Events: customer.created, card.installed, card.removed, stamp.added, points.added, reward.unlocked, reward.redeemed, tier.changed, feedback.received, ledger.reversed (a reversal or refund) and balance.expired. The “Send test” button sends a ping event.
Use the event `id` to drop duplicates: a retry may arrive twice.
{
"id": "0192f0c4-…",
"type": "stamp.added",
"createdAt": "2026-10-21T15:04:05.123Z",
"businessId": "0192e1aa-…",
"data": { "cardId": "…", "customerId": "…", "stamps": 1, "reason": "accrual", "locationId": "…", "occurredAt": "…" }
}Verifying the signature
Every notice carries a `Yapo-Signature: t=<unix seconds>,v1=<hex>` header. v1 is HMAC-SHA256 with your signing secret over the text `<t>.<body>`. Verify against the EXACT body you received (before parsing it) and reject notices older than 5 minutes.
import { createHmac, timingSafeEqual } from 'node:crypto';
// header = req.headers['yapo-signature'] → "t=1767225600,v1=5f3c…"
export function verifyYapo(header, rawBody, secret, toleranceSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
if (!m) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest();
const given = Buffer.from(m[2], 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
}Personal data
The API returns personal data of the business’s customers. Use it only for what the business asked you to do, store it securely and delete what you no longer need. The owner can revoke the token at any time.
Do you have a POS?
We are building direct connectors with Contífico, Loyverse, Odoo, Square and Shopify. Write to us if you want to try them first.
Create my free card