Developers
A small, strict API for rewards
JSON over HTTPS, described in OpenAPI 3. Money is always whole minor units, points are six-decimal strings, and every call that changes something takes an idempotency key, so retries are always safe.
What you work with
REST API
Customers, wallets, order events, redemptions, checkout sessions and member sessions. Secret keys are scoped and only ever used from your server.
Server SDK
A TypeScript client for Node that sets idempotency keys, retries safely and verifies webhooks.
Checkout widget
A web component that quotes, holds and releases points in the browser. It can never confirm a redemption; only your server can.
Signed webhooks
Events for points earned, used and reversed, holds, tier changes and more, signed with HMAC-SHA256 and a timestamp, and retried for about a day and a half.
Sandbox programmes
Test with fake shoppers and orders on the same API. Shoppers see a “Test programme” label, so nobody mistakes test points for real ones.
A reference store
The Demo Store in the repository integrates only through the public API, SDK and widget, so you can read a working example end to end.
Integrate in three steps
Send paid and refunded orders
Your server · TypeScript import { RewardsClient } from '@123/reward-sdk'; const rewards = new RewardsClient({ apiKey: process.env.REWARDS_SECRET_KEY!, baseUrl: process.env.REWARDS_API_URL }); // Called when your payment provider says the order is paid. Duplicates are ignored. await rewards.orderEvents.send({ external_event_id: 'ORD-1042:paid', external_order_id: 'ORD-1042', event_type: 'ORDER_PAID', event_time: new Date().toISOString(), currency: 'GHS', eligible_amount: '500.00', external_customer_id: 'CUST-77', });Open a checkout session and show the widget
Your server, then your checkout page const session = await rewards.checkoutSessions.create({ external_customer_id: 'CUST-77', cart_reference: 'CART-9001', external_order_id: 'ORD-1043', currency: 'GHS', eligible_amount_minor: 64000, basket: [{ sku: 'WEEKENDER', quantity: 1, line_total_minor: 64000 }], }); <script type="module" src="{session.widget_script_url}"></script> <reward-checkout token="{session.checkout_token}" api-base="https://api.example" name="reward_reservation_id"></reward-checkout>Confirm after payment, and verify webhooks
Your server · TypeScript import { verifyWebhook } from '@123/reward-sdk'; // The widget put the hold's id in your checkout form. Confirm it only after payment succeeds. await rewards.redemptions.commit(form.reward_reservation_id, { external_order_id: 'ORD-1043' }); // Webhooks: check the X-123-Signature header against the raw body before trusting an event. const event = verifyWebhook({ rawBody, headers: request.headers, secrets: process.env.REWARDS_WEBHOOK_SECRET! });
Rules the API enforces for you
- Points from one merchant can be spent only at that merchant’s checkout.
- A held redemption is confirmed once, by your server, or released. The same request sent twice has the same result once.
- Live programmes accept redemptions only after Rendo approves the redemption policy.
- No endpoint asks for card or bank details. Payments stay with your payment provider.
Want a sandbox for your team?
Ask for a demo and we’ll set up a sandbox programme with API keys, test shoppers and webhooks.