Voucher Integration Guide

An Essential Wallet voucher is a code worth money — a fixed amount off, or a percentage off — that its creator has already funded. This guide is for anyone who wants to accept vouchers: a shop owner with no developer, or an engineering team building a checkout. There are exactly two ways to integrate, and both run the same secure flow underneath (the shopper proves the voucher is theirs with a one-time SMS code).

{ "code": "FOOD2026", "type": "fixed", "category": "food", "amount_kobo": 500000, "total_uses": 20, "used_count": 8, "status": "active", "expires_at": "2026-12-31T23:59:59+00:00" }

All amounts are in kobo (₦1 = 100 kobo), as integers — never floats.

Vouchers are pre-funded. The moment a creator mints one, their wallet is debited for the full worst-case payout and that value sits in escrow until a shopper redeems it. Nothing is created from nothing, and there is no way to redeem a voucher the creator hasn't paid for.

fixed voucher:       amount_kobo    × total_uses
percentage voucher:  max_amount_kobo × total_uses      // the cap is the worst case per use

CREATE   creator wallet −amount×uses   →  voucher ACTIVE, use(s) in escrow
   │
REDEEM   shopper enters code + phone, passes the SMS code
   │     →  reservation PENDING, one use held (expires in 30 minutes), NO money moves yet
   │
   ├── CONFIRM   merchant wallet +discount   →  redemption CONFIRMED   (sale honoured)
   ├── RELEASE   use handed back             →  redemption RELEASED    (no sale; voucher reusable)
   └── (no confirm within 30 min → the hold EXPIRES and the use is handed back automatically)

REVERSE  a CONFIRMED settlement can be reversed:
         merchant wallet −discount, use handed back  →  redemption REVERSED, value back in escrow

If you can edit your website's HTML, you can accept vouchers. There's nothing to install, build, or run on your server. The widget renders the whole experience — code entry, the SMS code, and the confirmation — and talks to Essential Wallet directly from the shopper's browser.

Step 1 — paste these two lines where you want the box

<script src="https://api-ewallet.eroot.ng/voucher-widget.js" async></script>

<div
    data-essential-voucher-widget
    data-publishable-key="epk_YOUR_PUBLISHABLE_KEY"
    data-api-base="https://api-ewallet.eroot.ng"
    data-cart-kobo="2500000"
    data-category="food"
    data-auto-confirm="true"></div>

Step 2 — set two values for your store

• data-cart-kobo — the shopper's current order total, in kobo (₦25,000 = 2500000). The discount is worked out from this.
• data-category — the kind of goods you sell, so the right vouchers are accepted (one of the seven category values above).

Step 3 (optional) — tidy up

• Set data-auto-confirm="true" so a verified voucher settles immediately — no server needed. Leave it off if your backend will confirm the sale itself.
• Brand it with data-accent="#7c3aed" and data-title="Have a voucher?".
• If your cart total changes live, tell the widget: EssentialVoucher.updateCart(el, 1999000).

document.querySelector('[data-essential-voucher-widget]')
    .addEventListener('essential-voucher:redeemed', function (e) {
        var reservation = e.detail.reservation;   // { discount_kobo, amount_to_charge_kobo, redemption_reference, ... }
        console.log('Discount:', reservation.discount_kobo / 100);
    });

Essential Wallet issues merchant keys to the store's own Essential Wallet account. There's no self-serve portal yet — contact support, and an operator issues a key pair. The response is shown once, so store it safely.

The merchant API is server-to-server: your backend holds the secret key and makes these calls. The shopper never sees a key; they only ever type the voucher code, their phone number, and the SMS code. Below is the complete flow with copy-paste samples.

1. Look up the voucher — optional but recommended

Confirm the code is real and see the discount for the current cart before you ask the shopper for anything.

code — the voucher code · ?cart_kobo=2500000 optional, gives preview_value_kobo

HTTP 200
{
    "status": true,
    "data": {
        "code": "FOOD2026", "type": "fixed", "category": "food",
        "valid": true, "reason": null,
        "amount_kobo": 500000, "percentage": null, "max_amount_kobo": null,
        "preview_value_kobo": 500000, "uses_remaining": 12
    }
}

HTTP 404 { "error": "Voucher not found." }

2. Send the shopper a code

This texts a 6-digit code to the shopper's phone. It only works for vouchers that settle to your store, and only if the phone belongs to an Essential Wallet account.

{ "phone": "08012345678" }

HTTP 200
{ "status": true, "message": "A verification code has been sent to that number.",
  "data": { "otp_reference": "otp_9f2c…", "expires_at": "2026-10-13T10:17:00+00:00" } }

HTTP 422 { "error": "No Essential Wallet account found for that phone number." }
HTTP 422 { "error": "This voucher is invalid or has expired." }
HTTP 429 { "error": "Too many verification codes requested for this number. Try again later." }

3. Redeem — reserve the discount

Exchange the SMS code for a reservation. This holds one use for 30 minutes and returns the exact amount to charge. No money moves yet.

{
    "otp_reference":   "otp_9f2c…",
    "otp":             "482913",
    "cart_kobo":       2500000,
    "order_reference": "ORDER-8841",
    "category":        "food"
}

HTTP 200
{
    "status": true,
    "data": {
        "mode": "checkout",
        "redemption_reference": "vch_ab12cd34ef56",
        "discount_kobo": 500000,
        "amount_to_charge_kobo": 2000000,
        "order_reference": "ORDER-8841",
        "expires_at": "2026-10-13T10:47:00+00:00"
    }
}

HTTP 422 { "error": "This voucher is only valid for food purchases, not medical." }
HTTP 422 { "error": "Incorrect verification code." }

4. Charge the shopper, then confirm

Charge your own payment provider for amount_to_charge_kobo (the total minus the discount). Once that succeeds, call confirm and the discount is paid into your wallet.

reference — the redemption_reference from step 3

HTTP 200
{ "status": true, "message": "Settlement confirmed. ₦5,000.00 credited to the merchant's wallet.",
  "data": { "redemption_reference": "vch_ab12cd34ef56", "status": "confirmed", "amount_settled_kobo": 500000 } }

If the charge fails, free the hold so the voucher can be used again:

reference — the redemption_reference from step 3

HTTP 200 { "status": true, "message": "Reservation released. The voucher can be redeemed again." }

Putting it together (PHP)

$key   = getenv('ESSENTIAL_MERCHANT_KEY');          // esk_…
$base  = 'https://api-ewallet.eroot.ng/api';
$auth  = ['Authorization' => "Bearer {$key}", 'Content-Type' => 'application/json'];

function call($method, $url, $body = null) {
    global $auth;
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => array_map(fn($k, $v) => "$k: $v", array_keys($auth), $auth),
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    if (!empty($res['error'])) { throw new RuntimeException($res['error']); }
    return $res['data'] ?? $res;
}

// 1. shopper enters code + phone
call('POST', "{$base}/merchant/vouchers/{$code}/redeem/request-otp", ['phone' => $phone]);

// 2. shopper enters the SMS code
$reservation = call('POST', "{$base}/merchant/vouchers/redeem", [
    'otp_reference'   => $otpReference,
    'otp'             => $otp,
    'cart_kobo'       => $cartKobo,
    'order_reference' => "ORDER-{$orderId}",
    'category'        => 'food',
]);

// 3. charge Shopper.php for $reservation['amount_to_charge_kobo'] with YOUR gateway…

// 4. payment succeeded — settle the discount to your wallet
call('POST', "{$base}/merchant/vouchers/redeem/{$reservation['redemption_reference']}/confirm");

Shopper                Your server (or the widget)          Essential Wallet
  │                              │                                     │
  │ enters code + phone ───────► │ POST …/request-otp ───────────────► │ SMS a 6-digit code
  │ ◄─────────────────────────── │                                     │
  │ types SMS code ────────────► │ POST …/redeem ────────────────────► │ hold 1 use, 30 min
  │ ◄── "₦5,000 off; pay ₦20,000" │ ◄── reservation reference ─────── │
  │ pays reduced total to YOU ─► │ (your own payment gateway)          │
  │                              │ POST …/confirm ───────────────────► │ discount → your wallet
  │                              │                                     │ ✅ settled

A store's job is steps 1–4: identify the shopper, get the reservation, take payment, confirm. If anything fails before payment, release the reservation (or just let the 30-minute hold lapse) — the voucher returns to full availability either way.

Networks flake and webhooks fire twice. Every step is built to be retried safely:

• Redeem is keyed on your order_reference. Retry the same order and you get the same reservation back — never a second use burned. Use a fresh reference only for a genuinely new order.
• Confirm and release tolerate repeats. Confirming an already-confirmed reservation returns the original success without paying twice; releasing an already-released one is a no-op.
• Distinct references per order. Reusing one order_reference for two different orders will return the first reservation, not a new one.

These endpoints let a store see and control the vouchers that settle to it. Everything is scoped to your own store — another merchant's voucher reads back as a plain 404, identical to one that doesn't exist.

HTTP 200
{ "status": true, "data": [ { "code": "FOOD2026", "status": "active", "valid": true, "uses_remaining": 12, ... } ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 } }

code — the voucher code

HTTP 200 { "status": true, "message": "Voucher paused. It can no longer be redeemed until resumed.", "data": { "status": "paused" } }

code — the voucher code

HTTP 200 { "status": true, "message": "Voucher resumed.", "data": { "status": "active" } }
HTTP 422 { "error": "This voucher has expired and cannot be resumed." }

HTTP 200
{ "status": true, "data": [ { "reference": "vch_ab12cd34ef56", "status": "confirmed", "mode": "checkout",
  "amount_credited_kobo": 500000, "order_reference": "ORDER-8841", ... } ] }

If an order is refunded or a settlement was wrong, a confirmed redemption can be reversed. The credited party is debited and the voucher use is handed back — the value goes back into escrow (the creator is not paid out), so it can be used again.

reference — the redemption_reference of a confirmed settlement

{ "reason": "Order cancelled — refunded the shopper" }   // optional, recorded for support

HTTP 200 { "status": true, "message": "Settlement reversed. ₦5,000.00 returned to escrow; the voucher use has been reopened.",
  "data": { "reference": "vch_ab12cd34ef56", "status": "reversed" } }

HTTP 422 { "error": "Only a settled redemption can be reversed." }
HTTP 422 { "error": "The credited wallet no longer holds enough balance to reverse this settlement. Escalate to support." }

Wallet-mode credits (paid into a shopper's wallet) and disputed settlements are reversed by an Essential Wallet admin via POST /vouchers/redemptions/{reference}/reverse — the merchant API has no business touching a credit paid into someone's wallet.

Rather than polling GET /merchant/redemptions/{reference}, register one HTTPS endpoint and receive the reservation lifecycle as it happens. Delivery is best-effort and never blocks the money path — the redemption settles whether or not your endpoint is up, and failed attempts are retried with backoff and logged. Registering opts you into all four events.

# Set the destination. Returns a signing_secret ONCE — store it.
curl -X PUT https://api.ewallet.eroot.ng/api/merchant/webhook \
  -H "Authorization: Bearer esk_..." -H "Content-Type: application/json" \
  -d '{"url":"https://store.example.com/wallet/webhook"}'

# Recent attempts (filter with ?status=failed or ?event=reservation.confirmed)
curl https://api.ewallet.eroot.ng/api/merchant/webhook/deliveries \
  -H "Authorization: Bearer esk_..."

Each delivery is signed. Verify it before trusting the body, then return any 2xx to acknowledge:

$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_ESSENTIAL_TIMESTAMP'];   // X-Essential-Timestamp
$expected  = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, $signingSecret);  // your whsec_...
$received  = $_SERVER['HTTP_X_ESSENTIAL_SIGNATURE'];   // X-Essential-Signature

if (! hash_equals($expected, $received)) { http_response_code(400); exit; }

$event = json_decode($body, true);   // $event['type'], $event['data']['redemption_reference'], ...
http_response_code(200);             // non-2xx is retried 6x over ~24h

Full field list and error semantics are in the API reference → Webhooks.

Failures return a non-2xx status and one JSON envelope. Branch on the stable code, and show the human-readable message to staff — never match on the English text. The legacy error field is kept as a deprecated alias of message.

{ "status": false, "code": "voucher.category_mismatch",
  "message": "This voucher is only valid for food purchases, not medical.",
  "details": { "expected": "food", "received": "medical" }, "error": "…" }

• There is no sandbox — keys work against live data. Test with a small real voucher and amounts you're comfortable with.
• The redeeming phone number must belong to an existing Essential Wallet account, or the OTP request returns "No Essential Wallet account found". Register a test wallet first.
• The creator of a voucher cannot redeem their own voucher — use two accounts.
• A shopper can only use a given voucher once (per active reservation).