{ "openapi": "3.1.0", "info": { "title": "Datashop API", "version": "2026-08-12", "description": "Public API for wallet balance, product lookup, customer verification, purchases, and transaction reconciliation." }, "servers": [ { "url": "https://app.datashop.africa", "description": "Production" } ], "security": [ { "bearerApiKey": [] } ], "tags": [ { "name": "Wallet", "description": "Wallet balance." }, { "name": "Products and services", "description": "Service, provider, and product catalog endpoints." }, { "name": "Purchases", "description": "Purchase execution." }, { "name": "Verification", "description": "Customer verification for products that require validation." }, { "name": "Transactions", "description": "Transaction status and history." } ], "paths": { "/api/v2/account/wallet-balance": { "get": { "operationId": "getWalletBalance", "tags": [ "Wallet" ], "summary": "Get wallet balance", "description": "Check the spendable wallet balance available for new API purchases.", "responses": { "200": { "description": "Wallet balance returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalanceResponse" }, "examples": { "ok": { "value": { "status": true, "message": "Wallet fetched successfully", "data": { "balance": 12500 } } } } } } }, "400": { "description": "Request is not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthenticated": { "value": { "status": false, "message": "Error message" } } } } } } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/account/wallet-balance\", {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data.balance);" } ] } }, "/api/v2/get-services": { "get": { "operationId": "getServices", "tags": [ "Products and services" ], "summary": "List services", "description": "Start product discovery by listing the services your account can sell.", "responses": { "200": { "description": "Services returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceListResponse" }, "examples": { "ok": { "value": { "status": true, "message": "Services fetched successfully.", "data": [ "airtime", "data", "electricity", "tv" ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/get-services\", {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data);" } ] } }, "/api/v2/get-providers": { "get": { "operationId": "getProviders", "tags": [ "Products and services" ], "summary": "List providers", "description": "List providers for a selected service before loading products.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "examples": [ "tv" ], "example": "tv" }, "description": "Service returned by List services. For example, tv may return DSTV, GOTV, and Startimes; data may return MTN, Airtel, Glo, and 9mobile.", "example": "tv" } ], "responses": { "200": { "description": "Providers returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderListResponse" }, "examples": { "tv": { "summary": "TV providers", "value": { "status": true, "message": "Providers fetched successfully.", "data": [ "DSTV", "GOTV", "STARTIMES" ] } }, "data": { "summary": "Data providers", "value": { "status": true, "message": "Providers fetched successfully.", "data": [ "MTN", "AIRTEL", "GLO", "9MOBILE" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/get-providers?service=tv\", {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data);" } ] } }, "/api/v2/get-products": { "get": { "operationId": "getProducts", "tags": [ "Products and services" ], "summary": "List products", "description": "Load products available for purchase by service, provider, or both.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "examples": [ "data" ] }, "description": "Service returned by List services. Required when provider is not supplied." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "examples": [ "MTN" ] }, "description": "Provider returned by List providers. Required when service is not supplied." } ], "responses": { "200": { "description": "Products returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" }, "examples": { "data": { "summary": "Data products", "value": { "status": true, "message": "Products fetched successfully.", "data": [ { "service": "data", "product_name": "mtn-share-weekly-1gb", "provider": "MTN", "category": "weekly", "sub_category": "share", "description": "1GB weekly data bundle", "quantity": "1GB", "validity": "7 days", "fixed_price": 400, "amount_required": false, "require_validation": false, "available": true } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/get-products?service=tv&provider=DSTV\", {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data);" } ] } }, "/api/v2/products/{product_name}": { "get": { "operationId": "getProductDetail", "tags": [ "Products and services" ], "summary": "Get product detail", "description": "Get the current price, availability, and validation requirement before checkout.", "parameters": [ { "name": "product_name", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "mtn-share-weekly-1gb" ] }, "description": "Product name returned by GET /api/v2/get-products." } ], "responses": { "200": { "description": "Product returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }, "examples": { "fixedPrice": { "summary": "Fixed-price product", "value": { "status": true, "message": "Product fetched successfully.", "data": { "service": "data", "product_name": "mtn-share-weekly-1gb", "provider": "MTN", "category": "weekly", "sub_category": "share", "description": "1GB weekly data bundle", "quantity": "1GB", "validity": "7 days", "fixed_price": 400, "amount_required": false, "require_validation": false, "available": true } } }, "openPrice": { "summary": "Open-price product", "value": { "status": true, "message": "Product fetched successfully.", "data": { "service": "airtime", "product_name": "mtn-airtime", "provider": "MTN", "category": "AIRTIME", "sub_category": null, "description": "MTN airtime top-up", "quantity": null, "validity": null, "fixed_price": 0, "amount_required": true, "require_validation": false, "available": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Product was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notFound": { "value": { "status": false, "message": "Product not found." } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/products/mtn-share-weekly-1gb\", {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data);" } ] } }, "/api/v2/verification": { "post": { "operationId": "verifyCustomerIdentifier", "tags": [ "Verification" ], "summary": "Verify customer identifier", "description": "Confirm customer details before payment when a product requires validation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" }, "examples": { "tv": { "value": { "customer_id": "1234567890", "product_name": "dstv-padi" } } } } } }, "responses": { "200": { "description": "Verification completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" }, "examples": { "ok": { "value": { "status": true, "message": "Verification completed successfully.", "data": { "verified": true, "customer_id": "1234567890", "customer_name": "Umar Yahaya" } } } } } } }, "400": { "description": "Required customer_id is missing or network verification failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "networkFailed": { "value": { "message": "Number is not eligible for this bundle", "status": false } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/verification\", {\n method: \"POST\",\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\",\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify({\n customer_id: \"1234567890\",\n product_name: \"dstv-padi\"\n })\n});\n\nconst result = await response.json();\n\nconsole.log(result.data);" } ] } }, "/api/v2/purchase": { "post": { "operationId": "createPurchase", "tags": [ "Purchases" ], "summary": "Create purchase", "description": "Submit a purchase with the customer identifier, product name, and reference.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseRequest" }, "examples": { "async": { "value": { "customer_id": "08030000000", "product_name": "mtn-share-weekly-1gb", "reference": "merchant-ref-20260812001" } } } } } }, "responses": { "200": { "description": "Purchase completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" }, "examples": { "ok": { "value": { "status": true, "message": "Purchase processed successfully.", "data": { "reference": "merchant-ref-20260812001", "customer_id": "08030000000", "service": "data", "provider": "MTN", "product_name": "mtn-share-weekly-1gb", "quantity": "1GB", "paid_amount": 400, "transaction_status": "successful", "remark": "Purchase successful" } } }, "electricity": { "value": { "status": true, "message": "Purchase processed successfully.", "data": { "reference": "merchant-ref-8905fff6767", "customer_id": "45705225097", "service": "electricity", "provider": "Jos Electric", "product_name": "jos-electric-prepaid", "quantity": 1000, "paid_amount": 990, "transaction_status": "successful", "token": "7060-8360-1787-0933-6869", "units": "4.5", "meter_number": "45705225097", "customer_name": "UMAR MOHD AWWAL", "customer_address": "NEW MILE 3", "disco": "Jos Electric - JED", "remark": "7060-8360-1787-0933-6869\n\n(4.5 KWH)" } } } } } } }, "202": { "description": "ACK: purchase accepted into the async processing queue. This confirms Datashop accepted the request, not that delivery has completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" }, "examples": { "accepted": { "value": { "status": true, "message": "Purchase is processing.", "data": { "reference": "merchant-ref-20260812001", "customer_id": "08030000000", "service": "data", "provider": "MTN", "product_name": "mtn-share-weekly-1gb", "quantity": "1GB", "paid_amount": 400, "transaction_status": "processing" } } } } } } }, "400": { "description": "Validation failed or provider returned a final failure in wait mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment amount or wallet balance is insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Reference already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "duplicateReference": { "value": { "message": "Transaction with this reference already exists" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/purchase\", {\n method: \"POST\",\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\",\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify({\n customer_id: \"08030000000\",\n product_name: \"mtn-share-weekly-1gb\",\n reference: \"merchant-ref-20260812001\"\n })\n});\n\nconst result = await response.json();\n\nconsole.log(result.data);" } ] } }, "/api/v2/transactions/{reference}": { "get": { "operationId": "getTransactionStatus", "tags": [ "Transactions" ], "summary": "Get transaction status", "description": "Check the current status and receipt details for one purchase reference.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "minLength": 15, "maxLength": 40, "examples": [ "merchant-ref-0001" ] }, "description": "Purchase reference supplied to POST /api/v2/purchase." } ], "responses": { "200": { "description": "Transaction returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatusResponse" }, "examples": { "ok": { "value": { "status": true, "message": "Transaction fetched successfully.", "data": { "reference": "merchant-ref-20260812001", "service": "data", "remark": "Purchase successful", "product_name": "mtn-share-weekly-1gb", "provider": "MTN", "customer_id": "08030000000", "paid_amount": 400, "requery_queued": false, "transaction_status": "successful" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const reference = \"merchant-ref-20260812001\";\n\nconst response = await fetch(`https://app.datashop.africa/api/v2/transactions/${reference}`, {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data.transaction_status);" } ] } }, "/api/v2/account/transactions": { "get": { "operationId": "listTransactionHistory", "tags": [ "Transactions" ], "summary": "List transaction history", "description": "List paginated transactions for receipts, support, and reconciliation.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Page size. Maximum is 100." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tokenized search across reference, product, provider, customer, status, remark, and amount." }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact transaction reference filter." }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Include transactions created on or after this date." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Include transactions created on or before this date." } ], "responses": { "200": { "description": "History returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionHistoryResponse" }, "examples": { "ok": { "value": { "status": true, "message": "Transactions fetched successfully.", "data": { "transactions": [ { "reference": "merchant-ref-20260812001", "service": "data", "product_name": "mtn-share-weekly-1gb", "provider": "MTN", "customer_id": "08030000000", "paid_amount": 400, "created_at": "2026-08-12T10:00:00.000Z", "transaction_status": "successful" } ], "pagination": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch(\"https://app.datashop.africa/api/v2/account/transactions?page=1&limit=20\", {\n headers: {\n Authorization: \"Bearer YOUR_API_KEY\"\n }\n});\n\nconst result = await response.json();\n\nconsole.log(result.data.transactions);" } ] } } }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Datashop API key", "description": "Use Authorization: Bearer ." } }, "responses": { "BadRequest": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The requested resource was not found for the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "Datashop could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "WalletBalanceResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": false, "properties": { "balance": { "type": "number", "description": "Available balance for purchases." } } } }, "additionalProperties": false }, "VerificationRequest": { "type": "object", "required": [ "customer_id", "product_name" ], "properties": { "customer_id": { "type": "string", "description": "Phone number, meter number, smartcard number, or other customer identifier." }, "product_name": { "type": "string", "description": "Product value returned by GET /api/v2/get-products." } }, "additionalProperties": false }, "VerificationResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "verified": { "type": "boolean" }, "customer_id": { "type": "string" }, "customer_name": { "type": "string" }, "provider": { "type": "string" } } } }, "additionalProperties": false }, "PurchaseRequest": { "type": "object", "required": [ "customer_id", "product_name", "reference" ], "properties": { "customer_id": { "type": "string", "description": "Recipient phone number, meter number, smartcard number, or customer identifier." }, "product_name": { "type": "string", "description": "Product value returned by GET /api/v2/get-products." }, "reference": { "type": "string", "minLength": 15, "maxLength": 40, "description": "Unique merchant transaction reference." }, "amount": { "type": "number", "exclusiveMinimum": 0, "description": "Required only for open-price products where fixed_price is 0, such as airtime. Fixed-price products use the catalog price automatically." } }, "additionalProperties": false }, "PurchaseResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "reference": { "type": "string" }, "customer_id": { "type": "string", "description": "Recipient phone number, meter number, smartcard number, or customer identifier." }, "service": { "type": "string" }, "provider": { "type": "string" }, "product_name": { "type": "string", "description": "Product identifier used for the purchase." }, "quantity": { "type": [ "string", "number", "null" ], "description": "Product quantity or open-price amount label." }, "paid_amount": { "type": "number", "description": "Amount reserved or paid for the purchase." }, "transaction_status": { "type": "string", "enum": [ "successful", "processing", "failed" ], "description": "Public transaction status." }, "remark": { "type": "string" }, "token": { "type": "string", "description": "Electricity token for prepaid meter purchases." }, "units": { "type": "string", "description": "Electricity units credited." }, "meter_number": { "type": "string" }, "customer_name": { "type": "string" }, "customer_address": { "type": "string" }, "disco": { "type": "string" }, "exchange_reference": { "type": "string" }, "transaction_date": { "type": "string" } } } }, "additionalProperties": false }, "TransactionStatusResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Transaction" } }, "additionalProperties": false }, "TransactionHistoryResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": false, "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "additionalProperties": false }, "Transaction": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "string" }, "service": { "type": "string" }, "product_name": { "type": "string" }, "quantity": { "type": [ "string", "number", "null" ] }, "provider": { "type": "string" }, "customer_id": { "type": "string" }, "paid_amount": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "requery_queued": { "type": "boolean" }, "transaction_status": { "type": "string", "enum": [ "successful", "processing", "failed" ], "description": "Public transaction status." }, "remark": { "type": "string" }, "token": { "type": "string", "description": "Electricity token for prepaid meter purchases." }, "units": { "type": "string", "description": "Electricity units credited." }, "meter_number": { "type": "string" }, "customer_name": { "type": "string" }, "customer_address": { "type": "string" }, "disco": { "type": "string" }, "exchange_reference": { "type": "string" }, "transaction_date": { "type": "string" } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string" } } }, "PublicProduct": { "type": "object", "properties": { "service": { "type": "string", "description": "API service." }, "product_name": { "type": "string", "description": "Product name used when creating a purchase." }, "provider": { "type": "string", "description": "Product provider." }, "category": { "type": [ "string", "null" ], "description": "Product category." }, "sub_category": { "type": [ "string", "null" ], "description": "Product subcategory." }, "description": { "type": [ "string", "null" ], "description": "Product description." }, "quantity": { "type": [ "string", "null" ], "description": "Product quantity." }, "validity": { "type": [ "string", "null" ], "description": "Product validity." }, "fixed_price": { "type": "number", "description": "Product price." }, "amount_required": { "type": "boolean", "description": "Whether POST /api/v2/purchase must include amount for this product." }, "require_validation": { "type": "boolean", "description": "Whether customer validation is required before purchase." }, "available": { "type": "boolean", "description": "Whether the product is currently available for purchase." } }, "additionalProperties": false }, "ServiceListResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "ProviderListResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "ProductListResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProduct" } } }, "additionalProperties": false }, "ProductDetailResponse": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/PublicProduct" } }, "additionalProperties": false } } } }