{ "openapi": "3.1.0", "info": { "title": "mySubwallet API", "version": "1.0.0", "description": "Buy data, airtime, cable, electricity, exam pins, bulk SMS, betting, eSIM, flights, recharge/data cards and more, funded from your wallet. Test everything safely with your sandbox (sk_test_) key — no wallet charge." }, "servers": [ { "url": "https://api.mysubwallet.ng", "description": "Production (live — charges your wallet)" }, { "url": "https://sandbox.mysubwallet.ng", "description": "Sandbox (test — simulated, no wallet charge)" } ], "security": [ { "TokenAuth": [] } ], "tags": [ { "name": "Purchases" }, { "name": "Verification" }, { "name": "Betting" }, { "name": "eSIM" }, { "name": "Flights" }, { "name": "Wallet" }, { "name": "Catalogs" }, { "name": "Account" } ], "paths": { "/api/data": { "post": { "summary": "Buy Data", "tags": [ "Purchases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "network", "phone", "data_plan", "request-id" ], "properties": { "network": { "type": "integer", "description": "1 MTN, 2 Airtel, 3 Glo, 4 9mobile.", "example": 1 }, "phone": { "type": "string", "example": "2347013397088" }, "data_plan": { "type": "integer", "description": "Plan ID from GET /api/data-plan.", "example": 19 }, "bypass": { "type": "boolean", "default": false }, "request-id": { "type": "string", "example": "Data_12345678900" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "network": "MTN", "request-id": "Data_12345678900", "amount": "100", "dataplan": "500MB", "status": "success", "message": "You have gifted 500MB to 2347013397088.", "newbal": 110225, "system": "API" } } } } } } }, "/api/topup": { "post": { "summary": "Buy Airtime", "tags": [ "Purchases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "network", "phone", "plan_type", "amount", "request-id" ], "properties": { "network": { "type": "integer", "example": 1 }, "phone": { "type": "string", "example": "2347013397088" }, "plan_type": { "type": "string", "enum": [ "VTU", "SNS" ], "example": "VTU" }, "amount": { "type": "integer", "example": 100 }, "bypass": { "type": "boolean", "default": false }, "request-id": { "type": "string", "example": "Airtime_12345678900" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "network": "MTN", "amount": "100", "status": "success", "message": "Airtime delivered to 2347013397088.", "newbal": 110225, "system": "API" } } } } } } }, "/api/cable/cable-validation": { "get": { "summary": "Verify Smartcard", "tags": [ "Verification" ], "description": "Validate an IUC / SmartCard number before a cable purchase. Returns the customer name.", "parameters": [ { "name": "cable", "in": "query", "required": true, "schema": { "type": "integer", "example": 2 }, "description": "Cable provider ID (from GET /api/cable-providers)" }, { "name": "iuc", "in": "query", "required": true, "schema": { "type": "string", "example": "1234567890" }, "description": "IUC / SmartCard number" } ], "responses": { "200": { "description": "Customer", "content": { "application/json": { "example": { "status": "success", "name": "JOHN DOE" } } } } } } }, "/api/cable": { "post": { "summary": "Cable Subscription", "tags": [ "Purchases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cable", "cable_plan", "iuc", "bypass" ], "properties": { "cable": { "type": "integer", "description": "Cable provider ID (from GET /api/cable-plans)", "example": 1 }, "cable_plan": { "type": "integer", "description": "Cable subscription plan ID", "example": 12 }, "iuc": { "type": "string", "description": "IUC / SmartCard number", "example": "1234567890" }, "bypass": { "type": "integer", "enum": [ 0, 1 ], "description": "0 = validate IUC first; 1 = skip validation (only after a successful verify call)", "example": 0 }, "request-id": { "type": "string", "description": "Your unique reference (idempotency key). Reuse with GET /api/requery/{reference}. Optional - one is generated if omitted.", "example": "Cable_1234567890" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "status": "success", "message": "DStv Padi renewed on 1234567890.", "newbal": 109925, "system": "API" } } } } } } }, "/api/bill/bill-validation": { "get": { "summary": "Verify Meter", "tags": [ "Verification" ], "description": "Validate a meter number before an electricity purchase. Returns the customer name (and address for postpaid).", "parameters": [ { "name": "disco", "in": "query", "required": true, "schema": { "type": "integer", "example": 1 }, "description": "Disco plan_id (from GET /api/discos)" }, { "name": "meter_number", "in": "query", "required": true, "schema": { "type": "string", "example": "12345678901" }, "description": "Customer's meter number" }, { "name": "meter_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "prepaid", "postpaid" ], "example": "prepaid" }, "description": "prepaid or postpaid" } ], "responses": { "200": { "description": "Customer", "content": { "application/json": { "example": { "status": "success", "customer_name": "JOHN DOE", "customer_address": "12 Example Street, Lagos", "meter_number": "12345678901" } } } } } } }, "/api/bill": { "post": { "summary": "Pay Electricity Bill", "tags": [ "Purchases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "disco", "meter_type", "meter_number", "amount" ], "properties": { "disco": { "type": "integer", "description": "Disco plan_id (from GET /api/discos)", "example": 1 }, "meter_type": { "type": "string", "enum": [ "prepaid", "postpaid" ], "example": "prepaid" }, "meter_number": { "type": "string", "example": "12345678901" }, "amount": { "type": "integer", "description": "Amount in Naira", "example": 1000 }, "request-id": { "type": "string", "description": "Your unique reference (idempotency key). Reuse with GET /api/requery/{reference}. Optional - one is generated if omitted.", "example": "Bill_12345678900" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "status": "success", "message": "Recharge successful.", "token": "1234-5678-9012-3456-7890", "newbal": 109625, "system": "API" } } } } } } }, "/api/bulksms": { "post": { "summary": "Send Bulk SMS", "tags": [ "Purchases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sender", "number", "message", "request-id" ], "properties": { "sender": { "type": "string", "maxLength": 11, "example": "mySubwallet" }, "number": { "type": "string", "example": "2347013397088,2348011112222" }, "message": { "type": "string", "example": "Hello from mySubwallet!" }, "request-id": { "type": "string", "example": "BULKSMS_1234567890" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "status": "success", "message": "Message sent.", "units": 2, "newbal": 109600, "system": "API" } } } } } } }, "/api/exam": { "post": { "summary": "Buy Exam Pins", "tags": [ "Purchases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "exam", "quantity", "request-id" ], "properties": { "exam": { "type": "integer", "example": 1 }, "quantity": { "type": "integer", "example": 1 }, "request-id": { "type": "string", "example": "RESULTCHECKER_1234567890" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "status": "success", "message": "Pin purchased.", "pins": [ { "pin": "123456789012", "serial": "WRN123456789" } ], "newbal": 109200, "system": "API" } } } } } } }, "/api/verifybetting": { "post": { "summary": "Verify Betting Account", "tags": [ "Betting" ], "description": "Confirm a betting customer ID before funding.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "betting_id", "customer_id" ], "properties": { "betting_id": { "type": "string", "description": "Bookmaker plan ID (see Catalogs).", "example": "5" }, "customer_id": { "type": "string", "description": "The customer's betting account ID.", "example": "CUST12345" } } } } } }, "responses": { "200": { "description": "Account", "content": { "application/json": { "example": { "status": true, "data": { "customer_name": "JOHN DOE", "customer_id": "CUST12345" } } } } } } } }, "/api/fund/betting": { "post": { "summary": "Fund Betting Account", "tags": [ "Betting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "betting_id", "customer_id", "amount" ], "properties": { "betting_id": { "type": "string", "example": "5" }, "customer_id": { "type": "string", "example": "CUST12345" }, "amount": { "type": "number", "example": 1000 }, "request-id": { "type": "string", "example": "BETTING_1234567890" } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "status": "success", "message": "Bet9ja funded with ₦1,000 for CUST12345.", "newbal": 108200, "system": "API" } } } } } } }, "/api/cash": { "post": { "summary": "Airtime to Cash", "tags": [ "Wallet" ], "description": "Convert MTN/Airtel airtime to wallet cash via a 3-step Share-and-Sell flow (Tier 2+ KYC required).\n\n- **Step 1** `{step:1, network, phone}` — start; an OTP is sent and a verification `data` token is returned.\n- **Step 2** `{step:2, network, phone, otp, data}` — verify the OTP.\n- **Step 3** `{step:3, network, phone, data, share_pin, amount}` — complete; your wallet is credited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "step", "network", "phone" ], "properties": { "step": { "type": "integer", "enum": [ 1, 2, 3 ], "example": 1 }, "network": { "type": "integer", "description": "Network plan ID (MTN or Airtel only).", "example": 1 }, "phone": { "type": "string", "example": "2347013397088" }, "otp": { "type": "string", "description": "Step 2 — OTP received from the network.", "example": "123456" }, "data": { "type": "string", "description": "Steps 2 & 3 — verification token returned by the previous step." }, "share_pin": { "type": "string", "description": "Step 3 — your 4-digit network Share-and-Sell PIN.", "example": "1234" }, "amount": { "type": "number", "description": "Step 3 — airtime amount to convert.", "example": 1000 } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "example": { "status": "success", "message": "Airtime converted. Your wallet has been credited.", "newbal": 111000 } } } } } } }, "/api/esim/catalog/countries": { "get": { "summary": "List eSIM Countries", "tags": [ "eSIM" ], "responses": { "200": { "description": "Countries", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": 724, "name": "Spain", "country_code": "ES", "image_url": "https://flagcdn.com/h60/es.png" } ] } } } } } } }, "/api/esim/catalog/by-country/{id}": { "get": { "summary": "List eSIM Packages", "tags": [ "eSIM" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Country ID from List eSIM Countries.", "example": 724 }, { "name": "package_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DATA-ONLY", "DATA-VOICE-SMS" ] }, "description": "Filter by package type.", "example": "DATA-ONLY" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number (default 1).", "example": 1 } ], "responses": { "200": { "description": "Packages for the country.", "content": { "application/json": { "example": { "status": "success", "meta": { "total": 12, "perPage": 12, "currentPage": 1, "lastPage": 2 }, "data": [ { "id": "esim_abc", "name": "Spain 1GB - 7 Days", "data_quantity": 1, "data_unit": "GB", "package_validity": 7, "package_validity_unit": "Day", "price_ngn": 2500, "package_type": "DATA-ONLY" } ] } } } } }, "description": "Lists buyable eSIM packages for a country, priced in NGN (`price_ngn`). Paginated — pass `page` to fetch more. Use a package's `id` as `package_id` when calling Buy eSIM." } }, "/api/esim/buy": { "post": { "summary": "Buy eSIM", "tags": [ "eSIM" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "package_id", "package_type" ], "properties": { "package_id": { "type": "string", "example": "esim_abc" }, "package_type": { "type": "string", "enum": [ "DATA-ONLY", "DATA-VOICE-SMS" ], "example": "DATA-ONLY" } } } } } }, "responses": { "200": { "description": "The purchased eSIM.", "content": { "application/json": { "example": { "status": "success", "message": "eSIM ready. Install using the QR/link provided.", "data": { "id": 21, "transid": "ESIM_AB12CD34EF", "sim_applied": true, "iccid": "8932042000024889460", "universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$7230...", "activation_code": "LPA:1$rsp-eu.simlessly.com$7230...", "package_name": "Spain 1GB - 7 Days", "sold_price_ngn": 2500, "plan_status": 1, "provider": "esimaccess" } } } } }, "402": { "description": "Insufficient wallet balance.", "content": { "application/json": { "example": { "status": "fail", "message": "Insufficient balance. Required ₦2,500.00" } } } } }, "description": "Purchases an eSIM and charges your wallet. The response returns the provisioned eSIM directly — including its `id`, `iccid`, `universal_link` (the install link / QR payload) and `activation_code` — so you do not need to call My eSIMs afterwards. When the vendor provisions instantly, `sim_applied` is `true` and the link is ready; otherwise the eSIM is created in a provisioning state (`plan_status` 0) and the link fills in shortly — poll `GET /api/esim/my/{id}`." } }, "/api/esim/my": { "get": { "summary": "My eSIMs", "tags": [ "eSIM" ], "responses": { "200": { "description": "Your eSIMs (newest first).", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": 21, "package_name": "Spain 1GB - 7 Days", "package_type": "DATA-ONLY", "country_name": "Spain", "country_code": "ES", "data_quantity": "1.0000", "data_unit": "GB", "package_validity": 7, "package_validity_unit": "Day", "iccid": "8932042000024889460", "universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$7230...", "activation_code": "LPA:1$rsp-eu.simlessly.com$7230...", "plan_status": 1, "sim_applied": true, "is_topup": false, "parent_esim_id": null, "sold_price_ngn": 2500, "provider": "esimaccess", "transid": "ESIM_AB12CD34EF", "expires_at": "2026-07-01T09:01:16.000000Z", "created_at": "2026-06-24T09:01:16.000000Z" } ] } } } } }, "description": "Lists the eSIMs on **your account only** — scoped to your authenticated user, so you never see another reseller's eSIMs. Returns your most recent 50, newest first. `plan_status` is 1 once provisioned (install link ready), 0 while still provisioning. To fetch one eSIM, use Get eSIM by ID." } }, "/api/flight/search": { "get": { "summary": "Search Flights", "tags": [ "Flights" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "schema": { "type": "string" }, "example": "LOS" }, { "name": "destination", "in": "query", "required": true, "schema": { "type": "string" }, "example": "ABV" }, { "name": "departure_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-07-01" }, { "name": "return_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "children", "in": "query", "schema": { "type": "integer" } }, { "name": "infants", "in": "query", "schema": { "type": "integer" } }, { "name": "cabin", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "economy", "premium_economy", "business", "first" ] }, "example": "economy" } ], "responses": { "200": { "description": "Offers", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": "offer_123", "amount": 85000, "currency": "NGN", "outbound_stops": 0, "total_duration": 75 } ] } } } } } } }, "/api/flight/airports": { "get": { "summary": "Search Airports", "tags": [ "Flights" ], "parameters": [ { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Lagos" } ], "responses": { "200": { "description": "Airports", "content": { "application/json": { "example": { "status": "success", "data": [ { "city": "Lagos", "iata_code": "LOS", "name": "Murtala Muhammed International", "country": "Nigeria" } ] } } } } } } }, "/api/flight/book": { "post": { "summary": "Book Flight", "tags": [ "Flights" ], "description": "Confirm price, debit wallet and issue a ticket. Requires KYC. Auto-refunds on failure.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "flight_id", "passengers" ], "properties": { "flight_id": { "type": "string", "description": "Offer id from Search Flights.", "example": "offer_123" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "passenger_type": { "type": "string", "enum": [ "adult", "child", "infant" ] }, "title": { "type": "string", "enum": [ "mr", "mrs", "miss", "ms" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "dob": { "type": "string", "format": "date" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "email": { "type": "string" }, "phone_number": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Booking", "content": { "application/json": { "example": { "status": "success", "data": { "reference": "MSW123", "pnr": "ABC123", "status": "issued", "amount": 85000 } } } } } } } }, "/api/data-plan": { "get": { "summary": "List Data Plans", "tags": [ "Catalogs" ], "description": "Fetch every data plan with its plan_id, to use in POST /api/data.", "responses": { "200": { "description": "Plans", "content": { "application/json": { "example": { "status": "success", "plan": [ { "network": "GLO", "network_type": "GIFTING", "name": "750MB GIFTING = ₦194.00 1 Day Special", "plan_id": "19", "amount": "194" } ] } } } } } } }, "/api/networks": { "get": { "summary": "List Networks", "tags": [ "Catalogs" ], "description": "Network IDs (`plan_id`) used across the API.", "responses": { "200": { "description": "Networks", "content": { "application/json": { "example": { "status": "success", "network": [ { "network": "MTN", "plan_id": "1" }, { "network": "AIRTEL", "plan_id": "2" }, { "network": "GLO", "plan_id": "3" }, { "network": "9MOBILE", "plan_id": "4" } ] } } } } } } }, "/api/discos": { "get": { "summary": "List DISCOs", "tags": [ "Catalogs" ], "description": "Electricity distribution companies for the `disco` field in POST /api/bill.", "responses": { "200": { "description": "DISCOs", "content": { "application/json": { "example": { "status": "success", "bill": [ { "plan_id": "1", "disco_name": "Ikeja Electricity", "logo": "https://api.mysubwallet.ng/storage/logos/ikeja.jpeg" }, { "plan_id": "2", "disco_name": "Eko Electricity", "logo": "https://api.mysubwallet.ng/storage/logos/eko.jpeg" } ] } } } } } } }, "/api/cable-plans": { "get": { "summary": "List Cable Plans", "tags": [ "Catalogs" ], "description": "Cable plans and prices for POST /api/cable.", "responses": { "200": { "description": "Cable plans", "content": { "application/json": { "example": { "status": "success", "plan": [ { "cable_name": "DSTV", "plan_name": "DStv Padi", "plan_price": "4400.00", "plan_id": "1" }, { "cable_name": "GOTV", "plan_name": "GOtv Smallie", "plan_price": "1900.00", "plan_id": "20" } ] } } } } } } }, "/api/exam-bodies": { "get": { "summary": "List Exam Bodies", "tags": [ "Catalogs" ], "description": "Exam bodies and prices for the `exam` field in POST /api/exam.", "responses": { "200": { "description": "Exam bodies", "content": { "application/json": { "example": { "status": "success", "plan": [ { "exam_name": "WAEC", "plan_id": "1", "amount": "₦5,350.00" }, { "exam_name": "NECO", "plan_id": "2", "amount": "₦2,200.00" }, { "exam_name": "NABTEB", "plan_id": "3", "amount": "₦1,000.00" } ] } } } } } } }, "/api/balance": { "get": { "summary": "Check Balance", "tags": [ "Account" ], "description": "Returns the wallet balances for the authenticated account.", "responses": { "200": { "description": "Balances", "content": { "application/json": { "example": { "status": "success", "username": "johndoe", "balance": 15000.5, "bonus_balance": 0, "airtime_to_cash_balance": 0, "currency": "NGN" } } } } } } }, "/api/esim/catalog/package/{id}": { "get": { "summary": "Get eSIM Package", "tags": [ "eSIM" ], "description": "Fetches a single eSIM package by id, with its current NGN price. Handy to re-confirm the price right before Buy eSIM.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package id from List eSIM Packages.", "example": "esim_abc" } ], "responses": { "200": { "description": "The package.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "esim_abc", "name": "Spain 1GB - 7 Days", "data_quantity": 1, "data_unit": "GB", "package_validity": 7, "package_validity_unit": "Day", "price_ngn": 2500, "package_type": "DATA-ONLY" } } } } }, "404": { "description": "Package not available.", "content": { "application/json": { "example": { "status": "fail", "message": "Package not available." } } } } } } }, "/api/esim/my/{id}": { "get": { "summary": "Get eSIM by ID", "tags": [ "eSIM" ], "description": "Fetches a single eSIM by its `id`, scoped to your account. Use it to poll for the install link after buying, or to confirm provisioning status. Returns 404 if the `id` is not on your account.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The eSIM `id` from Buy eSIM or My eSIMs.", "example": 21 } ], "responses": { "200": { "description": "The eSIM.", "content": { "application/json": { "example": { "status": "success", "data": { "id": 21, "package_name": "Spain 1GB - 7 Days", "package_type": "DATA-ONLY", "country_name": "Spain", "country_code": "ES", "data_quantity": "1.0000", "data_unit": "GB", "package_validity": 7, "package_validity_unit": "Day", "iccid": "8932042000024889460", "universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$7230...", "activation_code": "LPA:1$rsp-eu.simlessly.com$7230...", "plan_status": 1, "sim_applied": true, "is_topup": false, "parent_esim_id": null, "sold_price_ngn": 2500, "provider": "esimaccess", "transid": "ESIM_AB12CD34EF", "expires_at": "2026-07-01T09:01:16.000000Z", "created_at": "2026-06-24T09:01:16.000000Z" } } } } }, "404": { "description": "Not found on your account.", "content": { "application/json": { "example": { "status": "fail", "message": "eSIM not found." } } } } } } }, "/api/esim/my/{id}/usage": { "get": { "summary": "eSIM Data Usage", "tags": [ "eSIM" ], "description": "Live data usage for one of your eSIMs — how much of the bundle is used and how much remains. Returns 404 if the eSIM is not yours or not yet provisioned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The eSIM `id`.", "example": 21 } ], "responses": { "200": { "description": "Usage snapshot.", "content": { "application/json": { "example": { "status": "success", "data": { "initial_data_quantity": 1, "initial_data_unit": "GB", "rem_data_quantity": 0.62, "rem_data_unit": "GB", "used_bytes": 408021900, "total_bytes": 1073741824, "last_updated_at": "2026-06-25T18:40:00.000000Z" } } } } } } } }, "/api/esim/my/{id}/topup-plans": { "get": { "summary": "Get eSIM Top-up Plans", "tags": [ "eSIM" ], "description": "Lists the top-up bundles available for one of your existing eSIMs (priced in NGN). Pass a returned `id` as `package_id` to Top up an eSIM. Paginated.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The eSIM `id` to top up.", "example": 21 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number (default 1).", "example": 1 } ], "responses": { "200": { "description": "Available top-up plans.", "content": { "application/json": { "example": { "status": "success", "meta": { "total": 3, "perPage": 3, "currentPage": 1, "lastPage": 1 }, "data": [ { "id": "esim_topup_xyz", "name": "Spain 3GB - 30 Days", "data_quantity": 3, "data_unit": "GB", "package_validity": 30, "package_validity_unit": "Day", "price_ngn": 5200, "package_type": "DATA-ONLY" } ] } } } } } } }, "/api/esim/topup": { "post": { "summary": "Top up an eSIM", "tags": [ "eSIM" ], "description": "Adds a new data bundle to an eSIM you already own, keeping the same `iccid`. Routed through the provider that issued the original eSIM. Use Get eSIM Top-up Plans to find an eligible `package_id`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parent_esim_id", "package_id", "package_type" ], "properties": { "parent_esim_id": { "type": "integer", "description": "`id` of the existing eSIM to top up (from My eSIMs).", "example": 21 }, "package_id": { "type": "string", "description": "Top-up package id (from Get eSIM Top-up Plans).", "example": "esim_topup_xyz" }, "package_type": { "type": "string", "enum": [ "DATA-ONLY", "DATA-VOICE-SMS" ], "example": "DATA-ONLY" } } } } } }, "responses": { "200": { "description": "The topped-up eSIM.", "content": { "application/json": { "example": { "status": "success", "message": "eSIM ready. Install using the QR/link provided.", "data": { "id": 22, "transid": "ESIM_TP90KL12MN", "sim_applied": true, "iccid": "8932042000024889460", "package_name": "Spain 3GB - 30 Days", "sold_price_ngn": 5200, "plan_status": 1, "provider": "esimaccess" } } } } } } } }, "/api/flight/bookings": { "get": { "summary": "My Flight Bookings", "tags": [ "Flights" ], "description": "Lists the flight bookings on **your account only** — scoped to your authenticated user, newest first (up to 50). Use a booking's `reference` to fetch its details, download the ticket, or cancel it. `status` is typically `pending`, `issued`, `cancelled` or `failed`.", "responses": { "200": { "description": "Your bookings (newest first).", "content": { "application/json": { "example": { "status": "success", "data": [ { "reference": "FB-7K2M9QZ", "pnr": "A1B2C3", "status": "issued", "trip_type": "one_way", "origin": "LOS", "destination": "ABV", "departure_date": "2026-07-10", "return_date": null, "cabin": "economy", "passengers": [ { "title": "Mr", "first_name": "John", "last_name": "Doe", "type": "adult" } ], "itinerary": [ { "airline": "Air Peace", "flight_number": "P47190", "departure": { "airport": "LOS", "time": "2026-07-10T07:30:00" }, "arrival": { "airport": "ABV", "time": "2026-07-10T08:45:00" }, "duration": "1h 15m", "cabin": "economy" } ], "tickets": [ { "passenger": "John Doe", "ticket_number": "0632190874321" } ], "amount": 78500, "currency": "NGN", "addons_fee": 0, "whatsapp_number": "2348012345678", "reminder_call": false, "email_delivery": "john@example.com", "expires_at": "2026-07-10T06:00:00+01:00", "my_trans_id": "FLT_AB12CD34", "created_at": "2026-06-25T20:00:00+01:00" } ] } } } } } } }, "/api/flight/booking/{reference}": { "get": { "summary": "Get Flight Booking", "tags": [ "Flights" ], "description": "Fetches a single flight booking by its `reference`, scoped to your account — including PNR, full itinerary and issued ticket numbers. Returns 404 if the reference isn't on your account.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking reference from Book Flight or My Flight Bookings.", "example": "FB-7K2M9QZ" } ], "responses": { "200": { "description": "The booking.", "content": { "application/json": { "example": { "status": "success", "data": { "reference": "FB-7K2M9QZ", "pnr": "A1B2C3", "status": "issued", "trip_type": "one_way", "origin": "LOS", "destination": "ABV", "departure_date": "2026-07-10", "return_date": null, "cabin": "economy", "passengers": [ { "title": "Mr", "first_name": "John", "last_name": "Doe", "type": "adult" } ], "itinerary": [ { "airline": "Air Peace", "flight_number": "P47190", "departure": { "airport": "LOS", "time": "2026-07-10T07:30:00" }, "arrival": { "airport": "ABV", "time": "2026-07-10T08:45:00" }, "duration": "1h 15m", "cabin": "economy" } ], "tickets": [ { "passenger": "John Doe", "ticket_number": "0632190874321" } ], "amount": 78500, "currency": "NGN", "addons_fee": 0, "whatsapp_number": "2348012345678", "reminder_call": false, "email_delivery": "john@example.com", "expires_at": "2026-07-10T06:00:00+01:00", "my_trans_id": "FLT_AB12CD34", "created_at": "2026-06-25T20:00:00+01:00" } } } } }, "404": { "description": "Not found on your account.", "content": { "application/json": { "example": { "status": "error", "message": "Booking not found." } } } } } } }, "/api/flight/booking/{reference}/ticket": { "get": { "summary": "Download Ticket", "tags": [ "Flights" ], "description": "Returns the e-ticket for a booking as a PDF file (`application/pdf`). Available once the booking is issued.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking reference.", "example": "FB-7K2M9QZ" } ], "responses": { "200": { "description": "The ticket PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not found on your account.", "content": { "application/json": { "example": { "status": "error", "message": "Booking not found." } } } } } } }, "/api/flight/booking/{reference}/cancel": { "post": { "summary": "Cancel Flight Booking", "tags": [ "Flights" ], "description": "Cancels a pending booking and refunds your wallet. Bookings already **issued** can't be cancelled here — contact support. Already-cancelled bookings return their current state.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking reference to cancel.", "example": "FB-7K2M9QZ" } ], "responses": { "200": { "description": "The cancelled booking.", "content": { "application/json": { "example": { "status": "success", "data": { "reference": "FB-7K2M9QZ", "pnr": "A1B2C3", "status": "cancelled", "trip_type": "one_way", "origin": "LOS", "destination": "ABV", "departure_date": "2026-07-10", "return_date": null, "cabin": "economy", "passengers": [ { "title": "Mr", "first_name": "John", "last_name": "Doe", "type": "adult" } ], "itinerary": [ { "airline": "Air Peace", "flight_number": "P47190", "departure": { "airport": "LOS", "time": "2026-07-10T07:30:00" }, "arrival": { "airport": "ABV", "time": "2026-07-10T08:45:00" }, "duration": "1h 15m", "cabin": "economy" } ], "tickets": [ { "passenger": "John Doe", "ticket_number": "0632190874321" } ], "amount": 78500, "currency": "NGN", "addons_fee": 0, "whatsapp_number": "2348012345678", "reminder_call": false, "email_delivery": "john@example.com", "expires_at": "2026-07-10T06:00:00+01:00", "my_trans_id": "FLT_AB12CD34", "created_at": "2026-06-25T20:00:00+01:00" } } } } }, "409": { "description": "Already issued — cannot cancel.", "content": { "application/json": { "example": { "status": "error", "message": "This ticket has already been issued. Please contact support for cancellation." } } } }, "404": { "description": "Not found on your account.", "content": { "application/json": { "example": { "status": "error", "message": "Booking not found." } } } } } } }, "/api/requery/{reference}": { "get": { "summary": "Requery Transaction", "tags": [ "Transactions" ], "description": "Checks the current status of any purchase (data, airtime, cable, electricity, exam, bulk SMS, eSIM, flight) by its reference — the `request-id` you sent when buying. Scoped to your account, so you only ever see your own transactions. Read-only; never re-charges. `transaction_status` is `success`, `pending` or `failed`. Use this to resolve a timeout or a missing callback instead of re-sending the purchase.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The transaction reference — the `request-id` you sent on the purchase.", "example": "Data_12345678900" } ], "responses": { "200": { "description": "The transaction.", "content": { "application/json": { "example": { "status": "success", "data": { "reference": "Data_12345678900", "request-id": "Data_12345678900", "type": "data", "amount": 100, "currency": "NGN", "transaction_status": "success", "message": "You have gifted 500MB to 2347013397088.", "date": "2026-06-25T20:00:00+01:00" } } } } }, "404": { "description": "Not found on your account.", "content": { "application/json": { "example": { "status": "fail", "message": "Transaction not found." } } } } } } }, "/api/esim/catalog/pricing": { "get": { "summary": "eSIM Pricing", "tags": [ "eSIM" ], "description": "Returns every country grouped with its buyable packages and NGN prices — a one-call catalog dump, handy for building a price list. For a single country use List eSIM Packages instead.", "responses": { "200": { "description": "Countries with packages.", "content": { "application/json": { "example": { "status": "success", "data": { "countries": [ { "id": 724, "name": "Spain", "packages": [ { "id": "esim_abc", "name": "Spain 1GB - 7 Days", "data_quantity": 1, "data_unit": "GB", "package_validity": 7, "package_validity_unit": "Day", "price_ngn": 2500, "package_type": "DATA-ONLY" } ] } ] } } } } } } } }, "/api/esim/catalog/continents": { "get": { "summary": "List eSIM Continents", "tags": [ "eSIM" ], "description": "Lists regional/continent groupings (e.g. Europe, Asia). Use a continent's `id` with List Packages by Continent for regional eSIMs that work across many countries.", "responses": { "200": { "description": "Continents.", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": 92415, "name": "Europe (40+ areas)", "image_url": null } ] } } } } } } }, "/api/esim/catalog/global": { "get": { "summary": "List Global eSIM Packages", "tags": [ "eSIM" ], "description": "Lists global eSIM packages that work across many countries worldwide. Priced in NGN. Paginated.", "parameters": [ { "name": "package_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DATA-ONLY", "DATA-VOICE-SMS" ] }, "description": "Filter by package type.", "example": "DATA-ONLY" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number (default 1).", "example": 1 } ], "responses": { "200": { "description": "Global packages.", "content": { "application/json": { "example": { "status": "success", "meta": { "total": 12, "perPage": 12, "currentPage": 1, "lastPage": 2 }, "data": [ { "id": "esim_abc", "name": "Global 1GB - 7 Days", "data_quantity": 1, "data_unit": "GB", "package_validity": 7, "package_validity_unit": "Day", "price_ngn": 2500, "package_type": "DATA-ONLY" } ] } } } } } } }, "/api/esim/catalog/by-continent/{id}": { "get": { "summary": "List Packages by Continent", "tags": [ "eSIM" ], "description": "Lists regional eSIM packages for a continent. Priced in NGN. Paginated. Use a package's `id` as `package_id` for Buy eSIM.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Continent ID from List eSIM Continents.", "example": 92415 }, { "name": "package_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DATA-ONLY", "DATA-VOICE-SMS" ] }, "description": "Filter by package type.", "example": "DATA-ONLY" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page number (default 1).", "example": 1 } ], "responses": { "200": { "description": "Packages for the continent.", "content": { "application/json": { "example": { "status": "success", "meta": { "total": 12, "perPage": 12, "currentPage": 1, "lastPage": 2 }, "data": [ { "id": "esim_abc", "name": "Europe 3GB - 30 Days", "data_quantity": 3, "data_unit": "GB", "package_validity": 30, "package_validity_unit": "Day", "price_ngn": 2500, "package_type": "DATA-ONLY" } ] } } } } } } }, "/api/flight/airlines": { "get": { "summary": "List Airlines", "tags": [ "Flights" ], "description": "Lists the airlines available for search/booking. Useful to map airline codes to names in your UI.", "responses": { "200": { "description": "Airlines.", "content": { "application/json": { "example": { "status": "success", "data": [ { "code": "P4", "name": "Air Peace" }, { "code": "W3", "name": "Arik Air" } ] } } } } } } }, "/api/flight/addons": { "get": { "summary": "Add-on Pricing", "tags": [ "Flights" ], "description": "Returns the fees for optional booking add-ons (WhatsApp ticket delivery, reminder call, email delivery), in NGN. Add these to the fare when you present a total to your customer.", "responses": { "200": { "description": "Add-on fees.", "content": { "application/json": { "example": { "status": "success", "data": { "whatsapp_fee": 100, "call_fee": 200, "email_fee": 0 } } } } } } } }, "/api/cable-providers": { "get": { "summary": "List Cable Providers", "tags": [ "Catalogs" ], "description": "Returns the cable providers and their IDs. Use the id as the cable field when verifying a smartcard or buying a subscription.", "responses": { "200": { "description": "Providers", "content": { "application/json": { "example": { "status": "success", "provider": [ { "id": 1, "plan_id": 1, "cable_name": "GOTV" }, { "id": 2, "plan_id": 2, "cable_name": "DSTV" }, { "id": 3, "plan_id": 3, "cable_name": "STARTIME" } ] } } } } } } } }, "components": { "securitySchemes": { "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Send your API key as `Token `.\n\nUse your **live key** for real transactions, or your **sandbox key** (`sk_test_…`) to test — sandbox calls return a realistic simulated result and never touch your wallet. Add `\"sandbox_status\": \"fail\"` to any sandbox request to simulate a failure." } } } }