How to issue reward cards via API in Nigeria — a step-by-step guide

A practical guide for developers and product teams integrating programmatic reward card issuance into Nigerian platforms. Covers trigger design, Naira denomination, delivery channel selection, and the failure modes that will bite you if you skip them.

Nigeria is the largest reward market in sub-Saharan Africa by both population and B2B programme volume. FMCG brands, fintechs, betting platforms, banks, telecoms, and employers are all issuing rewards at scale — or trying to. The technical integration is straightforward when you understand the market-specific considerations. When you don't, you get high issuance rates and low redemption, and you spend three weeks debugging something that wasn't a code problem.

This guide walks through the complete integration — from designing your trigger events to delivering a Naira-denominated reward card to a Nigerian recipient's WhatsApp or USSD session.

Step 1 — Design your trigger events before you write a line of code

The most common integration mistake is treating the API call as the starting point. It isn't. The starting point is a precise definition of what event should trigger a reward, for which recipient, of what value, in which format.

Get this wrong and you'll either over-issue (giving rewards for actions that don't warrant them, burning budget) or under-issue (missing qualifying events because your trigger logic has edge cases). Both are expensive.

For each reward trigger in your programme, define:

• The qualifying event

  Purchase confirmed, bet settled, milestone reached, referral activated, survey submitted — be specific. 'Purchase' is not specific enough. 'First purchase above ₦5,000 on a qualifying SKU, confirmed by payment gateway webhook' is.

• The recipient identifier

  Phone number is preferred for Nigerian programmes. Most delivery channels (USSD, WhatsApp, SMS) route on phone number. Email works for corporate employee programmes but reaches fewer people reliably.

• The reward value and currency

  Always NGN. Never USD with conversion. ₦2,000, ₦5,000, ₦10,000 — set the value in Naira at the moment of issuance.

• The reward category

  Grocery, electronics, fashion, connectivity, beauty, food, fuel — the category determines which brands the recipient can choose from at redemption.

• The delivery channel

  WhatsApp for smartphone users, USSD for any phone, SMS for confirmation. Decide based on your recipient profile.

• Deduplication logic

  What prevents the same event from triggering twice? Payment gateway retries, duplicate webhooks, and race conditions will fire your trigger more than once if you don't handle them.

Step 2 — Authentication and environment setup

The QIFTS API uses bearer token authentication. Every request includes your API key in the Authorization header. Use separate keys for your test and production environments — this sounds obvious but causes real production incidents when test keys accidentally go live.

// Environment variables — never hardcode keys
QIFTS_API_KEY=qf_live_xxxxxxxxxxxxxxxx
QIFTS_BASE_URL=https://api.qifts.com/v1

// Request headers — every call
{
  "Authorization": "Bearer qf_live_xxxxxxxxxxxxxxxx",
  "Content-Type": "application/json",
  "Idempotency-Key": "your-unique-event-id"  // critical
}

Step 3 — The issuance call

The core API call is a POST to /v1/rewards/issue. For a Nigerian programme, the payload looks like this:

// Request
{
  "recipient": {
    "phone": "+2348012345678",   // E.164 format, NG country code
    "name": "Chidinma A."       // optional — personalises delivery message
  },
  "reward": {
    "value": 5000,
    "currency": "NGN",          // always NGN for Nigerian programmes
    "category": "grocery",      // grocery | electronics | fashion |
                                //  connectivity | beauty | food | fuel
    "expires_days": 90          // 30, 60, or 90 — default 90
  },
  "delivery": {
    "channel": "whatsapp",      // whatsapp | ussd | sms | web
    "language": "en"            // en | yo | ig | ha (Yoruba/Igbo/Hausa)
  },
  "programme": {
    "id": "prog_fmcg_q2_2026",
    "trigger": "purchase_confirmed",
    "reference": "order_88211bc"  // your internal event ID
  }
}

// Response
{
  "reward_id": "rwd_NG_9f3k2m",
  "status": "issued",
  "recipient": "+2348012345678",
  "value": 5000,
  "currency": "NGN",
  "category": "grocery",
  "delivery": {
    "channel": "whatsapp",
    "status": "delivered",
    "delivered_at": "2026-06-01T14:23:01.441Z"
  },
  "redemption": {
    "code": "QFT-8821-NG",
    "expires_at": "2026-08-30T23:59:59Z",
    "brands": ["Shoprite Nigeria", "Spar Nigeria", "Justrite", "+6 more"]
  }
}

Language localisation

Nigeria has three major language groups beyond English — Yoruba (Southwest), Igbo (Southeast), and Hausa (North). If you know your recipient's language preference from your own user data, pass it in the delivery object. The WhatsApp and SMS message will be delivered in that language. Recipients who receive reward notifications in their own language redeem at measurably higher rates.

Step 4 — Handling the webhook response

Rather than polling for reward status, configure a webhook endpoint to receive delivery and redemption events. The QIFTS platform pushes events to your endpoint the moment a status changes.

// reward.delivered — fires when WhatsApp/SMS confirmed delivered
{
  "event": "reward.delivered",
  "reward_id": "rwd_NG_9f3k2m",
  "programme_reference": "order_88211bc",
  "delivered_at": "2026-06-01T14:23:01Z",
  "channel": "whatsapp"
}

// reward.redeemed — fires when recipient uses code at a brand
{
  "event": "reward.redeemed",
  "reward_id": "rwd_NG_9f3k2m",
  "redeemed_at": "2026-06-02T09:11:22Z",
  "brand": "Shoprite Nigeria",
  "value_redeemed": 5000,
  "currency": "NGN"
}

// reward.expired — fires if not redeemed before expiry
{
  "event": "reward.expired",
  "reward_id": "rwd_NG_9f3k2m",
  "expired_at": "2026-08-30T23:59:59Z"
}

Your webhook handler should return HTTP 200 within 5 seconds. If it doesn't, QIFTS will retry with exponential backoff. Make your handler idempotent — it may receive the same event more than once.

Step 5 — Nigeria-specific failure modes to handle

These are the issues that show up in Nigerian integrations specifically and aren't covered well in generic API documentation.

Step 6 — Testing your integration

Use the QIFTS sandbox environment for all testing. The sandbox behaves identically to production but routes delivery to a test phone number you configure. Run through these scenarios before going live:

• →Happy path: qualifying event fires, reward issued, WhatsApp delivered, recipient redeems
• →Duplicate event: same idempotency key sent twice — confirm only one reward issued
• →Invalid phone number: confirm your normalisation handles all four NG formats
• →WhatsApp fallback: set test phone to non-WhatsApp number — confirm USSD notification fires
• →Webhook delivery failure: return 500 from your endpoint — confirm QIFTS retries
• →Expiry: issue a test reward with 1-day expiry, confirm expiry webhook fires