API Documentation

{
    "first_name":    "Adewale",          // required
    "last_name":     "Yusuf",            // required
    "email":         "ade@example.com",  // required, unique
    "password":      "secret123",        // required, min 8
    "phone":         "08012345678",      // required
    "preferred_bank":"wema-bank",        // optional – provider slug
    "provider_slug": "wema-bank",        // optional – takes priority over preferred_bank
    "subaccount":    null,               // optional
    "split_code":    null,               // optional
    "metadata": [                        // optional key-value pairs
        { "key": "referral_code", "value": "REF123" }
    ]
}

HTTP 201
{
    "success": true,
    "message": "Registration successful! Your account and virtual bank account are ready.",
    "user": {
        "id": 12,
        "first_name": "Adewale",
        "last_name": "Yusuf",
        "email": "ade@example.com"
    },
    "customer": {
        "customer_code": "CUS_xxxxxxxxxxxx",
        "email": "ade@example.com"
    },
    "dedicated_account": {
        "account_name": "YUSUF ADEWALE",
        "account_number": "9876543210",
        "bank_name": "Wema Bank",
        "currency": "NGN"
    }
}

{
    "email":    "ade@example.com",  // required
    "password": "secret123"         // required
}

HTTP 200
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "message": "Login successful"
}

HTTP 200
{
    "success": true,
    "user": {
        "id": 12,
        "first_name": "Adewale",
        "last_name": "Yusuf",
        "email": "ade@example.com"
    }
}

HTTP 200
{
    "message": "Logged out successfully"
}

HTTP 200
{
    "status": true,
    "message": "Banks retrieved",
    "data": [
        { "id": 9, "name": "Guaranty Trust Bank", "code": "058", "slug": "guaranty-trust-bank", ... },
        { "id": 21, "name": "Zenith Bank", "code": "057", ... }
    ]
}

HTTP 200
{
    "success": true,
    "data": [
        {
            "id": 1,
            "user_id": 12,
            "customer_code": "CUS_xxxxxxxxxxxx",
            "email": "ade@example.com",
            "first_name": "Adewale",
            "last_name": "Yusuf",
            "phone": "08012345678"
        }
    ]
}

{
    "email":      "second@example.com", // required
    "first_name": "Ade",                // required
    "last_name":  "Yusuf",              // required
    "phone":      "08099887766",        // required
    "metadata":   [{ "key": "tier", "value": "standard" }] // optional
}

HTTP 201
{
    "success": true,
    "message": "Customer account created successfully.",
    "data": { "customer_code": "CUS_xxx", "email": "second@example.com", ... }
}

HTTP 422 { "success": false, "message": "You can create up to 3 customer accounts." }

customer_code — Paystack customer code e.g. CUS_xxxxxxxxxxxx

HTTP 200
{
    "success": true,
    "data": { "customer_code": "CUS_xxx", "email": "ade@example.com", ... }
}

customer_code — Paystack customer code

{
    "email":      "newemail@example.com",  // optional
    "first_name": "Ade",                   // optional
    "last_name":  "Yusuf",                 // optional
    "phone":      "08099887766",           // optional
    "metadata":   [{ "key": "tier", "value": "premium" }] // optional
}

HTTP 200
{
    "success": true,
    "message": "Customer updated successfully",
    "data": { ... }
}

customer_code — Paystack customer code

HTTP 200
{
    "success": true,
    "message": "Customer deleted successfully."
}

email (query) — user's email address

HTTP 200
{
    "success": true,
    "data": [ { "customer_code": "CUS_xxx", ... } ]
}

HTTP 200
{
    "status": true,
    "message": "Dedicated account providers retrieved",
    "data": [ { "provider_slug": "wema-bank", "bank_name": "Wema Bank", ... } ]
}

{
    "customer":      "CUS_xxxxxxxxxxxx",  // required
    "phone":         "08012345678",       // optional – updates customer phone
    "provider_slug": "wema-bank",         // optional – bank provider
    "preferred_bank":"wema-bank",         // optional – falls back if no provider_slug
    "subaccount":    "ACCT_xxx",          // optional
    "split_code":    "SPL_xxx"            // optional
}

HTTP 201
{
    "message": "Dedicated account created successfully.",
    "account_data": {
        "account_name": "YUSUF ADEWALE",
        "account_number": "9876543210",
        "bank": { "name": "Wema Bank", "slug": "wema-bank" },
        "currency": "NGN",
        "active": true
    }
}

email (query) — the user's email address

HTTP 200
{
    "success": true,
    "data": [
        { "account_number": "9876543210", "bank_name": "Wema Bank", "account_name": "...", "active": true }
    ]
}

email (query) — the user's email address

HTTP 200
{
    "status": true,
    "data": {
        "email": "ade@example.com",
        "dva_account_number": "9876543210",
        "balance": 42500.00,
        "transaction_count": 7
    }
}

Same structure as the public endpoint.

Same fields as POST /public/dedicated-account

HTTP 201
{
    "message": "Dedicated account created and saved successfully",
    "account_data": { ... }
}

HTTP 200
{
    "status": true,
    "data": [ { "account_number": "...", "bank_name": "...", ... } ]
}

account_number — the 10-digit account number

HTTP 200
{ "data": { "account_number": "9876543210", "bank_name": "Wema Bank", ... } }

account_number — the 10-digit account number

HTTP 200
{ "message": "Dedicated account deleted." }

{
    "amount_kobo": 200000   // required, min 10000 (₦100 floor)
}

HTTP 200
{
    "status": true,
    "data": {
        "authorization_url": "https://checkout.paystack.com/0peqxxxxxxxxxx",
        "access_code": "0peqxxxxxxxxxx",
        "reference": "wfund_9k2j7h1qz3xa8y0b5c4d"
    }
}

HTTP 422 { "errors": { "amount_kobo": ["The amount kobo must be at least 10000."] } }
HTTP 502 { "error": "Unable to start payment. Please try again." }   // Paystack initialize call failed

reference — the reference returned by /wallet/fund/initialize (also present as ?reference= on the Paystack redirect)

HTTP 200 (payment succeeded, first time this reference has been verified)
{
    "status": true,
    "data": {
        "credited": true,
        "amount_kobo": 200000,
        "balance": 4500000
    }
}

HTTP 200 (payment not completed yet — e.g. user abandoned checkout)
{ "status": true, "data": { "credited": false, "payment_status": "abandoned" } }

HTTP 404 { "error": "Reference not found." }   // unknown reference, or belongs to a different user
HTTP 502 { "error": "Unable to verify payment." }   // Paystack verify call failed

account_number (query) — 10-digit account number
bank_code      (query) — bank code e.g. 058 for GTBank

HTTP 200
{
    "status": true,
    "account_name": "YUSUF ADEWALE JAMIU",
    "account_number": "8133169835"
}

HTTP 422  (resolution failed)
{
    "status": false,
    "message": "Could not resolve account."
}

{
    "account_number": "8133169835",      // required, 10 digits
    "bank_code":      "999992",          // required
    "account_name":   "YUSUF ADEWALE"   // required
}

HTTP 200
{
    "recipient_code": "RCP_xxxxxxxxxxxx",
    "recipient_name": "YUSUF ADEWALE JAMIU"
}

{
    "amount":          300,                    // required, numeric, min 1 (Naira)
    "recipient":       "RCP_xxxxxxxxxxxx",     // required, Paystack recipient code
    "reason":          "Rent payment",         // optional, max 255
    "currency":        "NGN",                  // optional, default NGN
    "reference":       "trx_abc123def456ghij", // optional, unique, min 16 chars
    "save_beneficiary": true,                  // optional, saves to beneficiaries table
    "bank_code":       "999992",               // needed if save_beneficiary=true
    "bank_name":       "OPay"                  // needed if save_beneficiary=true
}

HTTP 201  (transfer queued — OTP may be required)
{
    "message": "Transfer initiated successfully.",
    "transfer_data": {
        "status":        "otp",
        "transfer_code": "TRF_xxxxxxxxxxxx",
        "reference":     "trx_abc123def456ghij",
        "amount":        30000,
        "recipient": {
            "details": {
                "account_name":   "GODSFAVOUR GILEAD EBERE",
                "account_number": "7044257292",
                "bank_name":      "OPay Digital Services"
            }
        }
    }
}

HTTP 400 — insufficient balance or bad request
HTTP 422 — validation errors
HTTP 422 { "error": "Daily transfer limit reached for unverified accounts (₦50,000.00/day). Verify your identity to remove this limit.", "code": "KYC_REQUIRED" }

per_page (query) — results per page, max 100, default 20
page     (query) — page number

HTTP 200
{
    "data": [
        {
            "id": 5,
            "reference": "trx_abc123",
            "type": "debit",
            "amount_kobo": 30000,
            "recipient_code": "RCP_xxx",
            "transfer_code": "TRF_xxx",
            "status": "success",
            "reason": "Rent payment",
            "currency": "NGN",
            "metadata": { ... },
            "created_at": "2026-05-21T13:39:45.000000Z"
        }
    ],
    "pagination": {
        "total": 24,
        "per_page": 20,
        "current_page": 1,
        "last_page": 2
    }
}

HTTP 200
{
    "status": true,
    "data": {
        "user_id": 12,
        "dva_account_number": "9876543210",
        "account_name": "YUSUF ADEWALE",
        "bank_name": "Wema Bank",
        "balance": 42000,           // in kobo — divide by 100 for Naira
        "transaction_count": 7,
        "last_updated": "2026-05-21T13:40:00.000000Z"
    }
}

HTTP 200
{
    "status": true,
    "data": { "currency": "NGN", "balance": 150000000 },
    "meta": { ... }
}

{
    "transfer_code": "TRF_xxxxxxxxxxxx",  // required
    "otp":           "928310"             // required, 4–10 digits
}

HTTP 200
{
    "message": "Transfer confirmed successfully.",
    "transfer_data": { "status": "success", ... }
}

{
    "transfer_code": "TRF_xxxxxxxxxxxx",  // required
    "reason":        "resend_otp"         // required, one of: resend_otp | transfer
}

HTTP 200 { "status": true, "message": "OTP has been resent" }

HTTP 200
{
    "status": true,
    "message": "OTP has been sent for disabling OTP requirement"
}

HTTP 403 { "error": "You are not authorized to change this setting." }

{ "otp": "482910" }  // required

HTTP 200 { "status": true, "message": "OTP requirement for transfers has been disabled" }
HTTP 403 { "error": "You are not authorized to change this setting." }

HTTP 200 { "status": true, "message": "OTP requirement for transfers has been enabled" }
HTTP 403 { "error": "You are not authorized to change this setting." }

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 3,
            "recipient_code": "RCP_xxxxxxxxxxxx",
            "name":           "GODSFAVOUR GILEAD EBERE",
            "account_number": "7044257292",
            "bank_code":      "999992",
            "bank_name":      "OPay Digital Services"
        }
    ]
}

recipient_code — Paystack recipient code e.g. RCP_xxxxxxxxxxxx

{
    "name":     "New Display Name",  // optional
    "bank_name":"OPay"               // optional
}

HTTP 200 { "message": "Recipient updated." }

{ "recipient_code": "RCP_xxxxxxxxxxxx" }  // required

HTTP 200 { "message": "Beneficiary deleted." }

HTTP 200
{
    "status": true,
    "data": [
        { "id": 1, "name": "Flex Save", "type": "flexible", "interest_rate": 8.5, "is_active": true },
        { "id": 2, "name": "Lock Save", "type": "locked",   "interest_rate": 12.0, "is_active": true }
    ]
}

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 4,
            "name": "House deposit",
            "balance_kobo": 500000,
            "balance_ngn": 5000.00,
            "target_ngn": 100000.00,
            "progress_percent": 5,
            "interest_rate": 8.5,
            "status": "active"
        }
    ]
}

{
    "savings_plan_id":    1,              // required, must exist and be active
    "name":               "House deposit",// required, max 100 chars
    "target_amount_kobo": 10000000,       // optional (100,000 NGN)
    "maturity_date":      "2027-01-01"   // optional, required for locked plans
}

HTTP 201
{
    "status": true,
    "message": "Savings account created.",
    "data": { "id": 4, "name": "House deposit", "balance_kobo": 0, ... }
}

account — savings account ID

{ "amount_kobo": 50000 }  // required, min 100 (= ₦1)

HTTP 200
{
    "status": true,
    "message": "Deposit successful.",
    "data": { "new_balance_kobo": 550000 }
}

account — savings account ID

{ "amount_kobo": 50000 }  // required, min 100

HTTP 200 { "status": true, "message": "Withdrawal successful." }
HTTP 422 { "error": "This account is locked until 01 Jan 2027." }

account — savings account ID

HTTP 200
{
    "status": true,
    "data": {
        "data": [ { "type": "deposit", "amount_kobo": 50000, "reference": "sav_dep_...", ... } ],
        "total": 5, "per_page": 20, "current_page": 1
    }
}

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 1, "name": "30-Day Plan",
            "duration_days": 30, "interest_rate": 9.5,
            "min_amount_kobo": 100000, "max_amount_kobo": 100000000,
            "is_active": true
        }
    ]
}

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 2, "reference": "fd_abc123",
            "principal_kobo": 100000, "interest_rate": 9.5,
            "start_date": "2026-05-01", "maturity_date": "2026-05-31",
            "status": "active",
            "total_at_maturity_kobo": 100790,
            "total_at_maturity_ngn": 1007.90,
            "days_remaining": 9
        }
    ]
}

{
    "fixed_deposit_plan_id": 1,      // required, must exist and be active
    "amount_kobo":           100000  // required, must be within plan's min/max range
}

HTTP 201
{
    "status": true,
    "message": "Fixed deposit booked successfully.",
    "data": {
        "reference": "fd_abc123",
        "principal_kobo": 100000,
        "maturity_date": "2026-05-31",
        "total_at_maturity_ngn": 1007.90
    }
}

deposit — fixed deposit ID

HTTP 200 { "status": true, "message": "Payout processed." }

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 1, "name": "Office Ajo", "code": "ABCD1234",
            "contribution_kobo": 1000000, "frequency": "monthly",
            "total_slots": 5, "status": "active",
            "creator": { "id": 12, "first_name": "Adewale", ... },
            "active_members": [ { "user_id": 12, "slot_position": 1, ... } ],
            "cycles": [ { "cycle_number": 1, "status": "pending", "due_date": "2026-06-01" } ]
        }
    ]
}

{
    "name":               "Office Ajo",       // required, max 100
    "contribution_kobo":  1000000,             // required, min 100 (= ₦10)
    "frequency":          "monthly",           // required: weekly | biweekly | monthly
    "total_slots":        5,                   // required, 2–50
    "start_date":         "2026-06-01",        // required, must be after today
    "description":        "Our office group"   // optional, max 500
}

HTTP 201
{
    "status": true,
    "message": "Ajo group created. Share code: ABCD1234",
    "data": { "id": 1, "code": "ABCD1234", "status": "pending", ... }
}

{ "code": "ABCD1234" }  // required, case-insensitive

HTTP 200
{
    "status": true,
    "message": "Joined group successfully.",
    "data": { "id": 1, "status": "active", "members": [ ... ] }
}

HTTP 422  (group full / already a member / not accepting)
{ "status": false, "error": "Group is full." }

cycle — AjoCycle ID (obtained from group cycles list)

HTTP 200 { "status": true, "message": "Contribution recorded." }
HTTP 422 { "error": "You have already contributed to this cycle." }

{
    "type":            "fixed",    // required: fixed | percentage
    "category":        "food",     // required: general | food | medical | transport | education | utilities | shopping
                                    // — enforced against the order category a store declares at checkout redemption,
                                    // see the "Every voucher has a category" note above.
    "amount_kobo":     1500000,    // required if type=fixed (₦15,000)
    "percentage":      20,         // required if type=percentage (1–100)
    "max_amount_kobo": 500000,     // required if type=percentage — the per-use cap, funded up front as cap × total_uses
    "total_uses":      50,         // required, min 1
    "expires_at":      "2026-12-31 23:59:59", // optional, must be future
    "description":     "Groceries welcome bonus",  // optional, max 255
    "merchant_name":   "Essential Store",      // optional — where this credit is meant to be spent
    "merchant_url":    "https://store.example.com", // optional
    "merchant_email":  "billing@store.example.com"  // optional — must belong to an existing Essential Wallet
                                                     // account. Required for this voucher to be usable in
                                                     // mode=checkout; see the eStore integration checklist above.
}

HTTP 201
{
    "status": true,
    "message": "Voucher created.",
    "data": {
        "id": 7, "code": "71TCYMGVMB",
        "type": "fixed", "category": "food", "amount_kobo": 1500000,
        "total_uses": 50, "used_count": 0,
        "status": "active", "expires_at": "2026-12-31T23:59:59.000000Z",
        "merchant_name": "Essential Store", "merchant_url": "https://store.example.com",
        "merchant_user_id": 42
    }
}

HTTP 422 { "errors": { "category": ["The selected category is invalid."] } }

HTTP 422 { "error": "Insufficient wallet balance to fund this voucher. You need ₦75,000.00 to cover all 50 use(s)." }
HTTP 422 { "error": "No Essential Wallet account found for that merchant email — they need to sign up first." }

{
    "code":            "71TCYMGVMB",  // required, case-insensitive
    "cart_kobo":       2000000,       // required for percentage vouchers, and always required for mode=checkout.
                                       // Whatever the caller sends is trusted as-is to compute the payout — it is
                                       // NOT an order ID and is never verified against a real cart anywhere.
    "mode":            "checkout",    // optional: wallet (default) | checkout
    "category":        "food",        // required if mode=checkout — what this order is actually for. Rejected with
                                       // 422 if it doesn't match the voucher's own category. Not used in mode=wallet.
    "order_reference": "ORDER-8841"   // required only if mode=checkout — your own order id, for your reconciliation
}

HTTP 200 (mode=wallet)
{
    "status": true,
    "message": "Voucher redeemed! ₦15,000.00 credited to your wallet. Intended for food spending. Spend it at Essential Store.",
    "data": {
        "mode": "wallet",
        "amount_credited_kobo": 1500000,
        "category": "food",
        "merchant_name": "Essential Store",
        "merchant_url": "https://store.example.com"
    }
}

HTTP 200 (mode=checkout)
{
    "status": true,
    "message": "Voucher reserved. Charge Paystack ₦20,000.00 and confirm once payment succeeds.",
    "data": {
        "mode": "checkout",
        "redemption_reference": "vch_ab12cd34ef56",
        "discount_kobo": 500000,
        "amount_to_charge_kobo": 2000000,
        "order_reference": "ORDER-8841",
        "expires_at": "2026-08-26T16:17:00+00:00"
    }
}

HTTP 422
{ "error": "You have already used this voucher." }
{ "error": "This voucher is invalid or has expired." }
{ "error": "You cannot redeem a voucher you created." }
{ "error": "This voucher isn't set up for checkout redemption." }
{ "error": "This voucher is only valid for food purchases, not medical." }  // category mismatch, mode=checkout only
{ "error": "cart_kobo is required for checkout-mode redemption." }
{ "error": "Voucher has no value for this transaction." }

reference — the redemption_reference returned by /vouchers/redeem

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,
        "confirmed_at": "2026-08-26T15:52:11+00:00"
    }
}

HTTP 404 { "error": "Reservation not found." }
HTTP 422 { "error": "This reservation was already released." }
HTTP 422 { "error": "This reservation has expired. Redeem the voucher again to get a new one." }

reference — the redemption_reference returned by /vouchers/redeem

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

HTTP 404 { "error": "Reservation not found." }
HTTP 422 { "error": "This reservation was already confirmed and settled; it can't be released." }

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 3,
            "amount_credited_kobo": 1500000,
            "reference": "vch_abc123",
            "redeemed_at": "2026-05-20T10:00:00.000000Z",
            "voucher": { "code": "71TCYMGVMB", "type": "fixed", "category": "food", ... }
        }
    ]
}

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 7, "code": "71TCYMGVMB",
            "type": "fixed", "category": "food", "amount_kobo": 1500000,
            "total_uses": 50, "used_count": 12,
            "status": "active", "expires_at": "2026-12-31T23:59:59.000000Z",
            "description": "Groceries welcome bonus"
        }
    ]
}

HTTP 200
{
    "status": true,
    "data": [
        { "project": "e-farm", "domain": "efarm.ng" },
        { "project": "e-medical", "domain": "emedicals.ng" }
    ]
}

voucher — the voucher id (not the code).

{
    "merchant_email": "store@example.com"   // required — an existing Essential Wallet account
}

HTTP 200
{
    "status": true,
    "message": "Merchant attached. This voucher can now be redeemed at checkout.",
    "data": { "id": 9, "code": "FQDW1B0HT2", "merchant_user_id": 388, … }
}

HTTP 403 { "status": false, "code": "forbidden", "message": "You can only manage vouchers you created." }
HTTP 422 { "status": false, "code": "voucher.already_used",
           "message": "This voucher has already been redeemed at least once and can no longer be reassigned…" }
HTTP 422 { "status": false, "code": "voucher.merchant_not_found",
           "message": "No Essential Wallet account found for that merchant email — they need to sign up first." }

reference — the redemption_reference of a confirmed redemption

{
    "reason": "Duplicate redemption — refunded the shopper"   // optional, recorded for support
}

HTTP 200
{
    "status": true,
    "message": "Redemption reversed. ₦5,000.00 returned to escrow; the voucher use has been reopened.",
    "data": {
        "redemption_reference": "vch_ab12cd34ef56",
        "status": "reversed",
        "amount_reversed_kobo": 500000,
        "reversed_at": "2026-10-13T10:12:00+00:00"
    }
}

HTTP 403 { "error": "Only an administrator can reverse a redemption." }
HTTP 404 { "error": "Redemption not found." }
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." }

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 3, "label": "my store — production", "key_prefix": "esk_OriC12b7",
            "publishable_key": "epk_9tQ4mWv2kZ7pR1sX8bY6nL3cH5jD0aF4gE2kM7v",
            "status": "active",                     // active | expired | revoked
            "last_used_at": "2026-10-15T16:08:11+00:00",
            "expires_at": null, "revoked_at": null,
            "created_at": "2026-10-01T09:00:00+00:00"
        }
    ]
}

id — the key id from GET /merchant/keys.

HTTP 200
{
    "status": true,
    "message": "Key rotated. The previous key stays valid for 24 hours.",
    "data": {
        "token":           "esk_NEWC12b7AKrhQJtu7J6pcQN32YVJjkFWWo6PSShE",  // new secret — store now
        "publishable_key": "epk_NEW4mWv2kZ7pR1sX8bY6nL3cH5jD0aF4gE2kM7v",
        "key": { "id": 3, "label": "my store — production", "key_prefix": "esk_NEWC12b7", "status": "active" },
        "previous_key_expires_at": "2026-10-16T16:08:11+00:00"              // old still works until here
    }
}

HTTP 422 { "status": false, "code": "merchant.key_revoked", "message": "A revoked key cannot be rotated." }
HTTP 404 { "status": false, "code": "merchant.key_not_found", "message": "API key not found." }

id — the key id from GET /merchant/keys.

HTTP 200
{
    "status": true,
    "message": "API key revoked.",
    "data": { "id": 3, "label": "my store — production", "status": "revoked", "revoked_at": "2026-10-15T16:10:00+00:00" }
}

HTTP 404 { "status": false, "code": "merchant.key_not_found", "message": "API key not found." }

code — the voucher code. Optional query string: ?cart_kobo=2500000 to get a discount preview for that cart total.

HTTP 200
{
    "status": true,
    "data": {
        "code": "FOOD2026",
        "type": "fixed",
        "category": "food",
        "status": "active",
        "valid": true,
        "reason": null,
        "amount_kobo": 500000,
        "percentage": null,
        "max_amount_kobo": null,
        "preview_value_kobo": 500000,
        "total_uses": 20,
        "used_count": 8,
        "uses_remaining": 12,
        "created_at": "2026-06-01T09:00:00+00:00",
        "expires_at": "2026-12-31T23:59:59+00:00",
        "description": "Groceries welcome bonus",
        "merchant_name": "Essential Store",
        "merchant_url": "https://store.example.com"
    }
}

// A voucher that exists but is exhausted/expired/paused still returns 200 — check "valid" and "reason":
{ "data": { "valid": false, "reason": "Voucher has no uses remaining.", ... } }

HTTP 401 { "error": "Missing or malformed merchant API key." }
HTTP 401 { "error": "Invalid or revoked merchant API key." }
HTTP 404 { "error": "Voucher not found." }

reference — the redemption_reference from /vouchers/redeem (mode=checkout)

HTTP 200
{
    "status": true,
    "data": {
        "reference": "vch_ab12cd34ef56",
        "status": "confirmed",
        "order_reference": "ORDER-8841",
        "amount_credited_kobo": 500000,
        "expires_at": "2026-08-26T16:17:00+00:00",
        "confirmed_at": "2026-08-26T15:52:11+00:00",
        "released_at": null,
        "reversed_at": null,
        "reversal_reason": null,
        "voucher": { "code": "FOOD2026", "category": "food" }
    }
}

HTTP 404 { "error": "Redemption not found." }   // unknown reference, wrong mode, or belongs to a different merchant

code — the voucher code

{
    "phone": "08012345678"   // required — the phone number on the shopper's Essential Wallet account
}

HTTP 200
{
    "status": true,
    "message": "A verification code has been sent to that number.",
    "data": {
        "otp_reference": "votp_jpS6iEBtwVYWV6cnVAcM4evg",
        "expires_at": "2026-08-31T19:57:22+00:00"
    }
}

HTTP 422 { "error": "This voucher is invalid or has expired." }
HTTP 422 { "error": "This voucher isn't set up for checkout redemption." }   // no merchant configured on the voucher
HTTP 422 { "error": "Enter a valid phone number." }
HTTP 422 { "error": "No Essential Wallet account found for that phone number." }
HTTP 422 { "error": "You cannot redeem a voucher you created." }
HTTP 422 { "error": "You have already used this voucher." }
HTTP 429 { "error": "Too many verification codes requested for this number. Try again later." }
HTTP 502 { "error": "Could not send the verification code. Try again shortly." }   // SMS provider failure

{
    "otp_reference":   "votp_jpS6iEBtwVYWV6cnVAcM4evg",  // required — from request-otp
    "otp":             "482913",       // required — the code the shopper received by SMS
    "cart_kobo":       2000000,        // required — trusted as-is to compute the payout, not verified against a real cart
    "category":        "food",         // required — what this order is actually for. Rejected with 422 if it
                                        // doesn't match the voucher's own category.
    "order_reference": "ORDER-8841"    // required — your own order id, for your reconciliation
}

HTTP 200
{
    "status": true,
    "message": "Voucher reserved. Charge Paystack ₦20,000.00 and confirm once payment succeeds.",
    "data": {
        "mode": "checkout",
        "redemption_reference": "vch_ab12cd34ef56",
        "discount_kobo": 500000,
        "amount_to_charge_kobo": 2000000,
        "order_reference": "ORDER-8841",
        "expires_at": "2026-08-26T16:17:00+00:00"
    }
}

HTTP 422 { "error": "This verification code has expired or is invalid. Request a new one." }
HTTP 422 { "error": "Incorrect verification code." }
HTTP 422 { "error": "This voucher is invalid or has expired." }
HTTP 422 { "error": "You cannot redeem a voucher you created." }
HTTP 422 { "error": "You have already used this voucher." }
HTTP 422 { "error": "This voucher is only valid for food purchases, not medical." }  // category mismatch
HTTP 422 { "error": "Voucher has no value for this transaction." }

reference — the redemption_reference returned by /merchant/vouchers/redeem

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,
        "confirmed_at": "2026-08-26T15:52:11+00:00"
    }
}

HTTP 404 { "error": "Reservation not found." }
HTTP 422 { "error": "This reservation was already released." }
HTTP 422 { "error": "This reservation has expired. Redeem the voucher again to get a new one." }

reference — the redemption_reference returned by /merchant/vouchers/redeem

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

HTTP 404 { "error": "Reservation not found." }
HTTP 422 { "error": "This reservation was already confirmed and settled; it can't be released." }

HTTP 200
{
    "status": true,
    "data": [
        {
            "code": "FOOD2026", "type": "fixed", "category": "food",
            "status": "active", "valid": true,
            "amount_kobo": 500000, "percentage": null, "max_amount_kobo": null,
            "total_uses": 20, "used_count": 8, "uses_remaining": 12,
            "created_at": "2026-06-01T09:00:00+00:00",
            "expires_at": "2026-12-31T23:59:59+00:00",
            "description": "Groceries welcome bonus", "merchant_name": "Essential Store"
        }
    ],
    "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

{
    "type":            "fixed",      // fixed | percentage (required)
    "category":        "food",       // general|food|medical|transport|education|utilities|shopping
    "amount_kobo":     500000,       // required when type=fixed
    "percentage":      null,         // required when type=percentage (1–100)
    "max_amount_kobo": null,         // required when type=percentage (per-use cap)
    "total_uses":      20,           // required, 1–1000
    "expires_at":      "2026-12-31T23:59:59Z",   // optional, must be future
    "description":     "Groceries welcome bonus", // optional
    "merchant_name":   "Essential Store",         // optional
    "merchant_url":    null          // optional, must be an Essential Group platform
}

HTTP 201
{
    "status": true,
    "message": "Voucher created.",
    "data": {
        "code": "FOOD2026", "type": "fixed", "category": "food",
        "status": "active", "valid": true,
        "total_uses": 20, "used_count": 0, "uses_remaining": 20, ...
    }
}

HTTP 422 { "status": false, "code": "wallet.insufficient_funds", "message": "…" }
HTTP 422 { "status": false, "code": "voucher.merchant_url_invalid", "message": "…" }

code — the voucher code

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

HTTP 404 { "error": "Voucher not found." }
HTTP 422 { "error": "Only an active voucher can be paused." }

code — the voucher code

HTTP 200
{
    "status": true,
    "message": "Voucher resumed.",
    "data": { "code": "FOOD2026", "status": "active", "valid": true, ... }
}

HTTP 404 { "error": "Voucher not found." }
HTTP 422 { "error": "Only a paused voucher can be resumed." }
HTTP 422 { "error": "This voucher has expired and cannot be resumed." }

HTTP 200
{
    "status": true,
    "data": [
        {
            "reference": "vch_ab12cd34ef56", "status": "confirmed", "mode": "checkout",
            "order_reference": "ORDER-8841", "amount_credited_kobo": 500000,
            "redeemed_at": "2026-08-26T15:51:00+00:00", "confirmed_at": "2026-08-26T15:52:11+00:00",
            "released_at": null, "reversed_at": null, "reversal_reason": null,
            "voucher": { "code": "FOOD2026", "category": "food" }
        }
    ],
    "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

reference — the redemption_reference of a confirmed checkout 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", "reversed_at": "2026-10-13T10:12:00+00:00", ... }
}

HTTP 404 { "error": "Redemption not found." }
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." }

{
    "merchant_email": "host@example.com",   // required — the seller's existing wallet account
    "label":          "estay — host #1"      // required, min 2 — shown in the operator's key list
}

HTTP 201
{
    "status": true,
    "message": "Merchant key created. Copy the secret now — it will not be shown again.",
    "data": {
        "token":           "esk_OriC12b7AKrhQJtu7J6pcQN32YVJjkFWWo6PSShE",  // esk_… — store server-side, never in a page
        "publishable_key": "epk_9tQ4mWv2kZ7pR1sX8bY6nL3cH5jD0aF4gE2kM7v",  // epk_… — safe to embed in the widget
        "key": {
            "id": 3, "merchant_user_id": 388,
            "label": "estay — host #1", "key_prefix": "esk_OriC12b7",
            "publishable_key": "epk_9tQ4mWv2kZ7pR1sX8bY6nL3cH5jD0aF4gE2kM7v"
        }
    }
}

HTTP 422 { "status": false, "code": "platform.merchant_not_found",
           "message": "No Essential Wallet account exists for that email — they need to sign up first." }
HTTP 401 { "status": false, "code": "platform.unauthorized", "message": "Invalid platform service token." }
HTTP 503 { "status": false, "code": "platform.disabled",     "message": "The platform service API is not enabled." }

id — the key id returned when it was minted.

HTTP 200
{
    "status": true,
    "message": "Merchant key revoked. Its secret and widget key no longer authenticate.",
    "data": { "id": 3, "revoked": true }
}

HTTP 404 { "status": false, "code": "platform.key_not_found", "message": "No merchant key exists with that id." }

HTTP 200
{
    "status": true,
    "data": {
        "kyc_status": "unverified",  // unverified | verified
        "verifications": [
            {
                "id": 4, "type": "nin", "id_number_last4": "8901",
                "status": "failed", "message": "No match found.",
                "created_at": "2026-08-20T09:12:00.000000Z"
            }
        ]
    }
}

{
    "type":      "nin",           // required: nin | bvn
    "id_number": "12345678901"    // required, exactly 11 digits
}

HTTP 200 (passed)
{
    "status": true,
    "message": "Identity verified successfully.",
    "data": { "kyc_status": "verified", "verification": { "type": "nin", "status": "passed", "matched_name": "Jane Doe", "confidence": 95 } }
}

HTTP 200 (failed — still HTTP 200, check data.verification.status)
{
    "status": true,
    "message": "We could not verify this NIN.",
    "data": { "kyc_status": "unverified", "verification": { "status": "failed" } }
}

HTTP 422 { "status": false, "error": "Your identity is already verified." }
HTTP 502 { "status": false, "error": "KYC verification is not configured on this server." }

HTTP 200
{
    "status": true,
    "data": {
        "url": "https://store.example.com/wallet/webhook",  // null until configured
        "configured": true,
        "secret_issued": true,
        "events": ["reservation.created","reservation.confirmed","reservation.released","reservation.expired"],
        "updated_at": "2026-10-15T16:08:00+00:00"
    }
}

{
    "url": "https://store.example.com/wallet/webhook",  // required
    "regenerate_secret": false                            // optional — true rotates the signing secret
}

HTTP 200 (secret shown only when first set or regenerated)
{
    "status": true,
    "message": "Webhook endpoint saved. Store the signing secret now — it is shown only once.",
    "data": {
        "url": "https://store.example.com/wallet/webhook",
        "events": ["reservation.created","reservation.confirmed","reservation.released","reservation.expired"],
        "signing_secret": "whsec_9tQ4mWv2kZ7pR1sX8bY6nL3cH5jD0aF4gE2kM7v"
    }
}

HTTP 200
{
    "status": true,
    "data": [
        {
            "id": 41, "event": "reservation.confirmed", "status": "success",
            "attempts": 1, "response_code": 200, "error": null,
            "delivered_at": "2026-10-15T16:08:11+00:00", "created_at": "2026-10-15T16:08:11+00:00"
        }
    ],
    "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

// Handled events:

// 1a. charge.success  — incoming DVA deposit
{
    "event": "charge.success",
    "data": {
        "channel": "dedicated_nuban",
        "amount": 1500000,
        "metadata": { "receiver_account_number": "9876543210" }
    }
}

// 1b. charge.success — Fund Wallet checkout (see the "Fund Wallet" section above).
//     Distinguished from 1a by metadata.purpose, not by channel — a Fund Wallet
//     charge can land on any Paystack channel (card, bank, ussd, ...).
{
    "event": "charge.success",
    "data": {
        "channel": "card",
        "amount": 200000,
        "reference": "wfund_9k2j7h1qz3xa8y0b5c4d",
        "metadata": { "purpose": "wallet_funding", "user_id": 42 }
    }
}

// 2. transfer.success  — outgoing transfer confirmed
{
    "event": "transfer.success",
    "data": {
        "reference": "trx_abc123def456ghij",
        "amount": 30000
    }
}

// 3. transfer.failed  — outgoing transfer failed
// 4. transfer.reversed — outgoing transfer reversed

HTTP 200 { "status": "success" }
HTTP 403 { "error": "Invalid signature" }   // bad or missing signature