{ "openapi": "3.0.3", "info": { "title": "GSUBZ API", "version": "1.0.0", "description": "Sell airtime, data, cable TV, electricity tokens, exam pins and social media services from your own website or app, using your GSUBZ wallet. Amounts are in Nigerian naira (NGN). Timestamps use West Africa Time (+01:00).\n\nAuthenticate every request except Get Plans, List All Services, List eSIM Countries, List eSIM Packages, List Games and List Game Products with `Authorization: Bearer `. Get your key at https://gsubz.com/dashboard/key.php.\n\nA transaction can return HTTP 200 and still fail: always check the `status` field. Send a unique `requestID` with each purchase and use Fetch Transaction Status before retrying after a timeout." }, "externalDocs": { "description": "Human-readable documentation", "url": "https://gsubz.com/api_doc/" }, "servers": [ { "url": "https://api.gsubz.com", "description": "Production" } ], "tags": [ { "name": "Wallet" }, { "name": "Services" }, { "name": "Plans" }, { "name": "Verify Customer" }, { "name": "Data & Airtime" }, { "name": "Cable TV" }, { "name": "Electricity" }, { "name": "Exam Pins" }, { "name": "Social Media Market" }, { "name": "Recharge Pins" }, { "name": "eSIM" }, { "name": "Games" }, { "name": "Bulk SMS" }, { "name": "Flights" }, { "name": "Store" }, { "name": "Transactions" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/balance/": { "post": { "tags": [ "Wallet" ], "summary": "Fetch Wallet Balance", "description": "Returns your current wallet balance in naira (₦). Check it before a purchase so you can top up before a transaction fails with `INSUFFICIENT_BALANCE`.", "operationId": "walletBalance", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "balance": "747.5" } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/category/": { "get": { "tags": [ "Services" ], "summary": "List All Services", "description": "Returns every active `serviceID` GSUBZ offers, grouped under its category — data, cable TV, electricity, social media and so on. Call this once to build a full picture of what's available, then use [Get Plans](#plans) for a specific service's pricing. No parameters: it always returns everything in one response, so filter or sort on your side.", "operationId": "listServices", "security": [], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "name": "electricity", "displayName": "Electricity", "image": "//gsubz.com/uploads/2021/9/1/electric-icon.png", "services": [ { "serviceID": "eko-electric", "displayName": "Eko (EKEDC)" }, { "serviceID": "kaduna-electric", "displayName": "Kaduna Electric" } ] }, { "name": "cable", "displayName": "Cable TV", "image": "//gsubz.com/uploads/2021/9/1/cable-icon.png", "services": [ { "serviceID": "gotv", "displayName": "GOtv" } ] } ] } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/plans/": { "get": { "tags": [ "Plans" ], "summary": "Get Plans", "description": "One shared endpoint for every category's plan list: data, cable TV, social media and more. Pass the `service` you want and get back that service's plans. Call it before a purchase to get the correct plan value. Every plan shows its normal `price` and its `api_price`, the price you pay through the API.\n\nThe plan identifier is returned in a field called `PlanName`, and its value tells you which body field to submit when buying. Data and social media services use `plan`. Cable TV services use `variation_code`.", "operationId": "plans", "security": [], "parameters": [ { "name": "service", "in": "query", "required": true, "description": "The service ID, for example `mtn_sme`. Also accepts cable (`gotv`, `dstv`, `startimes`) and social media (`socials`) service IDs. See [Service IDs](#service-ids).", "schema": { "type": "string", "example": "mtn_sme" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "service": "MTN-SME-Data(*461*4#)", "PlanName": "plan", "fixedPrice": true, "discount": "4.81%", "plans": [ { "displayName": "10GB - 30days", "value": "260", "price": "2400", "api_price": "2284.56" } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/verify-customer/": { "post": { "tags": [ "Verify Customer" ], "summary": "Verify Meter / IUC Number", "description": "Checks a meter number or a cable smartcard/IUC number before payment and returns the customer's name (and, for electricity meters, their address and account type). Always verify before you charge: it catches typing mistakes before money moves.\n\nFor electricity services, `type` is required: `prepaid` or `postpaid`. For cable services (`dstv`, `gotv`, `startimes`), leave `type` out.", "operationId": "verifyCustomer", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "serviceID": { "type": "string", "description": "Any electricity or cable service ID: see the list below, or `dstv`, `gotv`, `startimes` for cable. Underscores and hyphens both work, so `kaduna_electric` and `kaduna-electric` are the same.", "example": "kaduna_electric" }, "billersCode": { "type": "string", "description": "The meter number (electricity) or smartcard/IUC number (cable).", "example": "00000000000" }, "type": { "type": "string", "description": "`prepaid` or `postpaid`. Required for electricity, omit for cable.", "example": "prepaid" } }, "required": [ "api", "serviceID", "billersCode" ] }, "example": { "api": "YOUR_API_KEY", "serviceID": "kaduna_electric", "billersCode": "00000000000", "type": "prepaid" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "serviceID": { "type": "string", "description": "Any electricity or cable service ID: see the list below, or `dstv`, `gotv`, `startimes` for cable. Underscores and hyphens both work, so `kaduna_electric` and `kaduna-electric` are the same.", "example": "kaduna_electric" }, "billersCode": { "type": "string", "description": "The meter number (electricity) or smartcard/IUC number (cable).", "example": "00000000000" }, "type": { "type": "string", "description": "`prepaid` or `postpaid`. Required for electricity, omit for cable.", "example": "prepaid" } }, "required": [ "api", "serviceID", "billersCode" ] }, "example": { "api": "YOUR_API_KEY", "serviceID": "kaduna_electric", "billersCode": "00000000000", "type": "prepaid" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "description": "CUSTOMER_FOUND", "content": { "customerName": "JOHN ADEBAYO", "address": "12 SAMPLE STREET, IKEJA", "meterNumber": "45000000000", "meterType": "PREPAID", "accountType": null, "canVend": "yes" } } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "Could not verify this meter number" } } } } } } }, "/api/pay/": { "post": { "tags": [ "Data & Airtime", "Cable TV", "Electricity", "Exam Pins", "Social Media Market" ], "summary": "Make a purchase", "description": "One endpoint handles every purchase. The `serviceID` field decides what you are buying, and each service needs its own set of fields. Use the request variant that matches the service:\n\n- **Buy Data**: Send a data bundle to any Nigerian phone number. Call [Get Plans](#plans) with the network's `serviceID` first to get the exact `plan` value, then submit it here. The data service IDs are listed under [Service IDs](#service-ids).\n- **Buy Airtime**: Send airtime to any Nigerian number. The `serviceID` must be one of `mtn`, `airtel`, `etisalat` (9mobile) or `glo`: lowercase, spelt exactly as shown.\n- **Buy TV / Decoder / Cable Sub**: Renew a DStv, GOtv or StarTimes subscription. The `serviceID` must be `gotv`, `dstv` or `startimes`. Verify the smartcard/IUC number with [Verify Meter / IUC Number](#verify-customer) first.\n- **Buy Electric Token**: Generate an electricity token (prepaid) or pay a postpaid bill for any supported distribution company. Verify the meter number first with [Verify Meter / IUC Number](#verify-customer) so your customer sees their own name before you charge them.\n- **Buy Exam Pin**: Buy an exam pin. The `serviceID` must be `waec`, `neco` or `nabteb`: lowercase, spelt exactly as shown. Each exam service has one plan.\n- **Buy Social Media Service**: Place a social media order. The `serviceID` is always `socials`. Call [Get Plans](#plans) with `service=socials` first to get the `plan` value for the service you want (for example Instagram followers or TikTok likes).", "operationId": "makePurchase", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BuyDataRequest" }, { "$ref": "#/components/schemas/BuyAirtimeRequest" }, { "$ref": "#/components/schemas/BuyCableRequest" }, { "$ref": "#/components/schemas/BuyElectricRequest" }, { "$ref": "#/components/schemas/BuyExamPinRequest" }, { "$ref": "#/components/schemas/BuySocialRequest" } ] }, "examples": { "buyData": { "summary": "Buy Data", "value": { "serviceID": "mtn_sme", "plan": "260", "api": "YOUR_API_KEY", "amount": "", "phone": "08031234567", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyAirtime": { "summary": "Buy Airtime", "value": { "serviceID": "mtn", "api": "YOUR_API_KEY", "amount": "100", "phone": "08031234567", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyCable": { "summary": "Buy TV / Decoder / Cable Sub", "value": { "serviceID": "gotv", "api": "YOUR_API_KEY", "variation_code": "gotv-smallie", "phone": "08031234567", "amount": "", "customerID": "0000000000", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyElectric": { "summary": "Buy Electric Token", "value": { "serviceID": "kaduna_electric", "api": "YOUR_API_KEY", "phone": "08031234567", "customerID": "00000000000", "amount": "1100", "variation_code": "prepaid", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyExamPin": { "summary": "Buy Exam Pin", "value": { "serviceID": "waec", "plan": "waecdirect", "api": "YOUR_API_KEY", "amount": "", "phone": "08031234567", "requestID": "87dfhw8dbw8e7hw9d9dh" } }, "buySocial": { "summary": "Buy Social Media Service", "value": { "serviceID": "socials", "plan": "179", "api": "YOUR_API_KEY", "amount": "", "link": "https://instagram.com/gsubzonline", "quantity": "1000", "requestID": "8dhbc8w7huwh8hw9hew9" } } } }, "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BuyDataRequest" }, { "$ref": "#/components/schemas/BuyAirtimeRequest" }, { "$ref": "#/components/schemas/BuyCableRequest" }, { "$ref": "#/components/schemas/BuyElectricRequest" }, { "$ref": "#/components/schemas/BuyExamPinRequest" }, { "$ref": "#/components/schemas/BuySocialRequest" } ] }, "examples": { "buyData": { "summary": "Buy Data", "value": { "serviceID": "mtn_sme", "plan": "260", "api": "YOUR_API_KEY", "amount": "", "phone": "08031234567", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyAirtime": { "summary": "Buy Airtime", "value": { "serviceID": "mtn", "api": "YOUR_API_KEY", "amount": "100", "phone": "08031234567", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyCable": { "summary": "Buy TV / Decoder / Cable Sub", "value": { "serviceID": "gotv", "api": "YOUR_API_KEY", "variation_code": "gotv-smallie", "phone": "08031234567", "amount": "", "customerID": "0000000000", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyElectric": { "summary": "Buy Electric Token", "value": { "serviceID": "kaduna_electric", "api": "YOUR_API_KEY", "phone": "08031234567", "customerID": "00000000000", "amount": "1100", "variation_code": "prepaid", "requestID": "8dhbc8w7huwh8hw9hew9" } }, "buyExamPin": { "summary": "Buy Exam Pin", "value": { "serviceID": "waec", "plan": "waecdirect", "api": "YOUR_API_KEY", "amount": "", "phone": "08031234567", "requestID": "87dfhw8dbw8e7hw9d9dh" } }, "buySocial": { "summary": "Buy Social Media Service", "value": { "serviceID": "socials", "plan": "179", "api": "YOUR_API_KEY", "amount": "", "link": "https://instagram.com/gsubzonline", "quantity": "1000", "requestID": "8dhbc8w7huwh8hw9hew9" } } } } } }, "responses": { "200": { "description": "Response. Check `status`: a transaction can return HTTP 200 and still fail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": { "buyData": { "summary": "Buy Data", "value": { "code": 200, "status": "successful", "transactionID": 3878886201, "amount": 2400, "phone": "08031234567", "serviceID": "mtn_sme", "amountPaid": 2284.56, "initialBalance": 5000, "finalBalance": 2715.44, "date": "2026-09-28T09:47:15+01:00", "api_response": "Dear Customer, You have successfully shared 10GB Data to 2348031234567. Thankyou" } }, "buyAirtime": { "summary": "Buy Airtime", "value": { "code": 200, "status": "successful", "transactionID": 3768661863, "amount": 800, "phone": "08031234567", "serviceID": "mtn", "amountPaid": 768, "initialBalance": 5000, "finalBalance": 4232, "date": "2026-09-28T09:47:15+01:00", "api_response": "You have topped up N800.00 to 2348031234567. ref: 2026092809402519057879292" } }, "buyCable": { "summary": "Buy TV / Decoder / Cable Sub", "value": { "code": 200, "status": "successful", "transactionID": 3685573902, "amount": 900, "phone": "08031234567", "serviceID": "gotv", "amountPaid": 882, "initialBalance": 5000, "finalBalance": 4118, "date": "2026-09-28T09:47:15+01:00", "api_response": "Your GOtv subscription was successful." } }, "buyElectric": { "summary": "Buy Electric Token", "value": { "code": 200, "status": "successful", "transactionID": 3574357094, "amount": 1100, "phone": "08031234567", "serviceID": "kaduna_electric", "amountPaid": 1100, "initialBalance": 5000, "finalBalance": 3900, "date": "2026-09-28T09:47:15+01:00", "api_response": "Token: 47488383838383838383833" } }, "buyExamPin": { "summary": "Buy Exam Pin", "value": { "code": 200, "status": "successful", "transactionID": 3075647209, "amount": 3500, "phone": "08031234567", "serviceID": "waec", "amountPaid": 3500, "initialBalance": 5000, "finalBalance": 1500, "date": "2026-09-28T09:47:15+01:00", "api_response": "968686868685<=>WRN2056666666" } }, "buySocial": { "summary": "Buy Social Media Service", "value": { "code": 200, "status": "successful", "transactionID": 3075647200, "amount": 179, "serviceID": "socials", "amountPaid": 179, "initialBalance": 5000, "finalBalance": 4821, "date": "2026-09-28T09:47:15+01:00", "api_response": "Order received. Order ID: 39554883" } } } } } }, "default": { "description": "Error. See the Errors section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/generate/": { "post": { "tags": [ "Recharge Pins" ], "summary": "Recharge Pins / Epins Printing", "description": "Generate recharge card pins for printing. The `network` must be `mtn`, `airtel`, `glo` or `9mobile`: lowercase, spelt exactly as shown. This endpoint authenticates with the `Authorization` header only.\n\nIf you get `UNABLE_TO_PROCESS_REQUEST`, or no response at all, do not resend the order straight away. Check [Fetch Recharge Pin Orders](#generate-history) first: if the order is listed, it went through and your pins are there. Only send a new order when it is not listed.", "operationId": "generatePins", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "network": { "type": "string", "description": "`mtn`, `airtel`, `glo` or `9mobile`.", "example": "airtel" }, "value": { "type": "string", "description": "Face value of each pin in naira: `100`, `200`, `400` or `500`.", "example": "500" }, "number": { "type": "string", "description": "How many pins to generate. The minimum is 10 for values below 500.", "example": "1" } }, "required": [ "network", "value", "number" ] }, "example": { "network": "airtel", "value": "500", "number": "1" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "network": { "type": "string", "description": "`mtn`, `airtel`, `glo` or `9mobile`.", "example": "airtel" }, "value": { "type": "string", "description": "Face value of each pin in naira: `100`, `200`, `400` or `500`.", "example": "500" }, "number": { "type": "string", "description": "How many pins to generate. The minimum is 10 for values below 500.", "example": "1" } }, "required": [ "network", "value", "number" ] }, "example": { "network": "airtel", "value": "500", "number": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "We Received your order, 1 of 1 delivered\n Thank you for your patronage", "status": "success", "id": "c143e774874a59623aa928292d128f97", "network": "Airtel", "value": "500", "number": "1", "delivered": "1", "pending": 0, "pins": [ { "pin": "5794977707301520", "sn": "26026825914918714922" } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/generate/history/": { "get": { "tags": [ "Recharge Pins" ], "summary": "Fetch Recharge Pin Orders", "description": "Returns your recent [Recharge Pins](#generate-pins) orders, newest first, so you can compare them with your own records. If an order timed out or its response never reached you, the pins are here: read them from this endpoint instead of resending the order. Send an `order_id` to get just one order. This endpoint is free and authenticates with the `Authorization` header only. It also accepts POST.\n\nEvery order comes with its `pins` (the `pin` and its serial number `sn`), so you can save any you did not receive. A long list can be large: use `limit` for fewer orders, or `order_id` for one. Send `pins=0` if you only want the order details.\n\n`order_id` is the `id` returned when you placed the order.", "operationId": "generateHistory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many orders to return, from 1 to 200. The default is 200.", "schema": { "type": "string", "example": "200" } }, { "name": "order_id", "in": "query", "required": false, "description": "Return only this order, with its pins. Use the `id` from the order response.", "schema": { "type": "string", "example": "c143e774874a59623aa928292d128f97" } }, { "name": "pins", "in": "query", "required": false, "description": "Pins are included by default. Send `0` to leave them out.", "schema": { "type": "string", "example": "0" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": "200", "status": "TRANSACTION_SUCCESSFUL", "count": 1, "orders": [ { "order_id": "c143e774874a59623aa928292d128f97", "description": "Airtel-500-1 28/09/2026", "network": "airtel", "value": "500", "requested": 1, "delivered": 1, "amount_paid": "485", "status": "success", "timestamp": 1790585235, "date": "2026-09-28 09:47:15", "pins": [ { "pin": "5794977707301520", "sn": "26026825914918714922" } ] } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "404", "description": "ORDER_NOT_FOUND", "status": "TRANSACTION_FAILED" } } } } } } }, "/api/esim/countries/": { "get": { "tags": [ "eSIM" ], "summary": "List eSIM Countries", "description": "An eSIM gives your customer mobile data in another country without a physical SIM card. Start here: list the countries, pick one, then call [List eSIM Packages](#esim-packages) with its `locationCodes`. This list is public and needs no API key.", "operationId": "esimCountries", "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text to filter countries by name, for example `fra` for France. Leave it out to list every country.", "schema": { "type": "string", "example": "fra" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "countries": [ { "country": "France", "locationCodes": "FR", "plans": 12 }, { "country": "Spain", "locationCodes": "ES", "plans": 9 } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/esim/packages/": { "get": { "tags": [ "eSIM" ], "summary": "List eSIM Packages", "description": "Returns the data packages for one country, cheapest first. Use the `packageCode` of the one your customer wants when you call [Buy eSIM](#esim-buy). This list is public and needs no API key.\n\n`price` is in naira and can change slightly between this list and your purchase, because the live price is checked when you buy. Read `amountPaid` in the purchase response for what was actually charged.", "operationId": "esimPackages", "security": [], "parameters": [ { "name": "locationCode", "in": "query", "required": true, "description": "The `locationCodes` value from [List eSIM Countries](#esim-countries). You can send up to twenty codes, separated by commas.", "schema": { "type": "string", "example": "FR" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "packages": [ { "packageCode": "FR_1_7", "name": "France 1GB 7Days", "country": "France", "dataGB": 1, "duration": 7, "durationUnit": "DAY", "price": 2607, "refundable": true, "topUp": true } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/esim/buy/": { "post": { "tags": [ "eSIM" ], "summary": "Buy eSIM", "description": "Buys one eSIM. Your wallet is charged and the eSIM details come back in the response: scan the `qrCodeUrl` image or type the `activationCode` into the phone to install it.\n\nAlways send a `requestID`. If you send the same one again, the API returns the original order (code `406`, `INVALID_ARGUMENTS_DUPLICATE_REQUEST_ID`) and never charges twice.\n\nIf `esimStatus` is `provisioning`, the eSIM is still being prepared. Call [Fetch eSIM Orders](#esim-orders) in a minute to get the QR code and activation code. You have already been charged.", "operationId": "esimBuy", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "packageCode": { "type": "string", "description": "The `packageCode` from [List eSIM Packages](#esim-packages).", "example": "FR_1_7" }, "requestID": { "type": "string", "description": "Your own unique reference for this order, up to 100 characters. Use it later with [Fetch eSIM Orders](#esim-orders).", "example": "esim-1001" } }, "required": [ "api", "packageCode" ] }, "example": { "api": "YOUR_API_KEY", "packageCode": "FR_1_7", "requestID": "esim-1001" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "packageCode": { "type": "string", "description": "The `packageCode` from [List eSIM Packages](#esim-packages).", "example": "FR_1_7" }, "requestID": { "type": "string", "description": "Your own unique reference for this order, up to 100 characters. Use it later with [Fetch eSIM Orders](#esim-orders).", "example": "esim-1001" } }, "required": [ "api", "packageCode" ] }, "example": { "api": "YOUR_API_KEY", "packageCode": "FR_1_7", "requestID": "esim-1001" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "transactionID": "ESIMA0BA0EC673A45212", "orderID": 1, "amount": 3476, "serviceID": "esim", "amountPaid": 3476, "initialBalance": 100000, "finalBalance": 96524, "date": "2026-09-28T12:36:59+01:00", "api_response": "Your eSIM is ready. Scan the QR code or enter the activation code to install it.", "requestID": "esim-1001", "packageCode": "FR_1_7", "packageName": "France 1GB 7Days", "country": "France", "esimStatus": "active", "iccid": "8944500102030405060", "activationCode": "LPA:1$rsp.example.com$ABCD-1234-EFGH", "qrCodeUrl": "https://example.com/qr/ORD-123" } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 402, "status": "failed", "description": "INSUFFICIENT_BALANCE", "api_response": "Insufficient balance. This eSIM costs ₦3,476.00 but your wallet has ₦100.00." } } } } } } }, "/api/esim/orders/": { "post": { "tags": [ "eSIM" ], "summary": "Fetch eSIM Orders", "description": "Returns your eSIM orders. Send a `requestID` or an `orderID` to get one order, or send neither to list your last 50. An order that was still being prepared is checked again each time you call, so this is also how you collect the QR code after a `provisioning` purchase.", "operationId": "esimOrders", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "requestID": { "type": "string", "description": "The `requestID` you sent when you bought the eSIM.", "example": "esim-1001" }, "orderID": { "type": "integer", "description": "The `orderID` from the purchase response.", "example": 1 } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY", "requestID": "esim-1001", "orderID": "1" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "requestID": { "type": "string", "description": "The `requestID` you sent when you bought the eSIM.", "example": "esim-1001" }, "orderID": { "type": "integer", "description": "The `orderID` from the purchase response.", "example": 1 } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY", "requestID": "esim-1001", "orderID": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "orders": [ { "orderID": 1, "transactionID": "ESIMA0BA0EC673A45212", "packageCode": "FR_1_7", "packageName": "France 1GB 7Days", "country": "France", "amountPaid": 3476, "amountRefunded": 0, "esimStatus": "active", "iccid": "8944500102030405060", "activationCode": "LPA:1$rsp.example.com$ABCD-1234-EFGH", "qrCodeUrl": "https://example.com/qr/ORD-123", "date": "2026-09-28T12:36:59+01:00" } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "No eSIM order found for that reference." } } } } } } }, "/api/esim/cancel/": { "post": { "tags": [ "eSIM" ], "summary": "Cancel eSIM", "description": "Cancels an eSIM that has not been installed and returns what you paid to your wallet. It can only work once for each order.\n\nOnly an unused eSIM can be cancelled. If it has already been installed, used or refunded, the request is refused with `NOT_CANCELLABLE` and nothing is refunded.", "operationId": "esimCancel", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "orderID": { "type": "integer", "description": "The `orderID` from the purchase response or from [Fetch eSIM Orders](#esim-orders).", "example": 1 } }, "required": [ "api", "orderID" ] }, "example": { "api": "YOUR_API_KEY", "orderID": "1" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "orderID": { "type": "integer", "description": "The `orderID` from the purchase response or from [Fetch eSIM Orders](#esim-orders).", "example": 1 } }, "required": [ "api", "orderID" ] }, "example": { "api": "YOUR_API_KEY", "orderID": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "orderID": 1, "amountRefunded": 3476, "initialBalance": 96524, "finalBalance": 100000, "date": "2026-09-28T12:37:22+01:00", "api_response": "Refunded ₦3,476.00." } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 406, "status": "failed", "description": "NOT_CANCELLABLE", "api_response": "This eSIM cannot be cancelled. It may already be in use." } } } } } } }, "/api/games/list/": { "get": { "tags": [ "Games" ], "summary": "List Games", "description": "Top up a player's game account or sell a gift card. Start here: list the games and brands on sale, most popular first, then call [List Game Products](#games-products) with the `gameID` you want. This list is public and needs no API key.", "operationId": "gamesList", "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text to filter by name, for example `free` for Free Fire. Leave it out to list everything.", "schema": { "type": "string", "example": "free" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "games": [ { "gameID": 12, "name": "Free Fire", "image": "https://gsubz.com/uploads/gaming/free-fire.png", "note": null, "lines": 2, "products": 24, "fromPrice": 1440 }, { "gameID": 20, "name": "Roblox", "image": "https://gsubz.com/uploads/gaming/roblox.png", "note": "Codes arrive within seconds.", "lines": 1, "products": 8, "fromPrice": 8000 } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/games/products/": { "get": { "tags": [ "Games" ], "summary": "List Game Products", "description": "Returns the product lines of one game, each with the fields the player must give and the amounts or packs you can buy, priced in naira. Use a `productID` from here with [Validate Player ID](#games-validate) and [Buy Game Top-up](#games-buy). This list is public and needs no API key.\n\nA game can have several product lines, usually one for each region. A player's account only works with the line for its own region, so check `region` and use [Validate Player ID](#games-validate) before charging. Each line has its own `requirements`: send every field it lists, using its `field` name, when you validate or buy.", "operationId": "gamesProducts", "security": [], "parameters": [ { "name": "gameID", "in": "query", "required": true, "description": "The `gameID` from [List Games](#games-list).", "schema": { "type": "string", "example": "12" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "game": { "gameID": 12, "name": "Free Fire", "image": "https://gsubz.com/uploads/gaming/free-fire.png", "note": null }, "lines": [ { "lineID": 467, "name": "Direct Topup Mena", "region": "Mena", "requirements": [ { "field": "player_id", "label": "Player ID", "type": "text", "required": true, "options": null } ], "products": [ { "productID": "101", "name": "100 Diamonds", "price": 1520, "kind": "amount", "inStock": true }, { "productID": "102", "name": "Weekly Membership", "price": 5200, "kind": "pack", "inStock": null } ] } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "That game is not available." } } } } } } }, "/api/games/validate/": { "post": { "tags": [ "Games" ], "summary": "Validate Player ID", "description": "Checks the player's details for a product and returns the player's name (and region, when the game states one), so your customer can confirm it is the right account before you buy. It is free. Always validate before you buy: it catches a wrong ID or the wrong region before any money moves.\n\nSend every field the product line lists under `requirements`, using its `field` name. Most games need only `player_id`. Games that need more, such as a zone or server, take those as extra fields named exactly as listed in `requirements`, for example `zone_id`. Gift cards need no player details and answer `NO_ID_NEEDED`.\n\nYou can make 20 checks every 10 minutes for each API key.", "operationId": "gamesValidate", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "productID": { "type": "string", "description": "The `productID` from [List Game Products](#games-products).", "example": "101" }, "player_id": { "type": "string", "description": "The player's ID. Needed by most games. It is one of the fields a line lists under `requirements`.", "example": "12345678" } }, "required": [ "productID" ] }, "example": { "productID": "101", "player_id": "12345678" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "productID": { "type": "string", "description": "The `productID` from [List Game Products](#games-products).", "example": "101" }, "player_id": { "type": "string", "description": "The player's ID. Needed by most games. It is one of the fields a line lists under `requirements`.", "example": "12345678" } }, "required": [ "productID" ] }, "example": { "productID": "101", "player_id": "12345678" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "description": "PLAYER_FOUND", "playerName": "ProGamer99", "region": "AF", "api_response": "Player found." } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "PLAYER_NOT_FOUND", "api_response": "We could not find that player ID. Please check it and try again." } } } } } } }, "/api/games/buy/": { "post": { "tags": [ "Games" ], "summary": "Buy Game Top-up", "description": "Buys one game top-up or gift card. Your wallet is charged first. A top-up goes straight to the player's account, and a gift card returns its code or codes in `codes`. Validate the player with [Validate Player ID](#games-validate) first.\n\nAlways send a `requestID`. If you send the same one again, the API returns the original order (code `406`, `INVALID_ARGUMENTS_DUPLICATE_REQUEST_ID`) and never buys twice. A `requestID` is free to use again only after a request that was refused before any money moved (for example a wrong player ID or too little balance).\n\n**An order can still be processing.** When `orderStatus` is `processing`, you have been charged and the order is not finished. It ends as `completed` or `refunded`. We send you a [webhook](#webhooks) (`games.order.updated`) when it finishes, and you can always check it with [Fetch Game Orders](#games-orders). A refund goes back to your wallet automatically, and an order is never refunded while its outcome is unclear.\n\nSend every field the product line lists under `requirements`, using its `field` name. Most games need only `player_id`. Games that need more, such as a zone or server, take those as extra fields named exactly as listed in `requirements`, for example `zone_id`.", "operationId": "gamesBuy", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "productID": { "type": "string", "description": "The `productID` from [List Game Products](#games-products).", "example": "101" }, "player_id": { "type": "string", "description": "The player's ID. Needed by most games. It is one of the fields a line lists under `requirements`.", "example": "12345678" }, "requestID": { "type": "string", "description": "Your own unique reference for this order, up to 100 characters. Use it later with [Fetch Game Orders](#games-orders).", "example": "game-1001" } }, "required": [ "productID" ] }, "example": { "productID": "101", "player_id": "12345678", "requestID": "game-1001" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "productID": { "type": "string", "description": "The `productID` from [List Game Products](#games-products).", "example": "101" }, "player_id": { "type": "string", "description": "The player's ID. Needed by most games. It is one of the fields a line lists under `requirements`.", "example": "12345678" }, "requestID": { "type": "string", "description": "Your own unique reference for this order, up to 100 characters. Use it later with [Fetch Game Orders](#games-orders).", "example": "game-1001" } }, "required": [ "productID" ] }, "example": { "productID": "101", "player_id": "12345678", "requestID": "game-1001" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "transactionID": "GM261007113015A1B2C3D4", "orderID": 15, "amount": 1520, "serviceID": "games", "amountPaid": 1520, "initialBalance": 100000, "finalBalance": 98480, "date": "2026-10-07T11:30:15+01:00", "api_response": "Your order is complete.", "requestID": "game-1001", "game": "Free Fire · Direct Topup Mena", "product": "100 Diamonds", "orderStatus": "completed", "playerName": "ProGamer99", "codes": [] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "PLAYER_NOT_FOUND", "api_response": "We could not find that player ID. Please check it and try again. You have not been charged." } } } } } } }, "/api/games/orders/": { "post": { "tags": [ "Games" ], "summary": "Fetch Game Orders", "description": "Returns your game orders, including orders bought on the website. Send a `requestID`, an `orderID` or a `transactionID` to get one order, or send none of them to list your last 50. An order that is still processing is checked again when you look it up (at most every 25 seconds), so this is also how you collect the result, and any gift-card codes, after a `processing` purchase if you missed the [webhook](#webhooks).", "operationId": "gamesOrders", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "requestID": { "type": "string", "description": "The `requestID` you sent when you bought.", "example": "game-1001" }, "orderID": { "type": "integer", "description": "The `orderID` from the purchase response.", "example": 15 }, "transactionID": { "type": "string", "description": "The `transactionID` from the purchase response.", "example": "GM261007113015A1B2C3D4" } } }, "example": { "requestID": "game-1001", "orderID": "15", "transactionID": "GM261007113015A1B2C3D4" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "requestID": { "type": "string", "description": "The `requestID` you sent when you bought.", "example": "game-1001" }, "orderID": { "type": "integer", "description": "The `orderID` from the purchase response.", "example": 15 }, "transactionID": { "type": "string", "description": "The `transactionID` from the purchase response.", "example": "GM261007113015A1B2C3D4" } } }, "example": { "requestID": "game-1001", "orderID": "15", "transactionID": "GM261007113015A1B2C3D4" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "orders": [ { "orderID": 15, "transactionID": "GM261007113015A1B2C3D4", "requestID": "game-1001", "game": "Free Fire · Direct Topup Mena", "product": "100 Diamonds", "amount": 1520, "amountPaid": 1520, "amountRefunded": 0, "orderStatus": "completed", "playerName": "ProGamer99", "codes": [], "date": "2026-10-07T11:30:15+01:00" } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "No game order found for that reference." } } } } } } }, "/api/sms/": { "post": { "tags": [ "Bulk SMS" ], "summary": "Send Bulk SMS", "description": "Sends one text message to up to 5,000 Nigerian numbers in a single request. Your wallet is charged first, the message is sent, and anything that could not be sent is refunded automatically.\n\nThe field names `from`, `to` and `msg` are the standard names most SMS gateways use, so code written for another SMS service needs very little change. The message type (normal or unicode) is detected for you, so you never send `type`.\n\nYour message is checked before anything is charged, because the networks block certain content. These are refused: names of banks and payment companies, international brands such as WhatsApp or Facebook, OTP or verification-code wording, messages that look like bank credit or debit alerts, and any run of four or more digits in a row (write amounts with commas, for example `5,000`; years like 2026 are fine). Numbers on the DND list are not delivered by the networks and are not refunded.\n\nYou pay per page, per recipient. One page is 160 characters (153 each once the message is longer), or 70 (67) if it has emoji or other special characters. The naira sign is sent as `N` so it does not turn the message into a special-character one. The price is currently ₦5 per page per recipient, and `amount` in the response shows exactly what was charged.\n\nNumbers are cleaned and de-duplicated. Invalid or repeated numbers are skipped and counted in `skipped`. If some numbers cannot be sent, the request still returns `successful` with `failed` above zero, and those numbers are refunded. If nothing can be sent you get `GATEWAY_ERROR` and you are not charged.\n\nCommon failures, all with `\"status\": \"failed\"`: `INVALID_SENDER`, `MESSAGE_CONTENT_BLOCKED` (with an `issues` list), `NO_VALID_RECIPIENTS`, `TOO_MANY_RECIPIENTS` and `MESSAGE_TOO_LONG` (code `206`), and `DUPLICATE_MESSAGE` (code `406`, the same message to the same list within two minutes and no `requestID` sent). Send a `requestID` to send the same message again on purpose.", "operationId": "sendSms", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "from": { "type": "string", "description": "The sender name shown on the phone: 3 to 11 letters, with no spaces, numbers or symbols. Names of banks, payment companies, telecoms and government bodies cannot be used.", "example": "MyShop" }, "to": { "type": "string", "description": "The phone numbers, separated by commas or new lines, up to 5,000. `080…`, `234…` and `+234…` are all accepted.", "example": "08031234567,08021234568" }, "msg": { "type": "string", "description": "The message text, up to 905 characters.", "example": "Hello, your order is ready for pickup." }, "requestID": { "type": "string", "description": "Your own unique reference for this send, up to 100 characters. Send the same one again and you get the original result back, never a second send or charge. `message_uuid` is accepted as the same thing.", "example": "sms-1001" } }, "required": [ "api", "from", "to", "msg" ] }, "example": { "api": "YOUR_API_KEY", "from": "MyShop", "to": "08031234567,08021234568", "msg": "Hello, your order is ready for pickup.", "requestID": "sms-1001" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "from": { "type": "string", "description": "The sender name shown on the phone: 3 to 11 letters, with no spaces, numbers or symbols. Names of banks, payment companies, telecoms and government bodies cannot be used.", "example": "MyShop" }, "to": { "type": "string", "description": "The phone numbers, separated by commas or new lines, up to 5,000. `080…`, `234…` and `+234…` are all accepted.", "example": "08031234567,08021234568" }, "msg": { "type": "string", "description": "The message text, up to 905 characters.", "example": "Hello, your order is ready for pickup." }, "requestID": { "type": "string", "description": "Your own unique reference for this send, up to 100 characters. Send the same one again and you get the original result back, never a second send or charge. `message_uuid` is accepted as the same thing.", "example": "sms-1001" } }, "required": [ "api", "from", "to", "msg" ] }, "example": { "api": "YOUR_API_KEY", "from": "MyShop", "to": "08031234567,08021234568", "msg": "Hello, your order is ready for pickup.", "requestID": "sms-1001" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "transactionID": 3530235131, "amount": 10, "serviceID": "bulk_sms", "amountPaid": 10, "initialBalance": 1000, "finalBalance": 990, "date": "2026-09-28T12:30:52+01:00", "api_response": "Your message was sent to 2 numbers.", "reference": "BSMSA260928123052FC8106", "requestID": "sms-1001", "sender": "MyShop", "recipients": 2, "sent": 2, "failed": 0, "skipped": 0, "pages": 1 } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 206, "status": "failed", "description": "MESSAGE_CONTENT_BLOCKED", "api_response": "This message would be blocked by the networks, so it was not sent. The networks block messages that mention international brands such as WhatsApp or Facebook.", "issues": [ "The networks block messages that mention international brands such as WhatsApp or Facebook." ] } } } } } } }, "/api/flight/search/": { "get": { "tags": [ "Flights" ], "summary": "List Airports", "description": "Returns airports with their 3-letter `code`, name, city and country. Send `q` to search by city, airport name, code or country (the best 15 matches). Send nothing to get the popular airports, or `all=true` to download the whole list and keep it in your own cache. Use the `code` as `origin` and `destination` in [Search Flights](#flight-search).", "operationId": "flightAirports", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text, for example `lagos`, `abuja`, `LHR` or `London`. Leave it out for the popular airports.", "schema": { "type": "string", "example": "lagos" } }, { "name": "all", "in": "query", "required": false, "description": "`true` returns every airport instead of the best matches.", "schema": { "type": "string", "example": "true" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "count": 1, "airports": [ { "code": "LOS", "name": "Murtala Muhammed International Airport", "city": "Lagos", "country": "Nigeria" } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 401, "status": "failed", "description": "INVALID_API_OR_NOT_FOUND", "api_response": "This API key is not valid." } } } } } }, "post": { "tags": [ "Flights" ], "summary": "Search Flights", "description": "Searches flights for a date (and a return date for a return trip) and returns the available options, cheapest first, with every price in naira. Searching is free. Each option carries a `token`. Send that token, together with the `searchID` of this response, to [Book a Flight](#flight-book).\n\nPrices already include our margin, so `amount` is what the booking will cost, to the naira. The price is confirmed again when you call [Book a Flight](#flight-book) with `preview=true`, so show your customer that price, not the search one.\n\nSend `return_date` to search a return trip; leave it out for one-way. Times in the results are the local time at each airport, with no timezone. A search stays valid for one hour. You can run up to 20 searches a minute for each API key.", "operationId": "flightSearch", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "origin": { "type": "string", "description": "The airport code you fly from, from [List Airports](#flight-airports).", "example": "LOS" }, "destination": { "type": "string", "description": "The airport code you fly to.", "example": "ABV" }, "departure_date": { "type": "string", "description": "Departure date as `YYYY-MM-DD`. Today or later.", "example": "2026-12-01" }, "return_date": { "type": "string", "description": "Return date as `YYYY-MM-DD`, on or after the departure date. Leave it out for a one-way trip.", "example": "2026-12-08" }, "adults": { "type": "integer", "description": "Adults (12 and over). 1 to 9. The default is 1.", "example": 1 }, "children": { "type": "integer", "description": "Children (2 to 11). 0 to 9.", "example": 0 }, "infants": { "type": "integer", "description": "Infants (under 2). Each needs an adult. 0 to 9.", "example": 0 }, "cabin": { "type": "string", "description": "`economy` (default), `premium_economy`, `business` or `first`.", "example": "economy" } }, "required": [ "api", "origin", "destination", "departure_date" ] }, "example": { "api": "YOUR_API_KEY", "origin": "LOS", "destination": "ABV", "departure_date": "2026-12-01", "adults": "1" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "origin": { "type": "string", "description": "The airport code you fly from, from [List Airports](#flight-airports).", "example": "LOS" }, "destination": { "type": "string", "description": "The airport code you fly to.", "example": "ABV" }, "departure_date": { "type": "string", "description": "Departure date as `YYYY-MM-DD`. Today or later.", "example": "2026-12-01" }, "return_date": { "type": "string", "description": "Return date as `YYYY-MM-DD`, on or after the departure date. Leave it out for a one-way trip.", "example": "2026-12-08" }, "adults": { "type": "integer", "description": "Adults (12 and over). 1 to 9. The default is 1.", "example": 1 }, "children": { "type": "integer", "description": "Children (2 to 11). 0 to 9.", "example": 0 }, "infants": { "type": "integer", "description": "Infants (under 2). Each needs an adult. 0 to 9.", "example": 0 }, "cabin": { "type": "string", "description": "`economy` (default), `premium_economy`, `business` or `first`.", "example": "economy" } }, "required": [ "api", "origin", "destination", "departure_date" ] }, "example": { "api": "YOUR_API_KEY", "origin": "LOS", "destination": "ABV", "departure_date": "2026-12-01", "adults": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "searchID": "FS3A9C41D07B22E8F5A61", "expiresAt": "2026-10-17T11:59:51+01:00", "currency": "NGN", "count": 1, "api_response": "Found 1 flight option.", "offers": [ { "token": "eyJhbGciOi…", "airline": "Ibom Air", "airlineCode": "QI", "logo": "https://…/QI.png", "amount": 95000, "refundable": false, "journeys": [ { "from": "LOS", "to": "ABV", "departsAt": "2026-12-01T08:00:00", "arrivesAt": "2026-12-01T09:10:00", "duration": "1h10", "stops": 0, "flightNumber": "QI 301", "baggage": "23KG baggage" } ] } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 206, "status": "failed", "description": "INVALID_CONTENT", "api_response": "origin and destination must be different." } } } } } } }, "/api/flight/book/": { "post": { "tags": [ "Flights" ], "summary": "Book a Flight", "description": "Books one flight for your customer and pays for it from your wallet. The price is locked first: send `preview=true` to get the final price (and a `quoteID`) without paying, then book with that `quoteID`, or book straight away with the `token` and `searchID` from [Search Flights](#flight-search). Send the body as JSON (recommended) or as form fields.\n\n**Two steps.** 1) `preview=true` with `token` and `searchID` returns the final price and a `quoteID` that stays valid for about 25 minutes (`expiresIn`). Nothing is charged. 2) Send the passengers and contact with that `quoteID` to book at exactly that price. A quote can be used once. Add `maxAmount` to refuse a booking that would cost more: you get `PRICE_CHANGED` and nothing is charged.\n\n**A booking can still be processing.** When `orderStatus` is `processing`, you have been charged and the airline is still issuing the ticket. It ends as `completed` (with the `pnr` and `tickets`) or `refunded`. We send you a [webhook](#webhooks) (`flight.order.updated`) when it changes, and you can always check it with [Fetch Flight Orders](#flight-orders). A refund goes back to your wallet automatically, and a booking is never refunded while its outcome is unclear.\n\nAlways send a `requestID`. Send the same one again and you get the original booking back (code `406`, `INVALID_ARGUMENTS_DUPLICATE_REQUEST_ID`) and never a second booking, so retrying after a timeout is safe. International trips need `passport_number` and `passport_expiry` for every passenger, and the passport must be valid after the last travel date. The ticket e-mail to your customer is yours to send: we do not e-mail them.", "operationId": "flightBook", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "searchID": { "type": "string", "description": "The `searchID` from [Search Flights](#flight-search). Needed together with `token`.", "example": "FS3A9C41D07B22E8F5A61" }, "token": { "type": "string", "description": "The `token` of the option your customer picked in [Search Flights](#flight-search).", "example": "eyJhbGciOi…" }, "quoteID": { "type": "string", "description": "The `quoteID` from an earlier `preview=true` call. Books at that locked price.", "example": "Q1b2c3d4" }, "passengers": { "type": "array", "items": { "type": "object", "required": [ "type", "title", "first_name", "last_name", "gender" ], "properties": { "type": { "type": "string", "enum": [ "adult", "child", "infant" ] }, "title": { "type": "string" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "country_code": { "type": "string" }, "passport_number": { "type": "string" }, "passport_expiry": { "type": "string" } } }, "description": "One item for each traveller, matching the adults, children and infants you searched. Each has `type` (`adult`, `child` or `infant`), `title` (`Mr`, `Mrs`, `Ms`, `Miss` or `Master`), `first_name`, `last_name`, `gender` (`male` or `female`), and optionally `middle_name` and `country_code` (2 letters, default `NG`). International trips also need `passport_number` and `passport_expiry` (`YYYY-MM-DD`). Names use letters only." }, "contact": { "type": "object", "required": [ "email", "phone" ], "properties": { "email": { "type": "string" }, "phone": { "type": "string" } }, "description": "Who the airline contacts: `email` and `phone` (`080…`, `234…` or `+234…`)." }, "requestID": { "type": "string", "description": "Your own unique reference for this booking, up to 100 characters. Use it later with [Fetch Flight Orders](#flight-orders).", "example": "flight-1001" }, "maxAmount": { "type": "string", "description": "The most you will pay, in naira. If the price is higher you get `PRICE_CHANGED` and nothing is charged.", "example": "100000" }, "preview": { "type": "boolean", "description": "`true` locks and returns the final price (as `quoteID` and `amount`) without booking or charging anything.", "example": true } } }, "example": { "searchID": "FS3A9C41D07B22E8F5A61", "token": "eyJhbGciOi…", "passengers": [ { "type": "adult", "title": "Mr", "first_name": "Ada", "last_name": "Obi", "gender": "male" } ], "contact": { "email": "customer@example.com", "phone": "08031234567" }, "requestID": "flight-1001", "preview": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "searchID": { "type": "string", "description": "The `searchID` from [Search Flights](#flight-search). Needed together with `token`.", "example": "FS3A9C41D07B22E8F5A61" }, "token": { "type": "string", "description": "The `token` of the option your customer picked in [Search Flights](#flight-search).", "example": "eyJhbGciOi…" }, "quoteID": { "type": "string", "description": "The `quoteID` from an earlier `preview=true` call. Books at that locked price.", "example": "Q1b2c3d4" }, "passengers": { "type": "array", "items": { "type": "object", "required": [ "type", "title", "first_name", "last_name", "gender" ], "properties": { "type": { "type": "string", "enum": [ "adult", "child", "infant" ] }, "title": { "type": "string" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "country_code": { "type": "string" }, "passport_number": { "type": "string" }, "passport_expiry": { "type": "string" } } }, "description": "One item for each traveller, matching the adults, children and infants you searched. Each has `type` (`adult`, `child` or `infant`), `title` (`Mr`, `Mrs`, `Ms`, `Miss` or `Master`), `first_name`, `last_name`, `gender` (`male` or `female`), and optionally `middle_name` and `country_code` (2 letters, default `NG`). International trips also need `passport_number` and `passport_expiry` (`YYYY-MM-DD`). Names use letters only." }, "contact": { "type": "object", "required": [ "email", "phone" ], "properties": { "email": { "type": "string" }, "phone": { "type": "string" } }, "description": "Who the airline contacts: `email` and `phone` (`080…`, `234…` or `+234…`)." }, "requestID": { "type": "string", "description": "Your own unique reference for this booking, up to 100 characters. Use it later with [Fetch Flight Orders](#flight-orders).", "example": "flight-1001" }, "maxAmount": { "type": "string", "description": "The most you will pay, in naira. If the price is higher you get `PRICE_CHANGED` and nothing is charged.", "example": "100000" }, "preview": { "type": "boolean", "description": "`true` locks and returns the final price (as `quoteID` and `amount`) without booking or charging anything.", "example": true } } }, "example": { "searchID": "FS3A9C41D07B22E8F5A61", "token": "eyJhbGciOi…", "passengers": [ { "type": "adult", "title": "Mr", "first_name": "Ada", "last_name": "Obi", "gender": "male" } ], "contact": { "email": "customer@example.com", "phone": "08031234567" }, "requestID": "flight-1001", "preview": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "searchID": { "type": "string", "description": "The `searchID` from [Search Flights](#flight-search). Needed together with `token`.", "example": "FS3A9C41D07B22E8F5A61" }, "token": { "type": "string", "description": "The `token` of the option your customer picked in [Search Flights](#flight-search).", "example": "eyJhbGciOi…" }, "quoteID": { "type": "string", "description": "The `quoteID` from an earlier `preview=true` call. Books at that locked price.", "example": "Q1b2c3d4" }, "passengers": { "type": "array", "items": { "type": "object", "required": [ "type", "title", "first_name", "last_name", "gender" ], "properties": { "type": { "type": "string", "enum": [ "adult", "child", "infant" ] }, "title": { "type": "string" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "country_code": { "type": "string" }, "passport_number": { "type": "string" }, "passport_expiry": { "type": "string" } } }, "description": "One item for each traveller, matching the adults, children and infants you searched. Each has `type` (`adult`, `child` or `infant`), `title` (`Mr`, `Mrs`, `Ms`, `Miss` or `Master`), `first_name`, `last_name`, `gender` (`male` or `female`), and optionally `middle_name` and `country_code` (2 letters, default `NG`). International trips also need `passport_number` and `passport_expiry` (`YYYY-MM-DD`). Names use letters only." }, "contact": { "type": "object", "required": [ "email", "phone" ], "properties": { "email": { "type": "string" }, "phone": { "type": "string" } }, "description": "Who the airline contacts: `email` and `phone` (`080…`, `234…` or `+234…`)." }, "requestID": { "type": "string", "description": "Your own unique reference for this booking, up to 100 characters. Use it later with [Fetch Flight Orders](#flight-orders).", "example": "flight-1001" }, "maxAmount": { "type": "string", "description": "The most you will pay, in naira. If the price is higher you get `PRICE_CHANGED` and nothing is charged.", "example": "100000" }, "preview": { "type": "boolean", "description": "`true` locks and returns the final price (as `quoteID` and `amount`) without booking or charging anything.", "example": true } } }, "example": { "searchID": "FS3A9C41D07B22E8F5A61", "token": "eyJhbGciOi…", "passengers": [ { "type": "adult", "title": "Mr", "first_name": "Ada", "last_name": "Obi", "gender": "male" } ], "contact": { "email": "customer@example.com", "phone": "08031234567" }, "requestID": "flight-1001", "preview": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "transactionID": "TRV261017110002AB12CD34", "amount": 95000, "serviceID": "flight", "amountPaid": 95000, "initialBalance": 500000, "finalBalance": 405000, "date": "2026-10-17T11:00:02+01:00", "api_response": "Your booking is being processed and you have been charged. The result is sent to your webhook as flight.order.updated, or check it with Fetch Flight Orders.", "requestID": "flight-1001", "orderStatus": "processing", "tripType": "oneway", "origin": "LOS", "destination": "ABV", "departureDate": "2026-12-01", "returnDate": null, "airline": "Ibom Air", "journeys": [ { "from": "LOS", "to": "ABV", "departsAt": "2026-12-01T08:00:00", "arrivesAt": "2026-12-01T09:10:00", "duration": "1h10", "stops": 0, "flightNumber": "QI 301", "baggage": "23KG baggage" } ], "passengers": [ { "type": "Adult", "title": "Mr", "firstName": "Ada", "middleName": null, "lastName": "Obi", "gender": "Male", "countryCode": "NG" } ], "contact": { "email": "customer@example.com", "phone": "+2348031234567" }, "amountRefunded": 0, "pnr": null, "tickets": [] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 406, "status": "failed", "description": "PRICE_CHANGED", "api_response": "The price is now ₦98,500.00, above your maxAmount. Nothing was charged. Send the same request with the quoteID in this response to book at the new price.", "quoteID": "Q1b2c3d4", "currentAmount": 98500, "expiresIn": 1700 } } } } } } }, "/api/flight/orders/": { "post": { "tags": [ "Flights" ], "summary": "Fetch Flight Orders", "description": "Returns your flight bookings made through the API. Send a `requestID` or a `transactionID` to get one booking, or send neither to list your last 50. A booking that is still processing is checked again when you look it up (at most every 25 seconds), so this is also how you collect the PNR and e-ticket numbers if you missed the [webhook](#webhooks). It also answers GET.", "operationId": "flightOrders", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "requestID": { "type": "string", "description": "The `requestID` you sent when you booked.", "example": "flight-1001" }, "transactionID": { "type": "string", "description": "The `transactionID` from the booking response.", "example": "TRV261017110002AB12CD34" } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY", "requestID": "flight-1001", "transactionID": "TRV261017110002AB12CD34" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "requestID": { "type": "string", "description": "The `requestID` you sent when you booked.", "example": "flight-1001" }, "transactionID": { "type": "string", "description": "The `transactionID` from the booking response.", "example": "TRV261017110002AB12CD34" } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY", "requestID": "flight-1001", "transactionID": "TRV261017110002AB12CD34" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "orders": [ { "transactionID": "TRV261017110002AB12CD34", "requestID": "flight-1001", "serviceID": "flight", "orderStatus": "completed", "tripType": "oneway", "origin": "LOS", "destination": "ABV", "departureDate": "2026-12-01", "returnDate": null, "airline": "Ibom Air", "journeys": [ { "from": "LOS", "to": "ABV", "departsAt": "2026-12-01T08:00:00", "arrivesAt": "2026-12-01T09:10:00", "duration": "1h10", "stops": 0, "flightNumber": "QI 301", "baggage": "23KG baggage" } ], "passengers": [ { "type": "Adult", "title": "Mr", "firstName": "Ada", "middleName": null, "lastName": "Obi", "gender": "Male", "countryCode": "NG" } ], "contact": { "email": "customer@example.com", "phone": "+2348031234567" }, "amount": 95000, "amountRefunded": 0, "amountPaid": 95000, "pnr": "ABC123", "tickets": [ { "name": "Ada Obi", "type": "ADT", "ticketNumber": "1234567890123" } ], "date": "2026-10-17T11:00:02+01:00" } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "No flight booking found for that reference." } } } } } } }, "/api/store/search/": { "get": { "tags": [ "Store" ], "summary": "Search Products", "description": "Returns a page of products, 20 at a time, with every price in naira, exactly as shown on the Gsubz store. The `scope` decides where you search: `trending` (the default) and `official` are free, `market` searches the whole catalogue by keyword and costs ₦2. Send no parameters at all to get the first page of trending products.\n\n**What is free and what is not.** Free: trending products, the Official Store (with or without a brand), List Categories and Brands, and Official Store product details (IDs that start with `g`). ₦2 per call: `scope=market` search, details of any other product, and supplier products. ₦4: image search. You are charged only when a call returns results. If it returns nothing or fails, your wallet is refunded automatically, and the response shows what you paid in `amountPaid`.\n\nThe Store endpoints use the `Authorization` Bearer header only, and the same upgraded API account as the rest of the API. Each response carries `callID`, our reference for that call (quote it to support), plus `amountPaid` and your wallet balances.\n\nIf you send `q` you must also send `scope`, so that you never pay for a market search by accident. A market search returns up to 5 pages (100 products) for each keyword and filters only work with `scope=market`. Every call is charged, including a repeat of the same request, so keep the results in your own cache.", "operationId": "storeSearch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "`trending` (free, the default), `official` (free, the Gsubz Official Store) or `market` (₦2, searches the whole catalogue). If you send only `brand`, the scope is `official`.", "schema": { "type": "string", "example": "market" } }, { "name": "q", "in": "query", "required": false, "description": "The keyword to search for, up to 100 characters. Required with `scope=market`. With `scope=official` it filters the Official Store. Not used with `trending`. To search by category, use the category name as the keyword.", "schema": { "type": "string", "example": "wireless earbuds" } }, { "name": "brand", "in": "query", "required": false, "description": "A brand `id` from [List Categories and Brands](#store-categories). Returns every product of that brand. Only with `scope=official`.", "schema": { "type": "string", "example": "1" } }, { "name": "page", "in": "query", "required": false, "description": "The page number, starting at 1. Up to 5 for `market` and 80 for `trending`.", "schema": { "type": "string", "example": "1" } }, { "name": "sort", "in": "query", "required": false, "description": "`default`, `sales`, `price_up` or `price_down`. Only with `scope=market`.", "schema": { "type": "string", "example": "sales" } }, { "name": "start_price", "in": "query", "required": false, "description": "Lowest price in naira. Only with `scope=market`.", "schema": { "type": "string", "example": "5000" } }, { "name": "end_price", "in": "query", "required": false, "description": "Highest price in naira. Only with `scope=market`.", "schema": { "type": "string", "example": "20000" } }, { "name": "moq", "in": "query", "required": false, "description": "Only products you can order in this quantity or less. Only with `scope=market`.", "schema": { "type": "string", "example": "2" } }, { "name": "new_arrival", "in": "query", "required": false, "description": "`true` to list new products only. Only with `scope=market`.", "schema": { "type": "string", "example": "true" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "callID": 18452, "scope": "market", "amountPaid": 2, "initialBalance": 5000, "finalBalance": 4998, "date": "2026-10-07T11:20:15+01:00", "api_response": "Search results.", "page": 1, "pageSize": 20, "count": 2, "hasMore": false, "items": [ { "id": "682718261723", "title": "Wireless Bluetooth Earbuds Noise Cancelling", "fullTitle": "Wireless Bluetooth Earbuds Noise Cancelling Headset, Long Battery Life", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fa1.jpg", "priceNgn": 4850, "sold": 1240, "freeShipping": false }, { "id": "701442970035", "title": "TWS Earbuds Touch Control Charging Case", "fullTitle": "TWS Earbuds Touch Control Charging Case", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fb2.jpg", "priceNgn": 3600, "sold": 310, "freeShipping": false } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "No products found. You were not charged.", "callID": 18453 } } } } } } }, "/api/store/image-search/": { "post": { "tags": [ "Store" ], "summary": "Search Products by Image", "description": "Send a link to a photo and get back up to 20 similar products, in the same format as [Search Products](#store-search). It costs ₦4 and you are charged only when it returns results.\n\n`image_url` must be a public `https` link that anyone on the internet can open without logging in. Use a JPG, PNG or WebP photo of at least 100 × 100 pixels and up to 8 MB. We download the photo, so links to private networks are refused. Use a clear photo of one product for the best matches.", "operationId": "storeImageSearch", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "description": "A public https link to the photo.", "example": "https://example.com/photos/earbuds.jpg" } }, "required": [ "image_url" ] }, "example": { "image_url": "https://example.com/photos/earbuds.jpg" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "description": "A public https link to the photo.", "example": "https://example.com/photos/earbuds.jpg" } }, "required": [ "image_url" ] }, "example": { "image_url": "https://example.com/photos/earbuds.jpg" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "callID": 18455, "scope": "market", "amountPaid": 4, "initialBalance": 4998, "finalBalance": 4994, "date": "2026-10-07T11:22:40+01:00", "api_response": "Image search results.", "page": 1, "pageSize": 20, "count": 1, "hasMore": false, "items": [ { "id": "682718261723", "title": "Wireless Bluetooth Earbuds Noise Cancelling", "fullTitle": "Wireless Bluetooth Earbuds Noise Cancelling Headset, Long Battery Life", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fa1.jpg", "priceNgn": 4850, "sold": 1240, "freeShipping": false } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 206, "status": "failed", "description": "INVALID_CONTENT", "api_response": "That link is not an image.", "callID": 18456 } } } } } } }, "/api/store/product/": { "get": { "tags": [ "Store" ], "summary": "Get Product Details", "description": "Returns the full details of one product, with every price in naira. Use an `id` from [Search Products](#store-search). Official Store products (IDs that start with `g`) are free. Any other product costs ₦2, and you are charged only when the product is found.", "operationId": "storeProduct", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The product `id` from a search result, for example `682718261723`, or `g000000001` for an Official Store product.", "schema": { "type": "string", "example": "682718261723" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "callID": 18460, "scope": "market", "amountPaid": 2, "initialBalance": 4994, "finalBalance": 4992, "date": "2026-10-07T11:25:03+01:00", "api_response": "Product details.", "product": { "id": "682718261723", "title": "Wireless Bluetooth Earbuds Noise Cancelling Headset", "media": [ { "type": "video", "url": "https://video.example.com/earbuds.mp4" }, { "type": "image", "url": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fa1.jpg" } ], "priceTiers": [ { "minQty": 2, "priceNgn": 4850 }, { "minQty": 100, "priceNgn": 4300 } ], "minPriceNgn": 4300, "maxPriceNgn": 5100, "moq": 2, "skus": [ { "skuId": "5001", "label": "Black / Standard", "stock": 120, "priceNgn": 4850, "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fk1.jpg", "weightKg": 0.12, "lengthCm": 12, "widthCm": 8, "heightCm": 4, "shippingNgn": { "airFor1Pc": 4276, "airFor5Pcs": 14250, "seaFor1Pc": 990, "seaFor5Pcs": 3300 } } ], "specs": { "Battery": "300mAh", "Bluetooth": "5.3" }, "description": "", "location": "Guangdong Shenzhen", "totalSold": 4321, "freeShipping": false, "supplier": { "id": "sp_Q3ZnR2Fh0uJp9mKcT1xYvWbEoLd8sA" }, "shipping": { "airRatePerKgNgn": 21000, "seaRatePerCbmNgn": 450000, "weightsKg": [ 0.12 ], "volumesCbm": [ 0.000384 ], "estimated": true, "seaOnly": false, "flatAirFeePerItemNgn": null, "note": "Fees for any mix of quantities: POST /api/store/order/ with preview=true. The shipping fee charged is final." } } } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "status": "failed", "description": "CONTENT_NOT_FOUND", "api_response": "Product not found. You were not charged.", "callID": 18461 } } } } } } }, "/api/store/supplier/": { "get": { "tags": [ "Store" ], "summary": "Get Supplier Products", "description": "Returns a page of products from one supplier, in the same format as [Search Products](#store-search). Get the supplier ID from `supplier.id` in [Get Product Details](#store-product). It costs ₦2, charged only when the page has products.", "operationId": "storeSupplier", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The supplier ID from `supplier.id` in [Get Product Details](#store-product). Always start with `sp_`.", "schema": { "type": "string", "example": "sp_Q3ZnR2Fh0uJp9mKcT1xYvWbEoLd8sA" } }, { "name": "page", "in": "query", "required": false, "description": "The page number, starting at 1.", "schema": { "type": "string", "example": "1" } }, { "name": "sort", "in": "query", "required": false, "description": "`default`, `sales`, `price_up`, `price_down`, `time_up` or `time_down`.", "schema": { "type": "string", "example": "sales" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "callID": 18470, "scope": "market", "amountPaid": 2, "initialBalance": 4992, "finalBalance": 4990, "date": "2026-10-07T11:27:30+01:00", "api_response": "Supplier products.", "page": 1, "pageSize": 20, "count": 1, "hasMore": true, "items": [ { "id": "770000000015", "title": "Cotton Casual Shirt", "fullTitle": "Cotton Casual Shirt Short Sleeve", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fsh1.jpg", "priceNgn": 3100, "sold": 65, "freeShipping": false } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 206, "status": "failed", "description": "INVALID_CONTENT", "api_response": "id must be a supplier id from a product (supplier.id).", "callID": 18471 } } } } } } }, "/api/store/categories/": { "get": { "tags": [ "Store" ], "summary": "List Categories and Brands", "description": "Returns the categories shown on the Gsubz store and the Official Store brands. It is free. No parameters: it always returns everything in one response.\n\nA category is only a group of related search words. To get a category's products, send its `name` as `q` to [Search Products](#store-search) with `scope=market`. You are free to build your own categories from keywords instead. To get a brand's products, send its `id` as `brand` with `scope=official`.", "operationId": "storeCategories", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 200, "status": "successful", "callID": 18480, "amountPaid": 0, "initialBalance": 4990, "finalBalance": 4990, "date": "2026-10-07T11:30:02+01:00", "api_response": "Categories and brands.", "categories": [ { "name": "Women's Clothing", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fc1.jpg", "children": [ { "name": "Women's T-Shirts", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fc2.jpg", "children": [] }, { "name": "Women's Casual Pants", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fc3.jpg", "children": [ { "name": "Casual Pants", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fc4.jpg", "children": [] } ] } ] } ], "brands": [ { "id": 1, "name": "Apple", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fapple.jpg", "products": 24 } ] } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/store/order/": { "get": { "tags": [ "Store" ], "summary": "List Pickup Stations / Get Orders", "description": "This URL does several things. The `action` field picks which:\n\n- **List Pickup Stations**: Every Store order is delivered to a pickup station, where your customer collects it. This returns the stations by state, with the delivery fee for each parcel size. Send the `state` and the station `name` exactly as returned when you [Place an Order](#store-order). It is free.\n- **Get Orders**: Returns one order when you send `order_id` or `reference`, in the same format as [Place an Order](#store-order). Without them it returns your API orders, newest first, 20 at a time. It is free. Use it to check an order after a timeout, or if you missed a [webhook](#webhooks).", "operationId": "apiStoreOrderGet", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": false, "description": "Always `stations`.", "schema": { "type": "string", "example": "stations" } }, { "name": "state", "in": "query", "required": false, "description": "Only this state. Leave it out to get every state.", "schema": { "type": "string", "example": "Lagos" } }, { "name": "order_id", "in": "query", "required": false, "description": "The `orderId` from Place an Order.", "schema": { "type": "string", "example": "5231" } }, { "name": "reference", "in": "query", "required": false, "description": "Or your own `reference`.", "schema": { "type": "string", "example": "ORDER-10045" } }, { "name": "page", "in": "query", "required": false, "description": "Page number when listing, starting at 1.", "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "storeStations": { "summary": "List Pickup Stations", "value": { "code": 200, "status": "successful", "callID": 18490, "scope": "stations", "amountPaid": 0, "initialBalance": 50000, "finalBalance": 50000, "date": "2026-10-13T10:02:11+01:00", "api_response": "Pickup stations.", "parcelSizes": { "small": { "maxKg": 4, "maxCbm": 0.0384 }, "medium": { "maxKg": 12, "maxCbm": 0.1536 }, "large": { "maxKg": null, "maxCbm": null } }, "states": [ { "state": "Lagos", "stations": [ { "name": "Ikota", "address": "Ikota Shopping Complex, Lekki", "landmark": "Near VGC", "phone": "08000000001", "hours": { "weekdays": "8am - 6pm", "weekends": "9am - 3pm" }, "map": "https://maps.example.com/ikota", "deliveryFee": { "smallNgn": 2400, "mediumNgn": 4200, "largeNgn": 6800, "days": "2-4 days" } } ] } ] } }, "storeOrders": { "summary": "Get Orders", "value": { "code": 200, "status": "successful", "callID": 18510, "scope": "orders", "amountPaid": 0, "initialBalance": 19324, "finalBalance": 19324, "date": "2026-10-14T09:00:00+01:00", "api_response": "Order details.", "order": { "orderId": 5231, "reference": "ORDER-10045", "items": [] } } } } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Store" ], "summary": "Place an Order / Cancel an Order / Pay Shipping", "description": "This URL does several things. The `action` field picks which:\n\n- **Place an Order**: Places an order for one or more products and pays for it from your wallet. Prices, the service fee, shipping and the delivery fee are worked out exactly as on the Gsubz store. Send `preview=true` first to get the full price without paying. API orders are always packed without Gsubz branding, so you can ship to your own customers. Send the body as JSON (recommended) or as form fields.\n- **Cancel an Order**: Cancels an order and refunds your wallet at once. You can cancel within 2 hours of placing the order, and only items that are still `PAID` (not yet being processed). Leave out `item_id` to cancel the whole order: this works only when no item is being processed yet. Otherwise cancel items one by one. Each cancelled item refunds its price, its service fee and any shipping paid. The delivery fee is refunded when the last item of the order is cancelled.\n- **Pay Shipping**: When we weigh an item whose shipping was `pending`, or the weight turns out higher than listed, its `shipping.status` becomes `due` and you get a [webhook](#webhooks) with the new weight, size and fee. This pays everything due on the order from your wallet (or only one item with `item_id`). Items move to processing once their shipping is paid. Nothing waits on a deadline: an item stays on hold until it is paid.", "operationId": "apiStoreOrderPost", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StoreOrderRequest" }, { "$ref": "#/components/schemas/StoreOrderCancelRequest" }, { "$ref": "#/components/schemas/StoreOrderPayShippingRequest" } ] }, "examples": { "storeOrder": { "summary": "Place an Order", "value": { "reference": "ORDER-10045", "items": [ { "product_id": "682718261723", "sku_id": "5001", "quantity": 2, "price": 4850 } ], "shipping_method": "air", "state": "Lagos", "station": "Ikota", "first_name": "Ada", "last_name": "Obi", "phone": "08031234567", "preview": true } }, "storeOrderCancel": { "summary": "Cancel an Order", "value": { "action": "cancel", "order_id": "5231", "item_id": "88120" } }, "storeOrderPayShipping": { "summary": "Pay Shipping", "value": { "action": "pay_shipping", "order_id": "5231" } } } }, "multipart/form-data": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StoreOrderRequest" }, { "$ref": "#/components/schemas/StoreOrderCancelRequest" }, { "$ref": "#/components/schemas/StoreOrderPayShippingRequest" } ] }, "examples": { "storeOrder": { "summary": "Place an Order", "value": { "reference": "ORDER-10045", "items": [ { "product_id": "682718261723", "sku_id": "5001", "quantity": 2, "price": 4850 } ], "shipping_method": "air", "state": "Lagos", "station": "Ikota", "first_name": "Ada", "last_name": "Obi", "phone": "08031234567", "preview": true } }, "storeOrderCancel": { "summary": "Cancel an Order", "value": { "action": "cancel", "order_id": "5231", "item_id": "88120" } }, "storeOrderPayShipping": { "summary": "Pay Shipping", "value": { "action": "pay_shipping", "order_id": "5231" } } } }, "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StoreOrderRequest" }, { "$ref": "#/components/schemas/StoreOrderCancelRequest" }, { "$ref": "#/components/schemas/StoreOrderPayShippingRequest" } ] }, "examples": { "storeOrder": { "summary": "Place an Order", "value": { "reference": "ORDER-10045", "items": [ { "product_id": "682718261723", "sku_id": "5001", "quantity": 2, "price": 4850 } ], "shipping_method": "air", "state": "Lagos", "station": "Ikota", "first_name": "Ada", "last_name": "Obi", "phone": "08031234567", "preview": true } }, "storeOrderCancel": { "summary": "Cancel an Order", "value": { "action": "cancel", "order_id": "5231", "item_id": "88120" } }, "storeOrderPayShipping": { "summary": "Pay Shipping", "value": { "action": "pay_shipping", "order_id": "5231" } } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "storeOrder": { "summary": "Place an Order", "value": { "code": 200, "status": "successful", "callID": 18500, "scope": "place", "amountPaid": 30676, "initialBalance": 50000, "finalBalance": 19324, "date": "2026-10-13T10:05:40+01:00", "api_response": "Order placed.", "order": { "orderId": 5231, "reference": "ORDER-10045", "dropship": true, "createdAt": "2026-10-13T10:05:40+01:00", "cancellableUntil": "2026-10-13T12:05:40+01:00", "shippingMethod": "air", "recipient": { "firstName": "Ada", "lastName": "Obi", "phone": "08031234567" }, "pickupStation": { "name": "Ikota", "address": "Ikota Shopping Complex, Lekki", "state": "Lagos" }, "amounts": { "itemsNgn": 9700, "serviceFeeNgn": 1900, "shippingPaidNgn": 16676, "shippingDueNgn": 0, "deliveryNgn": 2400 }, "items": [ { "itemId": 88120, "productId": "682718261723", "skuId": "5001", "title": "Wireless Bluetooth Earbuds Noise Cancelling Headset", "variation": "Black / Standard", "image": "https://gsubz.com/store/image_proxy.php?url=https%3A%2F%2Fimg.example.com%2Fk1.jpg", "quantity": 2, "unitPriceNgn": 4850, "lineTotalNgn": 9700, "serviceFeeNgn": 1900, "status": "PAID", "shipping": { "method": "air", "weightKg": null, "volumeCbm": null, "status": "paid", "unitNgn": 8338, "totalNgn": 16676, "paidNgn": 16676, "dueNgn": 0 }, "trackingNumber": null, "cancellable": true, "cancelledAt": null } ] } } }, "storeOrderCancel": { "summary": "Cancel an Order", "value": { "code": 200, "status": "successful", "callID": 18520, "scope": "cancel", "amountPaid": 0, "initialBalance": 19324, "finalBalance": 50000, "date": "2026-10-13T10:40:12+01:00", "api_response": "1 item(s) cancelled. ₦30,676.00 was refunded to your wallet.", "refundedNgn": 30676, "cancelled": [ { "itemId": 88120, "refundNgn": 30676, "itemNgn": 9700, "serviceFeeNgn": 1900, "shippingNgn": 16676, "deliveryNgn": 2400 } ], "order": { "orderId": 5231, "reference": "ORDER-10045", "items": [] } } }, "storeOrderPayShipping": { "summary": "Pay Shipping", "value": { "code": 200, "status": "successful", "callID": 18530, "scope": "pay_shipping", "amountPaid": 4356, "initialBalance": 19324, "finalBalance": 14968, "date": "2026-10-16T14:20:00+01:00", "api_response": "Shipping paid for 1 item(s).", "paid": [ { "id": 88121, "amount": 4356 } ], "order": { "orderId": 5231, "reference": "ORDER-10045", "items": [] } } } } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/verify/": { "post": { "tags": [ "Transactions" ], "summary": "Fetch Transaction Status", "description": "Check the status and response of a purchase using the `requestID` you sent when you made it, or the `transactionID` GSUBZ returned. Use this whenever a purchase request times out or returns no response, before you try again. Electricity purchases also return their `token`, and social media orders return their live progress.\n\nA transaction can return HTTP 200 and still have failed. Always check the `status` field, not just the response code.\n\nSend **either** `requestID` **or** `transactionID`: whichever you have. Only your own transactions are searched. If you send neither, the request is refused with code `400`.\n\n**Electricity.** The response carries `token`, the meter token. If the token was not available when you bought, it is fetched for you now, so a purchase whose token you never received can be recovered by calling this endpoint. If the token is still not ready, `token` is left out: try again in a minute. A failed or refunded purchase never has a token.\n\n**Social media.** The response carries `order`: the live progress of the order, with `status`, `start_count` (the count when the order started) and `remains` (how many are still to be delivered). It is left out if the progress cannot be read right now.", "operationId": "transactionStatus", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "requestID": { "type": "string", "description": "The `requestID` you passed during the purchase. Send this or `transactionID`.", "example": "7wbd7wbdw7d72g6vd" }, "transactionID": { "type": "string", "description": "The `transactionID` from the purchase response. Send this or `requestID`.", "example": "3574357094" } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY", "requestID": "7wbd7wbdw7d72g6vd" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "requestID": { "type": "string", "description": "The `requestID` you passed during the purchase. Send this or `transactionID`.", "example": "7wbd7wbdw7d72g6vd" }, "transactionID": { "type": "string", "description": "The `transactionID` from the purchase response. Send this or `requestID`.", "example": "3574357094" } }, "required": [ "api" ] }, "example": { "api": "YOUR_API_KEY", "requestID": "7wbd7wbdw7d72g6vd" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": "200", "status": "success", "description": "TRANSACTION_SUCCESSFUL", "transaction_id": "3574357094", "amount": "1100", "api_response": "Dear Customer, You have successfully shared 1GB Data to 2349063648020. Your SME data balance is 28955.68GB expires 30/01/2024. Thankyou" } } } }, "default": { "description": "Error. See the Errors section: the failure is described in `code`, `description` and `api_response`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "404", "description": "CONTENT_NOT_FOUND_API_OR_NOT_FOUND", "status": "TRANSACTION_FAILED" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your GSUBZ API key (it starts with `ap_`). Also send the same key in the `api` body field on endpoints that list it." } }, "schemas": { "BuyDataRequest": { "type": "object", "properties": { "serviceID": { "type": "string", "description": "The data service ID, for example `mtn_sme`.", "example": "mtn_sme" }, "plan": { "type": "string", "description": "The plan value from [Get Plans](#plans) for this service.", "example": "260" }, "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "amount": { "type": "string", "description": "Send as an empty string. The price is set by the plan.", "example": "" }, "phone": { "type": "string", "description": "The phone number to receive the data.", "example": "08031234567" }, "requestID": { "type": "string", "description": "Your own unique reference for this order (for example your order ID). Use it later with [Fetch Transaction Status](#transaction-status).", "example": "8dhbc8w7huwh8hw9hew9" } }, "required": [ "serviceID", "plan", "api", "amount", "phone" ], "title": "Buy Data" }, "BuyAirtimeRequest": { "type": "object", "properties": { "serviceID": { "type": "string", "description": "`mtn`, `airtel`, `etisalat` (9mobile) or `glo`.", "example": "mtn" }, "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "amount": { "type": "string", "description": "Amount of airtime in naira. The minimum is ₦100.", "example": "100" }, "phone": { "type": "string", "description": "The phone number to receive the airtime.", "example": "08031234567" }, "requestID": { "type": "string", "description": "Your own unique reference for this order (for example your order ID). Use it later with [Fetch Transaction Status](#transaction-status).", "example": "8dhbc8w7huwh8hw9hew9" } }, "required": [ "serviceID", "api", "amount", "phone" ], "title": "Buy Airtime" }, "BuyCableRequest": { "type": "object", "properties": { "serviceID": { "type": "string", "description": "`dstv`, `gotv` or `startimes`.", "example": "gotv" }, "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "variation_code": { "type": "string", "description": "The package from [Get Plans](#plans) (`service=gotv`, `dstv` or `startimes`).", "example": "gotv-smallie" }, "phone": { "type": "string", "description": "Customer phone number. Can be any valid number.", "example": "08031234567" }, "amount": { "type": "string", "description": "Send as an empty string. The price is set by the plan.", "example": "" }, "customerID": { "type": "string", "description": "The IUC or smartcard number of the decoder.", "example": "0000000000" }, "requestID": { "type": "string", "description": "Your own unique reference for this order (for example your order ID). Use it later with [Fetch Transaction Status](#transaction-status).", "example": "8dhbc8w7huwh8hw9hew9" } }, "required": [ "serviceID", "api", "variation_code", "phone", "amount", "customerID" ], "title": "Buy TV / Decoder / Cable Sub" }, "BuyElectricRequest": { "type": "object", "properties": { "serviceID": { "type": "string", "description": "The distribution company service ID. See the list below.", "example": "kaduna_electric" }, "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "phone": { "type": "string", "description": "Customer phone number. Can be any valid number.", "example": "08031234567" }, "customerID": { "type": "string", "description": "The meter number.", "example": "00000000000" }, "amount": { "type": "string", "description": "Amount of electricity to buy, in naira.", "example": "1100" }, "variation_code": { "type": "string", "description": "`prepaid` or `postpaid`.", "example": "prepaid" }, "requestID": { "type": "string", "description": "Your own unique reference for this order (for example your order ID). Use it later with [Fetch Transaction Status](#transaction-status).", "example": "8dhbc8w7huwh8hw9hew9" } }, "required": [ "serviceID", "api", "phone", "customerID", "amount", "variation_code" ], "title": "Buy Electric Token" }, "BuyExamPinRequest": { "type": "object", "properties": { "serviceID": { "type": "string", "description": "`waec`, `neco` or `nabteb`.", "example": "waec" }, "plan": { "type": "string", "description": "The plan for the exam service. There is one plan per service; for WAEC it is `waecdirect`.", "example": "waecdirect" }, "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "amount": { "type": "string", "description": "Send as an empty string. The price is set by the plan.", "example": "" }, "phone": { "type": "string", "description": "Customer phone number.", "example": "08031234567" }, "requestID": { "type": "string", "description": "Your own unique reference for this order. Use it later with [Fetch Transaction Status](#transaction-status).", "example": "87dfhw8dbw8e7hw9d9dh" } }, "required": [ "serviceID", "plan", "api", "amount", "phone" ], "title": "Buy Exam Pin" }, "BuySocialRequest": { "type": "object", "properties": { "serviceID": { "type": "string", "description": "Always `socials`.", "example": "socials" }, "plan": { "type": "string", "description": "The plan value from [Get Plans](#plans) (`service=socials`).", "example": "179" }, "api": { "type": "string", "description": "Your API key. Send the same key you use in the `Authorization` header.", "example": "YOUR_API_KEY" }, "amount": { "type": "string", "description": "Send as an empty string. The price is set by the plan.", "example": "" }, "link": { "type": "string", "description": "The profile or post URL the order should be delivered to.", "example": "https://instagram.com/gsubzonline" }, "quantity": { "type": "integer", "description": "How many to deliver. Must be a positive whole number.", "example": 1000 }, "requestID": { "type": "string", "description": "Your own unique reference for this order (for example your order ID). Use it later with [Fetch Transaction Status](#transaction-status).", "example": "8dhbc8w7huwh8hw9hew9" } }, "required": [ "serviceID", "plan", "api", "amount", "link", "quantity" ], "title": "Buy Social Media Service" }, "StoreOrderRequest": { "type": "object", "properties": { "reference": { "type": "string", "description": "Your own unique ID for this order: letters, numbers, `.` `-` `_`, up to 64 characters.", "example": "ORDER-10045" }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "sku_id", "quantity" ], "properties": { "product_id": { "type": "string" }, "sku_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "price": { "type": "integer", "description": "Expected unit price in naira (optional)." } } }, "description": "The products. Each item has `product_id` (from [Search Products](#store-search)), `sku_id` (a `skuId` from [Get Product Details](#store-product); Official Store products use their own `skuId` too), `quantity`, and optionally `price`: the naira unit price you expect. If the price has gone up, nothing is charged and you get `PRICE_CHANGED` with the new price. Up to 50 items. A product with a minimum order (`moq`) needs at least that many pieces across its variants." }, "shipping_method": { "type": "string", "description": "`air` or `sea`, for the whole order. Not needed when every item is an Official Store product (their shipping is already in the price).", "example": "air" }, "state": { "type": "string", "description": "The pickup station's state, from [List Pickup Stations](#store-stations).", "example": "Lagos" }, "station": { "type": "string", "description": "The pickup station's `name`, from [List Pickup Stations](#store-stations).", "example": "Ikota" }, "first_name": { "type": "string", "description": "First name of the person who collects the order.", "example": "Ada" }, "last_name": { "type": "string", "description": "Last name of the person who collects the order.", "example": "Obi" }, "phone": { "type": "string", "description": "Their phone number. The pickup station contacts this number.", "example": "08031234567" }, "preview": { "type": "boolean", "description": "`true` returns the full price (as `quote`) without placing or paying for anything.", "example": true } }, "required": [ "reference", "items", "state", "station", "first_name", "last_name", "phone" ], "title": "Place an Order" }, "StoreOrderCancelRequest": { "type": "object", "properties": { "action": { "type": "string", "description": "Always `cancel`.", "example": "cancel" }, "order_id": { "type": "integer", "description": "The order to cancel. You can send `reference` instead.", "example": 5231 }, "reference": { "type": "string", "description": "Your own reference, instead of `order_id`.", "example": "ORDER-10045" }, "item_id": { "type": "integer", "description": "Cancel only this item (`itemId`). Leave it out to cancel the whole order.", "example": 88120 } }, "required": [ "action" ], "title": "Cancel an Order" }, "StoreOrderPayShippingRequest": { "type": "object", "properties": { "action": { "type": "string", "description": "Always `pay_shipping`.", "example": "pay_shipping" }, "order_id": { "type": "integer", "description": "The order. You can send `reference` instead.", "example": 5231 }, "reference": { "type": "string", "description": "Your own reference, instead of `order_id`.", "example": "ORDER-10045" }, "item_id": { "type": "integer", "description": "Pay only this item. Leave it out to pay everything due on the order.", "example": 88121 } }, "required": [ "action" ], "title": "Pay Shipping" }, "TransactionResponse": { "type": "object", "description": "Standard response for a purchase. Check `status` first: `successful` means delivered, `failed` means it did not go through.", "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "successful", "description": "`successful` means delivered. `failed` means it did not go through." }, "transactionID": { "type": "integer", "description": "GSUBZ transaction reference." }, "amount": { "type": "number", "description": "Purchase value in naira." }, "phone": { "type": "string", "description": "Phone number the purchase was for, where the service uses one." }, "serviceID": { "type": "string" }, "amountPaid": { "type": "number", "description": "Amount deducted from your wallet at your API price, in naira." }, "initialBalance": { "type": "number", "description": "Wallet balance before the purchase." }, "finalBalance": { "type": "number", "description": "Wallet balance after the purchase." }, "date": { "type": "string", "format": "date-time", "description": "ISO 8601, West Africa Time (+01:00)." }, "api_response": { "type": "string", "description": "Message returned by the network or provider." } } }, "Error": { "type": "object", "description": "A failed request. `status` is `failed`, and the problem is identified by `code` and `description`: 200 successful, 204 REQUIRED_CONTENT_NOT_SENT, 400 REQUIRED_CONTENT_REQUESTID_IS_EMPTY, 206 INVALID_CONTENT, 401 INVALID_PLAN, 401 INVALID_API_OR_NOT_FOUND, 402 INSUFFICIENT_BALANCE, 404 CONTENT_NOT_FOUND, 405 REQUEST_METHOD_NOT_IN_POST, 406 SERVICE_DISABLED, 406 INVALID_ARGUMENTS_DUPLICATE_REQUEST_ID, 406 NOT_CANCELLABLE, 404 PLAYER_NOT_FOUND, 406 OUT_OF_STOCK, 406 PRICE_CHANGED, 206 REGION_MISMATCH, 406 ORDER_FAILED, 406 REQUEST_IN_PROGRESS, 206 BELOW_MINIMUM_ORDER, 406 SEARCH_EXPIRED, 406 QUOTE_EXPIRED, 406 FARE_UNAVAILABLE, 406 BOOKING_FAILED, 406 CANCEL_NOT_ALLOWED, 406 NOTHING_DUE, 406 ACCOUNT_BLOCKED, 407 Chat Admin to get upgraded before using our API, Thank you!, 429 TOO_MANY_REQUESTS, 500 SERVER_ERROR, 502 GATEWAY_ERROR.", "properties": { "code": { "type": "integer", "example": 402 }, "status": { "type": "string", "example": "INSUFFICIENT_BALANCE" }, "description": { "type": "string", "example": "INSUFFICIENT_BALANCE" }, "api_response": { "type": "string", "description": "Plain-words explanation of what went wrong." } } } } } }