API Reference

The RibiRewards Reward API uses the existing RewardsCard Partner API, a REST API served over HTTPS. All request and response bodies are JSON. It is designed for server-to-server integration — your backend calls the API, and your frontend never needs to know about it.

Get your first card issued in under 5 minutes.

1. 1

   Get an API key

   Submit a key request or email tech@ribirewards.com. Keys are provisioned manually and are active within one business day.

2. 2

   Check available categories

   Call GET /v1/categories?country=NG with your key. You will receive just the category list for that country — no product dump.

3. 3

   Create a campaign

   Call POST /v1/campaigns with a name, the country, an amount, and — if you want to scope it — the categoryIds from the previous step. Save the id this returns — this is your campaignId.

4. 4

   Submit recipients

   Call POST /v1/campaigns/:campaignId/recipients with a name + email for each person, and an Idempotency-Key. Every recipient is emailed their code directly — there is no separate delivery step.

5. 5

   That's it

   Each recipient opens shop.rewardscardafrica.com, enters their code, and shops within whatever categories the campaign was scoped to. Check GET /v1/campaigns/:campaignId/redemptions to see who's actually redeemed.

Every request (except POST /v1/request-api-key) requires your API key as a request header:

X-API-Key: your_api_key_here

How authentication works

On every authenticated request, the API verifies your key against the partner registry. The key must exist and have status ACTIVE. A BLOCKED key is treated the same as an invalid key — you receive a 422 either way.

• Keys are long-lived — there is no expiry mechanism. Rotate your key by contacting tech@ribirewards.com if you believe it has been compromised.
• Your API key is redacted from server logs at the network layer — it is never written to log storage, even at debug level.
• Store your key in an environment variable or secrets manager. Do not hard-code it, commit it to a repository, or pass it through a browser.
• If you need to call this API from a browser context, contact us to add your origin to the CORS allowlist. See the CORS & Security section.

Key status reference

POST /v1/campaigns/:campaignId/recipients requires an Idempotency-Key header on every call. Omitting it returns a 400 immediately, before any issuance is attempted.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Why this matters

Network timeouts are normal. Without idempotency, a timeout leaves you not knowing whether a card was issued — and a naive retry would issue a second one. With idempotency, you always retry with the same key, and the API returns the original result regardless of whether the first attempt succeeded.

• The Idempotency-Key header is required on every POST /v1/campaigns/:campaignId/recipients call. A 400 is returned if it is missing.
• Keys are scoped per partner account. The same key value sent by two different partners does not conflict.
• Keys expire after 24 hours. After expiry, the same key value can be reused — it will be treated as a new request.
• Only successful and client-error responses are cached (status < 500). A 500 or 504 is never cached — you can safely retry.
• The cached response is returned as-is, including the original status code. A cached 200 returns 200, not 201.
• Backed by Redis when configured, so this is safe across multiple instances — falls back to an in-memory store only in environments without Redis provisioned (e.g. local development).

Recommended approach

// Generate one key per issuance attempt.
// Tie it to your own order ID so you can reconstruct it on retry.
import { randomUUID } from "crypto";

const idempotencyKey = randomUUID();

// Store idempotencyKey alongside your order before calling the API.
// If the call times out, retrieve your stored key and retry with it.

The API uses two-tier rate limiting on authenticated routes. All rate limit headers follow the standard RateLimit-* format and are present on every response.

Daily spend cap

In addition to request-rate limits, every partner account has a daily ceiling on total redemption value per currency. This is separate from the request rate — you can be well within the rate limit and still hit the spend cap if you issue enough high-value cards in one day.

• The cap is per-currency and per-partner — spending in NGN does not count against your ZAR cap.
• The cap resets automatically at midnight UTC.
• When the cap is hit, POST /v1/campaigns/:campaignId/recipients returns 429 with a message identifying the spend cap (not the request rate) as the reason — checked as one total for the whole submission before anything is sent.
• Spend is only counted on confirmed successful issuance — a failed or timed-out attempt never counts against the cap.
• Contact tech@ribirewards.com to raise your cap.

Handling 429 responses

• Read the Retry-After response header — it contains the number of seconds to wait before retrying.
• Always implement back-off. Do not poll without a delay.
• Check the message field to distinguish a rate-limit 429 from a spend-cap 429 — the messages are different.

CORS

• Server-to-server calls (no Origin header) are never blocked by CORS — this is correct browser behaviour and is intentional.
• Browser-originated cross-site calls are checked against an allowlist. By default the allowlist is empty — this API is designed for server-to-server use.
• If you need to call this API from a browser context (e.g. your own dashboard), contact tech@ribirewards.com to have your origin added to the allowlist.

Security headers

• HTTPS is enforced. The HSTS header (max-age=31536000; includeSubDomains; preload) is set on every response.
• The X-Powered-By header is not present — framework fingerprinting is disabled.
• Request bodies are capped at 100kb. Requests exceeding this limit are rejected before reaching validation.
• Every request has a 15-second server-side timeout. If a downstream call hangs, the server closes the connection and returns 504 rather than leaving it open indefinitely.
• Auth headers (X-API-Key, Authorization) and cookies are redacted from server logs. Request and response bodies are never logged.

Returns the full product catalogue for one supported country, grouped by category. Only products with status ACTIVE and in-stock are included. Categories with no qualifying products are excluded from the response entirely.

Query parameters

Markup

If your account has a catalogue markup percentage configured, it is applied server-side before the response is built. The amount field on every product already reflects the marked-up price — you do not need to apply markup yourself, and you never see our base cost.

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/reward-card-catalogue?country=NG" \
  -H "X-API-Key: your_api_key_here"

const response = await fetch(
  "https://api.rewardscardafrica.com/v1/reward-card-catalogue?country=NG",
  { headers: { "X-API-Key": "your_api_key_here" } }
);
const { country, currency, categories } = await response.json();

import requests

resp = requests.get(
    "https://api.rewardscardafrica.com/v1/reward-card-catalogue",
    params={"country": "NG"},
    headers={"X-API-Key": "your_api_key_here"},
)
resp.raise_for_status()
data = resp.json()

Example response

{
  "country": "Nigeria",
  "countryCode": "NG",
  "currency": "NGN",
  "categories": [
    {
      "id": "cat_a1b2c3d4-e5f6-...",
      "title": "Airtime & Mobile Data",
      "image": "https://cdn.example.com/categories/airtime.jpg",
      "products": [
        {
          "id": "prod_550e8400-e29b-...",
          "title": "MTN Nigeria ₦500 Airtime",
          "description": "Instant airtime top-up for any MTN Nigeria number.",
          "amount": "500.00",
          "currency": "NGN",
          "deliveryDays": "Delivered within a few hours",
          "image": "https://cdn.example.com/products/mtn-500.jpg",
          "brand": {
            "id": "brand_9c821f3a-...",
            "title": "MTN Nigeria",
            "image": "https://cdn.example.com/brands/mtn.png"
          }
        }
      ]
    }
  ]
}

Response fields — top level

Response fields — category object

Response fields — product object

Notes

• Product IDs (id) are stable UUIDs. Safe to store as a reference to a specific product.
• amount is always a string, not a number. Parse with parseFloat() or your language's decimal equivalent before any arithmetic.
• deliveryDays is a full display string — do not append 'days' or modify it. Render it exactly as returned.
• image URLs may be null at any level. Always null-check before rendering — do not assume an image exists.
• The catalogue can change between calls (new products added, products going out of stock). Do not cache it indefinitely — refresh at least once per session or before showing it to a customer.
• Country coverage expands periodically without notice. Re-confirm supported countries against GET /v1/reward-card-catalogue rather than hardcoding the list.
• Every product returned here is voucher-fulfilled unless RibiRewards has separately agreed a physical/shop-and-ship arrangement with you. There is no field on the product object to filter or detect merchandise/physical products — that distinction isn't API-addressable today. If your integration needs to offer physical goods, contact tech@ribirewards.com to scope that separately; the recipient selects the product and delivery address on RibiRewards' own redemption page in that case, not inside your platform.

Returns just the categories available in a country — id, title, image. Deliberately not the full catalogue: no nested products. Use this to build a category picker when creating a campaign, not GET /v1/reward-card-catalogue, which returns every product nested under every category.

Query parameters

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/categories?country=NG" \
  -H "X-API-Key: your_api_key_here"

const resp = await fetch(
  "https://api.rewardscardafrica.com/v1/categories?country=NG",
  { headers: { "X-API-Key": "your_api_key_here" } }
);
const { categories } = await resp.json();

import requests

resp = requests.get(
    "https://api.rewardscardafrica.com/v1/categories",
    params={"country": "NG"},
    headers={"X-API-Key": "your_api_key_here"},
)
resp.raise_for_status()
categories = resp.json()["categories"]

Example response

{
  "country": "Nigeria",
  "countryCode": "NG",
  "categories": [
    { "id": "9f1c2e3a-1234-4a5b-8c9d-abcdef123456", "title": "Dining", "image": "https://cdn.rewardscardafrica.com/categories/dining.jpg" },
    { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "title": "Beauty", "image": "https://cdn.rewardscardafrica.com/categories/beauty.jpg" }
  ]
}

Response fields

Creates a campaign — a name, a country, a category scope, and one amount that applies to every code issued under it. This replaces choosing a specific product per recipient: pick categories once here, then submit as many recipients as you like against the campaignId this returns. The partner attached to the campaign is always your own authenticated account — never a field you set yourself.

Request body

Example request

curl -X POST "https://api.rewardscardafrica.com/v1/campaigns" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "August staff rewards",
    "country": "NG",
    "amount": 500,
    "categoryIds": ["9f1c2e3a-1234-4a5b-8c9d-abcdef123456"]
  }'

const response = await fetch(
  "https://api.rewardscardafrica.com/v1/campaigns",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "August staff rewards",
      country: "NG",
      amount: 500,
      categoryIds: ["9f1c2e3a-1234-4a5b-8c9d-abcdef123456"], // optional — omit for the full catalogue
    }),
  }
);

const { data } = await response.json();
const campaignId = data.id;

import requests

resp = requests.post(
    "https://api.rewardscardafrica.com/v1/campaigns",
    headers={
        "X-API-Key": "your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "name": "August staff rewards",
        "country": "NG",
        "amount": 500,
        "categoryIds": ["9f1c2e3a-1234-4a5b-8c9d-abcdef123456"],  # optional
    },
)
resp.raise_for_status()
campaign_id = resp.json()["data"]["id"]

Example response

{
  "message": "Campaign created.",
  "data": {
    "id": "9f1c2e3a-1234-4a5b-8c9d-abcdef123456",
    "name": "August staff rewards",
    "country": "NG",
    "amount": "500.00",
    "categoryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"]
  }
}

Response fields

The actual send. Submit up to 1000 recipients (name + email only — no per-row amount, the campaign's amount applies to every code) against a campaign you already created. Each recipient gets emailed their code directly — there is no separate delivery step. A malformed row never fails the whole submission; check the per-row results array.

Request body

Required headers

Example request

curl -X POST "https://api.rewardscardafrica.com/v1/campaigns/9f1c2e3a-1234-4a5b-8c9d-abcdef123456/recipients" \
  -H "X-API-Key: your_api_key_here" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "name": "Lerisha Naidoo", "emailAddress": "lerisha@example.com" },
      { "name": "Sipho Dube", "emailAddress": "sipho@example.com" }
    ]
  }'

import { randomUUID } from "crypto"; // Node.js

const campaignId = "9f1c2e3a-1234-4a5b-8c9d-abcdef123456";

const response = await fetch(
  `https://api.rewardscardafrica.com/v1/campaigns/${campaignId}/recipients`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key_here",
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipients: [
        { name: "Lerisha Naidoo", emailAddress: "lerisha@example.com" },
        { name: "Sipho Dube", emailAddress: "sipho@example.com" },
      ],
    }),
  }
);

const { results, generatedCards } = await response.json();
// results has one entry per row — check status: "SENT" | "FAILED" per row,
// a partial failure does not fail the whole submission.

import uuid, requests

campaign_id = "9f1c2e3a-1234-4a5b-8c9d-abcdef123456"

resp = requests.post(
    f"https://api.rewardscardafrica.com/v1/campaigns/{campaign_id}/recipients",
    headers={
        "X-API-Key": "your_api_key_here",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "recipients": [
            {"name": "Lerisha Naidoo", "emailAddress": "lerisha@example.com"},
            {"name": "Sipho Dube", "emailAddress": "sipho@example.com"},
        ],
    },
)
resp.raise_for_status()
data = resp.json()
results = data["results"]
generated_cards = data["generatedCards"]

Example response

{
  "message": "2 of 2 codes sent.",
  "results": [
    { "row": 1, "emailAddress": "lerisha@example.com", "status": "SENT", "cardNumber": "RWDNG-8847-2291-XKQP" },
    { "row": 2, "emailAddress": "sipho@example.com", "status": "SENT", "cardNumber": "RWDNG-1122-3344-ABCD" }
  ],
  "generatedCards": [
    { "cardNumber": "RWDNG-8847-2291-XKQP", "emailAddress": "lerisha@example.com", "amount": "500.00", "currency": "NGN" },
    { "cardNumber": "RWDNG-1122-3344-ABCD", "emailAddress": "sipho@example.com", "amount": "500.00", "currency": "NGN" }
  ]
}

Response fields

Per-row validation and dedup

• Deduplication happens per row within a campaign recipient submission — if the recipient's email already exists with an ACTIVE account, that account is reused rather than creating a duplicate.
• A currency mismatch (the recipient's existing account is a different currency than the campaign's country) fails that row with a clear reason, rather than silently issuing the wrong currency.
• There is no cross-request deduplication by design — submitting the same CSV twice against the same campaign issues a second batch of codes. Use a distinct Idempotency-Key per submission to guard against accidental retries.

Timeout and retry behaviour

• The API has a 15-second server-side timeout. If a response does not arrive within 15 seconds, the server closes the connection and returns 504.
• On a 504, some recipients in the batch may have already been sent — the internal call may have completed the submission before the timeout was hit on your end.
• Always retry a 504 with the same Idempotency-Key rather than a fresh one — this returns the original result if the submission actually completed, instead of sending the batch a second time.
• 500 responses are never cached by the idempotency store. You can always retry a 500.

Daily spend cap

• Checked as ONE total for the whole submission — the campaign's amount × the number of recipients — before any code is generated, not per-recipient afterward.
• If the total would exceed your cap, the entire submission is rejected with 429 and nothing is sent. Reduce the batch size or contact tech@ribirewards.com to raise your limit.

Generates a batch of codes with no named recipient yet — for you to distribute yourself (CSV, your own UI, however fits your flow). No email is sent. This is the counterpart to submitting recipients above: use that endpoint when you already know who's getting a code, use this one when you just want a batch of codes in hand. Every code, either way, belongs to a campaign — there is no standalone/unscoped issuance path.

Request body

Example request

curl -X POST "https://api.rewardscardafrica.com/v1/reward-cards/generate" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 10,
    "country": "NG",
    "amount": 500,
    "campaignId": "9f1c2e3a-1234-4a5b-8c9d-abcdef123456",
    "categoryIds": ["9f1c2e3a-1234-4a5b-8c9d-abcdef123456"]
  }'

const campaignId = "9f1c2e3a-1234-4a5b-8c9d-abcdef123456";

const response = await fetch(
  "https://api.rewardscardafrica.com/v1/reward-cards/generate",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      quantity: 10,
      country: "NG",
      amount: 500,
      campaignId, // required — every batch belongs to a campaign
      categoryIds: ["9f1c2e3a-1234-4a5b-8c9d-abcdef123456"], // optional, re-picked each call
    }),
  }
);

const { codes } = await response.json();
// codes: [{ rewardCardId, cardNumber, serialNumber, amount, currency, expiredAt }]
// No email is sent — cardNumber is yours to distribute however you choose.

import requests

campaign_id = "9f1c2e3a-1234-4a5b-8c9d-abcdef123456"

resp = requests.post(
    "https://api.rewardscardafrica.com/v1/reward-cards/generate",
    headers={
        "X-API-Key": "your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "quantity": 10,
        "country": "NG",
        "amount": 500,
        "campaignId": campaign_id,  # required
        "categoryIds": ["9f1c2e3a-1234-4a5b-8c9d-abcdef123456"],  # optional
    },
)
resp.raise_for_status()
codes = resp.json()["codes"]

Example response

{
  "message": "10 codes generated.",
  "codes": [
    {
      "rewardCardId": "rc_aaa111",
      "cardNumber": "RWDNG-8847-2291-XKQP",
      "serialNumber": "8847229 1XKQP",
      "amount": "500.00",
      "currency": "NGN",
      "expiredAt": "2029-09-08"
    }
  ]
}

Response fields

Re-scoping an existing campaign

• Country and category scope resolve per-campaign at redemption time, not per code-batch — there is no per-card scope. A generate call that would change a campaign's country or categories is only allowed while that campaign has no codes issued yet.
• Once a campaign has any codes issued (via this endpoint or by submitting recipients), a further generate call with a different country or categoryIds is rejected with 409 — this is deliberate, not a bug. An in-place scope change would silently reshape what already-issued, possibly already-distributed codes can redeem.
• To use a different scope, create a new campaign rather than trying to change an active one.

Daily spend cap

• Checked as ONE total for the whole batch — amount × quantity — before any code is generated, same as recipient submission.
• If the total would exceed your cap, the entire batch is rejected with 429 and nothing is generated.

Same shape as GET /v1/reward-card-redemptions, filtered to one campaign — see that endpoint below for the full field reference. Use this when you need redemption activity for a specific campaign rather than your whole account's history.

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/campaigns/9f1c2e3a-1234-4a5b-8c9d-abcdef123456/redemptions" \
  -H "X-API-Key: your_api_key_here"

const campaignId = "9f1c2e3a-1234-4a5b-8c9d-abcdef123456";

const resp = await fetch(
  `https://api.rewardscardafrica.com/v1/campaigns/${campaignId}/redemptions`,
  { headers: { "X-API-Key": "your_api_key_here" } }
);
const { redemptions } = await resp.json();

import requests

campaign_id = "9f1c2e3a-1234-4a5b-8c9d-abcdef123456"

resp = requests.get(
    f"https://api.rewardscardafrica.com/v1/campaigns/{campaign_id}/redemptions",
    headers={"X-API-Key": "your_api_key_here"},
)
resp.raise_for_status()
redemptions = resp.json()["redemptions"]

Returns your current wallet balance. Balance is a computed value — the sum of all completed transactions on your account — not a raw stored field. The value returned is always accurate to the time of the request.

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/wallet-balance" \
  -H "X-API-Key: your_api_key_here"

const resp = await fetch(
  "https://api.rewardscardafrica.com/v1/wallet-balance",
  { headers: { "X-API-Key": "your_api_key_here" } }
);
const { amount, currency } = await resp.json();

resp = requests.get(
    "https://api.rewardscardafrica.com/v1/wallet-balance",
    headers={"X-API-Key": "your_api_key_here"},
)
data = resp.json()  # { "amount": 2450.00, "currency": "USD" }

Example response

{
  "currency": "USD",
  "amount": 2450.00
}

Response fields

Notes

• amount is a number (not a string), unlike product and card amounts which are strings. This is consistent with how the underlying computation returns it.
• Wallet currency is fixed per your partnership agreement. Contact tech@ribirewards.com if you need to top up or change the currency.
• There is no pagination or history endpoint for wallet transactions at this time.

Returns all reward cards issued via your API key, with their current card status and fulfilment status. Use this to track deliveries, build your own reconciliation, or poll for status updates without implementing a webhook listener.

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/reward-card-redemptions" \
  -H "X-API-Key: your_api_key_here"

const resp = await fetch(
  "https://api.rewardscardafrica.com/v1/reward-card-redemptions",
  { headers: { "X-API-Key": "your_api_key_here" } }
);
const { redemptions } = await resp.json();
const pending = redemptions.filter(r => r.fulfilmentStatus !== "ORDER_DELIVERED");

resp = requests.get(
    "https://api.rewardscardafrica.com/v1/reward-card-redemptions",
    headers={"X-API-Key": "your_api_key_here"},
)
redemptions = resp.json()["redemptions"]
pending = [r for r in redemptions if r["fulfilmentStatus"] != "ORDER_DELIVERED"]

Example response

{
  "redemptions": [
    {
      "rewardCardId": "rc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "cardNumber": "RWDZA-8847-2291-XKQP",
      "recipientEmail": "lerisha@example.com",
      "amount": "500.00",
      "currency": "ZAR",
      "status": "ACTIVE",
      "orderNumber": "RCA-20260818-001",
      "fulfilmentStatus": "ORDER_PLACED",
      "issuedAt": "2026-08-18T10:23:00.000Z",
      "redeemedAt": null
    }
  ]
}

Response fields — redemption record

Notes

• Results are scoped to your partner account only. You cannot retrieve cards issued by other partners.
• There is no pagination at this time — all records are returned in a single response. Contact us if you need cursor-based pagination.
• status and fulfilmentStatus are distinct. A card can be ACTIVE (not yet redeemed by the recipient) while its fulfilmentStatus is ORDER_DELIVERED (the product has been delivered).
• Use this endpoint to poll for fulfilment updates rather than building a webhook listener — polling once every few minutes is sufficient for most fulfilment scenarios.

Request API access. This is the one endpoint that does not require authentication — it exists for integrators who do not have a key yet. Submitting this form notifies the RibiRewards team directly. Key provisioning is manual and typically takes one business day.

Request body

Example response

{
  "message": "Request received. We'll be in touch at your contact email within 1 business day."
}

Notes

• This endpoint is rate-limited to 5 requests per 15 minutes per IP to prevent spam. Every successful submission sends a real notification email.
• If you need faster turnaround, email tech@ribirewards.com directly.
• Key provisioning is manual — submission does not automatically create an account or key.

For partners who use the partner dashboard (partner.rewardscardafrica.com) but never integrate with this API directly. Exchanges an email address and a dashboard key — a separate credential from your API key, issued by the RibiRewards team — for your partner details. This endpoint is itself the authentication check, so it does not require an X-API-Key header. A dashboard key cannot be used as an X-API-Key on any other endpoint, and an API key cannot be used here.

Request body

Example request

curl -X POST "https://api.rewardscardafrica.com/v1/dashboard-login" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "you@yourcompany.com",
    "dashboardKey": "your_dashboard_key_here"
  }'

const response = await fetch(
  "https://api.rewardscardafrica.com/v1/dashboard-login",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      emailAddress: "you@yourcompany.com",
      dashboardKey: "your_dashboard_key_here",
    }),
  }
);

if (!response.ok) {
  const { message } = await response.json();
  throw new Error(message);
}

const { partnerId, partnerName, portalSlug } = await response.json();

resp = requests.post(
    "https://api.rewardscardafrica.com/v1/dashboard-login",
    json={
        "emailAddress": "you@yourcompany.com",
        "dashboardKey": "your_dashboard_key_here",
    },
)
resp.raise_for_status()
data = resp.json()  # { "partnerId": "...", "partnerName": "...", "portalSlug": null }

Example response

{
  "partnerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "partnerName": "Xoxoday",
  "portalSlug": null
}

Response fields

Notes

• A wrong email, a wrong key, or a key that has been deactivated all return the same 422 and the same message — the response never reveals whether a given email is enrolled.
• This endpoint is rate-limited to 10 requests per 15 minutes per IP — a separate, tighter budget from the general edge limit, since this is a login endpoint. See Rate limits.
• A successful login here does not create a session or token — save the emailAddress and dashboardKey yourself and send both again as headers on every subsequent dashboard call (see the next two endpoints).

The dashboard-key equivalent of GET /v1/wallet-balance — identical response shape, same underlying computation. Authenticated with X-Dashboard-Email and X-Dashboard-Key headers instead of X-API-Key.

Headers

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/dashboard/wallet-balance" \
  -H "X-Dashboard-Email: you@yourcompany.com" \
  -H "X-Dashboard-Key: your_dashboard_key_here"

const resp = await fetch(
  "https://api.rewardscardafrica.com/v1/dashboard/wallet-balance",
  {
    headers: {
      "X-Dashboard-Email": "you@yourcompany.com",
      "X-Dashboard-Key": "your_dashboard_key_here",
    },
  }
);
const { amount, currency } = await resp.json();

resp = requests.get(
    "https://api.rewardscardafrica.com/v1/dashboard/wallet-balance",
    headers={
        "X-Dashboard-Email": "you@yourcompany.com",
        "X-Dashboard-Key": "your_dashboard_key_here",
    },
)
data = resp.json()

Example response

{
  "currency": "USD",
  "amount": 2450.00
}

Response fields

Notes

• Missing or invalid X-Dashboard-Email / X-Dashboard-Key headers return 422 — this route never falls through to anonymous access.

The dashboard-key equivalent of GET /v1/reward-card-redemptions — identical response shape. Authenticated with X-Dashboard-Email and X-Dashboard-Key headers instead of X-API-Key.

Headers

Example request

curl -X GET "https://api.rewardscardafrica.com/v1/dashboard/reward-card-redemptions" \
  -H "X-Dashboard-Email: you@yourcompany.com" \
  -H "X-Dashboard-Key: your_dashboard_key_here"

const resp = await fetch(
  "https://api.rewardscardafrica.com/v1/dashboard/reward-card-redemptions",
  {
    headers: {
      "X-Dashboard-Email": "you@yourcompany.com",
      "X-Dashboard-Key": "your_dashboard_key_here",
    },
  }
);
const { redemptions } = await resp.json();

resp = requests.get(
    "https://api.rewardscardafrica.com/v1/dashboard/reward-card-redemptions",
    headers={
        "X-Dashboard-Email": "you@yourcompany.com",
        "X-Dashboard-Key": "your_dashboard_key_here",
    },
)
redemptions = resp.json()["redemptions"]

Response fields — redemption record

Notes

• Results are scoped to your partner account only, same as the API-key version.
• Missing or invalid X-Dashboard-Email / X-Dashboard-Key headers return 422 — this route never falls through to anonymous access.

These headers are present on every response.

All error responses follow the same shape. The message field is always human-readable. Validation errors also include an errors array.

// Standard error
{ "message": "Human-readable description." }

// Validation error (422)
{
  "message": "Validation failed.",
  "errors": [
    { "type": "field", "msg": "Amount must be a positive number.", "path": "amount", "location": "body" }
  ]
}

{ "message": "Selected country is not supported." }

{ "message": "Idempotency-Key header is required for this request." }

{ "message": "Not found." }

{ "message": "Missing X-API-Key header." }

{ "message": "Invalid or inactive API key." }

{
  "message": "Validation failed.",
  "errors": [
    { "type": "field", "msg": "Amount must be a positive number.", "path": "amount", "location": "body" }
  ]
}

{ "message": "Too many requests for this account. Please slow down and try again shortly." }

{ "message": "Daily spend cap reached for this account. Contact RibiRewards to raise your limit or try again tomorrow." }

{ "message": "Request timed out." }

{ "message": "Something went wrong. Please try again later." }

Fulfilment status

Reflects whether the physical or digital product has been delivered. Returned as fulfilmentStatus on each entry from GET /v1/reward-card-redemptions or GET /v1/campaigns/:campaignId/redemptions.

Card status

Reflects the lifecycle of the card itself — distinct from fulfilment status. Returned as status in the redemptions list.

Country coverage expands without notice. Adding a new country requires a backend whitelist update — it is not solely a catalogue upload. Re-confirm the live list by calling the catalogue endpoint rather than hardcoding this table.

To request a specific market, email tech@ribirewards.com.

campaignId

UUID of a campaign you created via POST /v1/campaigns. Every code issued through POST /v1/campaigns/:campaignId/recipients belongs to one campaign, which carries the country, amount, and category scope shared by every recipient in it.

rewardCardId / cardNumber

cardNumber is the actual redemption code — what a recipient uses to claim their reward. Returned per-recipient in generatedCards after a submission, and appears in redemption records.

categoryIds

Category UUIDs from GET /v1/categories, passed when creating a campaign. Scopes every recipient's shop to just those categories. Omit for the full catalogue.

fulfilment status

Whether the physical or digital product has been delivered (ORDER_PLACED, PROCESSING, SHIPPED, ORDER_DELIVERED, CANCELLED, EXPIRED). Distinct from card status.

card status

The lifecycle state of the card itself (PENDING, ACTIVE, REDEEMED, EXPIRED, BLOCKED). A card starts PENDING at issuance and becomes ACTIVE once the recipient claims it on the redemption shop. Distinct from fulfilment status.

idempotency key

A UUID you generate and include in the Idempotency-Key request header on POST /v1/campaigns/:campaignId/recipients. Guarantees that retrying a timed-out request does not resend the same batch of codes. Scoped per partner, expires after 24 hours, Redis-backed.

markupPct

A per-partner markup percentage configured by the RibiRewards team. If set, product amounts in the catalogue are already marked up in the API response — you do not apply markup yourself.

daily spend cap

A per-currency daily ceiling on total redemption value per partner. Checked as one total (campaign amount × recipient count) before a submission is processed. Resets at midnight UTC. Returns 429 when reached. Contact tech@ribirewards.com to raise it.

dashboard key

A separate login credential from your API key, for partners who use the partner dashboard (partner.rewardscardafrica.com) but never call the API directly. Issued by the RibiRewards team. Cannot be used as an X-API-Key — it only works with POST /v1/dashboard-login and the /v1/dashboard/* endpoints, including the dashboard-mounted versions of every campaign endpoint.

portalSlug

Returned by POST /v1/dashboard-login. Set only for partners with a dedicated, isolated redemption portal. Used internally for portal routing — most integrators can ignore this field.