Developer API

Connect your POS to
Yokaa memberships.

Each business creates its own API key. Your POS or booking system uses it to look up members and outlets, and to send a signed event when an order is paid, so the customer earns points automatically.

One key per business · Signed, replay-safe webhooks · Amounts in the business's own currency

From the counter to the customer's points.

01 Look up a member02 List outlets03 Send a purchase
1 · Authentication

Use the business's API key on your server.

The business owner or an admin creates a key under Settings → Business and outlets → API keys. The key is shown once. Send it as a bearer token over HTTPS, and keep it on your server: never put it in a browser, an app or POS client code. The business can revoke it at any time.

headers
Authorization: Bearer yok_<business-secret>
Content-Type: application/json
2 · Members

Look up a member by email.

Search only after the customer has given you their email at the counter. The result is either one exact match or {"member":null}; never guess a member from a similar address.

GET /api/v1/members
GET /api/v1/members?email=[email protected]

{ "member": { "id": "…", "name": "…", "email": "…", "phone": "+6581234567", "points": 42 } }
3 · Outlets

List the business's outlets.

The response also tells you the business's country and currency. Send every amount in that currency, using its normal decimal places: two for SGD, none for JPY.

GET /api/v1/stores
GET /api/v1/stores

{ "country": "SG", "currency": "SGD", "stores": [ { "id": "…", "name": "Tiong Bahru" } ] }
4 · Purchases

Send a signed event when an order is paid.

Use your POS's stable order ID as externalId. Sending the same ID again never awards points twice. The member and outlet must belong to the key's business, and the amount must be positive. Refunds are handled by the business in Yokaa for now.

Sign the timestamp, a full stop and the exact request body with HMAC-SHA256, using the API key as the secret. Timestamps older than five minutes are rejected.

send-purchase.js
import { createHmac } from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({ externalId: "ORDER-123", memberId, storeId, amount: 28.5 });
const signature = "sha256=" + createHmac("sha256", apiKey).update(`${timestamp}.${body}`).digest("hex");

await fetch(`${baseUrl}/api/v1/webhooks/transactions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json",
    "X-Yokaa-Timestamp": timestamp, "X-Yokaa-Signature": signature },
  body,
});
// 201 the first time; 200 with "duplicate": true for a repeated externalId.
5 · Errors

Errors and testing

StatusMeaning
400A field is missing or the amount isn't valid for the currency.
401The key, signature or timestamp isn't valid.
404The endpoint doesn't exist.
409The order conflicts with one already recorded.

To test, create a test member and outlet in the business's workspace, read their IDs from the API, then send a small order and check the points on the member's profile. Error messages come back in the language set by the X-Yokaa-Lang header: en, zh-Hans or zh-Hant.

YOKAA FOR DEVELOPERS

Build once.
Reach every business.

Join the developer preview ↗