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"
        }
    ]
}

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." }

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

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"
}

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

HTTP 200 { "status": true, "message": "OTP requirement for transfers has been disabled" }

HTTP 200 { "status": true, "message": "OTP requirement for transfers has been enabled" }

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
    "amount_kobo":     1500000,    // required if type=fixed (₦15,000)
    "percentage":      20,         // required if type=percentage (1–100)
    "max_amount_kobo": 500000,     // optional max cap for percentage vouchers
    "total_uses":      50,         // required, min 1
    "expires_at":      "2026-12-31 23:59:59", // optional, must be future
    "description":     "Food voucher"          // optional, max 255
}

HTTP 201
{
    "status": true,
    "message": "Voucher created.",
    "data": {
        "id": 7, "code": "71TCYMGVMB",
        "type": "fixed", "amount_kobo": 1500000,
        "total_uses": 50, "used_count": 0,
        "status": "active", "expires_at": "2026-12-31T23:59:59.000000Z"
    }
}

{
    "code":       "71TCYMGVMB",  // required, case-insensitive
    "cart_kobo":  2000000        // optional — required for percentage vouchers to calculate value
}

HTTP 200
{
    "status": true,
    "message": "Voucher redeemed! ₦15,000.00 credited to your wallet.",
    "data": { "amount_credited_kobo": 1500000 }
}

HTTP 422
{ "error": "You have already used this voucher." }
{ "error": "This voucher is invalid or has expired." }

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", ... }
        }
    ]
}

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

// Handled events:

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

// 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