Skip to content

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

  1. 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',
    });
  2. 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>
  3. 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.

Security model

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.