{ "openapi": "3.0.3", "info": { "title": "DataBoom\ud83c\uddf3\ud83c\uddec API Documentation", "version": "v1.6.0", "description": "Auto-generated from the documentation page spec (based on your \/api endpoint code)." }, "servers": [ { "url": "https:\/\/databoomnigeria.ng\/api" } ], "components": { "securitySchemes": { "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Use: Token YOUR_API_KEY" }, "VendorTokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Use a live vendor account API key: Token YOUR_VENDOR_API_KEY" }, "SandboxTokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Use the account sandbox key: Token YOUR_SANDBOX_API_KEY. Sandbox requests never change production data." } } }, "paths": { "\/user": { "post": { "operationId": "user_details_post", "summary": "Fetch the logged-in user\u2019s profile and balances using your API Token.", "description": "Your API token identifies your account (only active accounts can call private endpoints).\nResponse formats monetary values with 2 decimal places (string).", "tags": [ "Auth & User" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "id": 1001, "name": "Doe John", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "08012345678", "account_type": 1, "balance": "50000.00", "commission_balance": "3500.00", "referral_balance": "750.00" } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "user-details-10001" } ], "requestBody": { "required": false, "content": { "application\/json": { "schema": { "type": "object" }, "example": {} } } } } }, "\/network-details": { "get": { "operationId": "network_details_get", "summary": "List available networks and service toggles (VTU, SME, Gifting, Corporate, Share-sell, etc.).", "description": "Supports pagination, sorting, search (q), filters, and ETag caching (If-None-Match).\nDebug logging: ?debug=1 writes to \/api\/network-details\/network_details_error_log.txt", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox networks fetched successfully", "networks": [ { "nId": 1, "network": "MTN", "logo": "\/uploads\/networks\/mtn.png", "networkStatus": "On", "vtuStatus": "On", "sharesellStatus": "Off", "smeStatus": "On", "giftingStatus": "On", "corporateStatus": "On", "datapinStatus": "On", "airtimepinStatus": "On", "ids": { "networkid": "1", "smeId": "1", "giftingId": "1", "corporateId": "1", "vtuId": "1", "sharesellId": "1" } }, { "nId": 2, "network": "Airtel", "logo": "\/uploads\/networks\/airtel.png", "networkStatus": "On", "vtuStatus": "On", "sharesellStatus": "Off", "smeStatus": "On", "giftingStatus": "On", "corporateStatus": "On", "datapinStatus": "Off", "airtimepinStatus": "On", "ids": { "networkid": "2", "smeId": "2", "giftingId": "2", "corporateId": "2", "vtuId": "2", "sharesellId": "2" } } ], "count": 2, "airtimeType": "VTU" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "only_active", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "example": "data" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] }, "post": { "operationId": "network_details_post", "summary": "List available networks and service toggles (VTU, SME, Gifting, Corporate, Share-sell, etc.).", "description": "Supports pagination, sorting, search (q), filters, and ETag caching (If-None-Match).\nDebug logging: ?debug=1 writes to \/api\/network-details\/network_details_error_log.txt", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox networks fetched successfully", "networks": [ { "nId": 1, "network": "MTN", "logo": "\/uploads\/networks\/mtn.png", "networkStatus": "On", "vtuStatus": "On", "sharesellStatus": "Off", "smeStatus": "On", "giftingStatus": "On", "corporateStatus": "On", "datapinStatus": "On", "airtimepinStatus": "On", "ids": { "networkid": "1", "smeId": "1", "giftingId": "1", "corporateId": "1", "vtuId": "1", "sharesellId": "1" } }, { "nId": 2, "network": "Airtel", "logo": "\/uploads\/networks\/airtel.png", "networkStatus": "On", "vtuStatus": "On", "sharesellStatus": "Off", "smeStatus": "On", "giftingStatus": "On", "corporateStatus": "On", "datapinStatus": "Off", "airtimepinStatus": "On", "ids": { "networkid": "2", "smeId": "2", "giftingId": "2", "corporateId": "2", "vtuId": "2", "sharesellId": "2" } } ], "count": 2, "airtimeType": "VTU" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "network-details-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "only_active": 1, "service": "data", "page": 1, "limit": 50 } } } } } }, "\/data-plans": { "get": { "operationId": "data_plans_get", "summary": "Fetch data plans grouped by network, with advanced filters and ETag caching.", "description": "Requires token: used to determine user type (user\/agent\/vendor) and return the correct price tier.\nReturns networks[] and also mirrors it into data[] for compatibility.\nDebug logging: ?debug=1 writes to \/api\/data-plans\/data_plans_error_log.txt", "tags": [ "Catalog \/ Lookups" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox data plans fetched successfully", "networks": [ { "networkId": 1, "networkName": "MTN", "dataplans": [ { "planId": 101, "planName": "500MB SME", "planType": "SME", "planSize": "500MB", "planValidity": "30 Days", "userPrice": 160, "agentPrice": 155, "vendorPrice": 150, "planStatus": "On" }, { "planId": 102, "planName": "1GB Corporate", "planType": "Corporate", "planSize": "1GB", "planValidity": "30 Days", "userPrice": 320, "agentPrice": 310, "vendorPrice": 300, "planStatus": "On" } ] }, { "networkId": 2, "networkName": "Airtel", "dataplans": [ { "planId": 201, "planName": "1GB Gifting", "planType": "Gifting", "planSize": "1GB", "planValidity": "30 Days", "userPrice": 350, "agentPrice": 340, "vendorPrice": 330, "planStatus": "On" } ] } ], "count": 3 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "network", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "only_active", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] }, "post": { "operationId": "data_plans_post", "summary": "Fetch data plans grouped by network, with advanced filters and ETag caching.", "description": "Requires token: used to determine user type (user\/agent\/vendor) and return the correct price tier.\nReturns networks[] and also mirrors it into data[] for compatibility.\nDebug logging: ?debug=1 writes to \/api\/data-plans\/data_plans_error_log.txt", "tags": [ "Catalog \/ Lookups" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox data plans fetched successfully", "networks": [ { "networkId": 1, "networkName": "MTN", "dataplans": [ { "planId": 101, "planName": "500MB SME", "planType": "SME", "planSize": "500MB", "planValidity": "30 Days", "userPrice": 160, "agentPrice": 155, "vendorPrice": 150, "planStatus": "On" }, { "planId": 102, "planName": "1GB Corporate", "planType": "Corporate", "planSize": "1GB", "planValidity": "30 Days", "userPrice": 320, "agentPrice": 310, "vendorPrice": 300, "planStatus": "On" } ] }, { "networkId": 2, "networkName": "Airtel", "dataplans": [ { "planId": 201, "planName": "1GB Gifting", "planType": "Gifting", "planSize": "1GB", "planValidity": "30 Days", "userPrice": 350, "agentPrice": 340, "vendorPrice": 330, "planStatus": "On" } ] } ], "count": 3 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "data-plans-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "network": 1, "only_active": 1, "page": 1, "limit": 50 } } } } } }, "\/cable-details": { "get": { "operationId": "cable_details_get", "summary": "List cable TV providers and their plan metadata (plan IDs, names, validity).", "description": "Use planId from this endpoint when calling \/api\/cabletv.\nSupports filters: q, provider, status; pagination, sorting, ETag caching.", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox cable plans fetched successfully", "providers": [ { "providerId": 1, "providerName": "DStv", "providerStatus": "On", "plans": [ { "planId": 11, "planProvider": "DStv", "planName": "DStv Padi", "planUserPrice": 3600, "planAgentPrice": 3550, "planVendorPrice": 3500, "planValidity": "30 Days" } ] }, { "providerId": 2, "providerName": "GOtv", "providerStatus": "On", "plans": [ { "planId": 21, "planProvider": "GOtv", "planName": "GOtv Jolli", "planUserPrice": 5000, "planAgentPrice": 4950, "planVendorPrice": 4900, "planValidity": "30 Days" } ] } ], "count": 2 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "providerIds", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1,2" }, { "name": "only_active", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] }, "post": { "operationId": "cable_details_post", "summary": "List cable TV providers and their plan metadata (plan IDs, names, validity).", "description": "Use planId from this endpoint when calling \/api\/cabletv.\nSupports filters: q, provider, status; pagination, sorting, ETag caching.", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox cable plans fetched successfully", "providers": [ { "providerId": 1, "providerName": "DStv", "providerStatus": "On", "plans": [ { "planId": 11, "planProvider": "DStv", "planName": "DStv Padi", "planUserPrice": 3600, "planAgentPrice": 3550, "planVendorPrice": 3500, "planValidity": "30 Days" } ] }, { "providerId": 2, "providerName": "GOtv", "providerStatus": "On", "plans": [ { "planId": 21, "planProvider": "GOtv", "planName": "GOtv Jolli", "planUserPrice": 5000, "planAgentPrice": 4950, "planVendorPrice": 4900, "planValidity": "30 Days" } ] } ], "count": 2 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "cable-details-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "providerIds": "1,2", "only_active": 1, "page": 1, "limit": 50 } } } } } }, "\/electricity-providers": { "get": { "operationId": "electricity_providers_get", "summary": "List electricity discos\/providers and their service status.", "description": "Use provider id (eId) when calling \/api\/electricity.\nSupports filters, pagination, sorting, ETag caching.", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox electricity providers fetched successfully", "providers": [ { "providerId": 1, "providerName": "EEDC", "providerStatus": "On", "providerDiscount": 0.5, "providerCharges": 100 }, { "providerId": 2, "providerName": "IKEDC", "providerStatus": "On", "providerDiscount": 0.5, "providerCharges": 100 } ], "count": 2 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "only_active", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "providerName" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "example": "asc" } ] }, "post": { "operationId": "electricity_providers_post", "summary": "List electricity discos\/providers and their service status.", "description": "Use provider id (eId) when calling \/api\/electricity.\nSupports filters, pagination, sorting, ETag caching.", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox electricity providers fetched successfully", "providers": [ { "providerId": 1, "providerName": "EEDC", "providerStatus": "On", "providerDiscount": 0.5, "providerCharges": 100 }, { "providerId": 2, "providerName": "IKEDC", "providerStatus": "On", "providerDiscount": 0.5, "providerCharges": 100 } ], "count": 2 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "electricity-providers-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "only_active": 1, "sort_by": "providerName", "sort_dir": "asc" } } } } } }, "\/exam-providers": { "get": { "operationId": "exam_providers_get", "summary": "List exam providers (WAEC, NECO, etc.) and their pricing metadata.", "description": "Use providerId (eId) when calling \/api\/exam.\nSupports filters, pagination, sorting, ETag caching.", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox exam providers fetched successfully", "providers": [ { "providerId": 1, "providerName": "WAEC Result Checker", "providerPrice": 3900, "providerStatus": "On" }, { "providerId": 2, "providerName": "NECO Result Checker", "providerPrice": 1200, "providerStatus": "On" } ], "count": 2 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "only_active", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "providerPrice" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "example": "asc" } ] }, "post": { "operationId": "exam_providers_post", "summary": "List exam providers (WAEC, NECO, etc.) and their pricing metadata.", "description": "Use providerId (eId) when calling \/api\/exam.\nSupports filters, pagination, sorting, ETag caching.", "tags": [ "Catalog \/ Lookups" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox exam providers fetched successfully", "providers": [ { "providerId": 1, "providerName": "WAEC Result Checker", "providerPrice": 3900, "providerStatus": "On" }, { "providerId": 2, "providerName": "NECO Result Checker", "providerPrice": 1200, "providerStatus": "On" } ], "count": 2 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "validation_error", "message": "One or more request values are invalid." } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "exam-providers-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "only_active": 1, "sort_by": "providerPrice", "sort_dir": "asc" } } } } } }, "\/transactions": { "get": { "operationId": "transactions_list_get", "summary": "Fetch wallet transactions for the token owner with powerful filtering, sorting, pagination and ETag caching.", "description": "AUTH RULE: finds subscriber via subscribers.sApiKey = {TOKEN}, then returns transactions by subscribers.sId.\nOutput fields are intentionally minimal (only 8 per transaction), but filters are advanced.\nDebug logging: ?debug=1 writes to \/api\/transactions\/transactions_error_log.txt", "tags": [ "Transactions" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox transactions fetched successfully", "transactions": [ { "reference": "SBX-TXN-001", "service": "Data", "description": "1GB MTN SME to 08012345678", "amount": "320.00", "status": "success", "before": "50320.00", "after": "50000.00", "date": "2026-07-11 09:45:00" }, { "reference": "SBX-TXN-002", "service": "Wallet Funding", "description": "Sandbox AutoStatement credit", "amount": "5000.00", "status": "success", "before": "45000.00", "after": "50000.00", "date": "2026-07-11 09:00:00" } ], "count": 2, "pagination": { "page": 1, "limit": 50, "total": 2, "pages": 1 } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "success" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 20 }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "date" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "example": "desc" } ] }, "post": { "operationId": "transactions_list_post", "summary": "Fetch wallet transactions for the token owner with powerful filtering, sorting, pagination and ETag caching.", "description": "AUTH RULE: finds subscriber via subscribers.sApiKey = {TOKEN}, then returns transactions by subscribers.sId.\nOutput fields are intentionally minimal (only 8 per transaction), but filters are advanced.\nDebug logging: ?debug=1 writes to \/api\/transactions\/transactions_error_log.txt", "tags": [ "Transactions" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "msg": "Sandbox transactions fetched successfully", "transactions": [ { "reference": "SBX-TXN-001", "service": "Data", "description": "1GB MTN SME to 08012345678", "amount": "320.00", "status": "success", "before": "50320.00", "after": "50000.00", "date": "2026-07-11 09:45:00" }, { "reference": "SBX-TXN-002", "service": "Wallet Funding", "description": "Sandbox AutoStatement credit", "amount": "5000.00", "status": "success", "before": "45000.00", "after": "50000.00", "date": "2026-07-11 09:00:00" } ], "count": 2, "pagination": { "page": 1, "limit": 50, "total": 2, "pages": 1 } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "transactions-list-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "status": "success", "page": 1, "limit": 20, "sort_by": "date", "sort_dir": "desc" } } } } } }, "\/cabletv\/verify": { "get": { "operationId": "verify_cable_customer_get", "summary": "Validate a Cable TV smart card or IUC number and return the registered customer name before subscription.", "description": "This endpoint only verifies customer details. It does not debit the wallet or create a subscription transaction.\nUse the provider ID returned by \/api\/cable-details. The compatibility field cablename also accepts DSTV, GOTV or STARTIMES.\nBoth live and sandbox API keys are supported. Sandbox returns realistic customer data without contacting a provider.", "tags": [ "Customer verification" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "SANDBOX CUSTOMER", "name": "SANDBOX CUSTOMER", "Customer_Name": "SANDBOX CUSTOMER", "customer_name": "SANDBOX CUSTOMER", "provider_id": "1", "provider": "DStv", "iucnumber": "1234567890", "smart_card_number": "1234567890", "verification_reference": "CV-SBX-8F1A2C3D4E5F6789" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "iucnumber", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1234567890" } ] }, "post": { "operationId": "verify_cable_customer_post", "summary": "Validate a Cable TV smart card or IUC number and return the registered customer name before subscription.", "description": "This endpoint only verifies customer details. It does not debit the wallet or create a subscription transaction.\nUse the provider ID returned by \/api\/cable-details. The compatibility field cablename also accepts DSTV, GOTV or STARTIMES.\nBoth live and sandbox API keys are supported. Sandbox returns realistic customer data without contacting a provider.", "tags": [ "Customer verification" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "SANDBOX CUSTOMER", "name": "SANDBOX CUSTOMER", "Customer_Name": "SANDBOX CUSTOMER", "customer_name": "SANDBOX CUSTOMER", "provider_id": "1", "provider": "DStv", "iucnumber": "1234567890", "smart_card_number": "1234567890", "verification_reference": "CV-SBX-8F1A2C3D4E5F6789" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "verify-cable-customer-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "provider": 1, "iucnumber": "1234567890" } } } } } }, "\/electricity\/verify": { "get": { "operationId": "verify_electricity_meter_get", "summary": "Validate an electricity meter number and return the customer name and address before payment.", "description": "This endpoint only verifies meter details. It does not debit the wallet or purchase electricity units.\nUse the provider ID returned by \/api\/electricity-providers. Provider names and abbreviations are also accepted where configured.\nMeter type must be PREPAID or POSTPAID.\nBoth live and sandbox API keys are supported. Sandbox returns realistic meter data without contacting a provider.", "tags": [ "Customer verification" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "SANDBOX CUSTOMER @ 1 Sandbox Avenue", "name": "SANDBOX CUSTOMER @ 1 Sandbox Avenue", "Customer_Name": "SANDBOX CUSTOMER @ 1 Sandbox Avenue", "customer_name": "SANDBOX CUSTOMER", "customer_address": "1 Sandbox Avenue", "provider_id": "1", "provider": "EEDC", "meter_number": "12345678901", "meternumber": "12345678901", "meter_type": "PREPAID", "verification_reference": "EV-SBX-9A8B7C6D5E4F3210" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "meternumber", "in": "query", "required": false, "schema": { "type": "string" }, "example": "12345678901" }, { "name": "metertype", "in": "query", "required": false, "schema": { "type": "string" }, "example": "PREPAID" } ] }, "post": { "operationId": "verify_electricity_meter_post", "summary": "Validate an electricity meter number and return the customer name and address before payment.", "description": "This endpoint only verifies meter details. It does not debit the wallet or purchase electricity units.\nUse the provider ID returned by \/api\/electricity-providers. Provider names and abbreviations are also accepted where configured.\nMeter type must be PREPAID or POSTPAID.\nBoth live and sandbox API keys are supported. Sandbox returns realistic meter data without contacting a provider.", "tags": [ "Customer verification" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "SANDBOX CUSTOMER @ 1 Sandbox Avenue", "name": "SANDBOX CUSTOMER @ 1 Sandbox Avenue", "Customer_Name": "SANDBOX CUSTOMER @ 1 Sandbox Avenue", "customer_name": "SANDBOX CUSTOMER", "customer_address": "1 Sandbox Avenue", "provider_id": "1", "provider": "EEDC", "meter_number": "12345678901", "meternumber": "12345678901", "meter_type": "PREPAID", "verification_reference": "EV-SBX-9A8B7C6D5E4F3210" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "verify-electricity-meter-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "provider": 1, "meternumber": "12345678901", "metertype": "PREPAID" } } } } } }, "\/airtime": { "post": { "operationId": "buy_airtime_post", "summary": "Purchase airtime (VTU or Share & Sell). Debits wallet and records a transaction.", "description": "Minimum\/maximum purchase limits are enforced by the platform configuration.\nAirtime type must be exactly: \"VTU\" or \"Share And Sell\".\nOptional: set ported_number=\"true\" to skip network prefix validation.\nTransaction ref (ref) must be unique; duplicates return an error.", "tags": [ "Purchases (Debit wallet)" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "Sandbox transaction completed successfully", "reference": "ORDER-10001", "transaction_reference": "ORDER-10001", "amount": "1000.00", "phone": "08012345678", "balance_before": "50000.00", "balance_after": "49000.00", "service": "airtime", "network": 1, "airtime_type": "VTU" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "buy-airtime-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "network": 1, "amount": 1000, "phone": "08012345678", "airtime_type": "VTU", "ref": "ORDER-10001" } } } } } }, "\/data": { "post": { "operationId": "buy_data_post", "summary": "Purchase mobile data bundle using a plan ID. Debits wallet and records a transaction.", "description": "Network must be active (networkStatus = On).\nPlan must exist for that network (datanetwork) and must be enabled per group (SME\/Gifting\/Corporate) on the networkid flags.\nOptional: set ported_number=\"true\" to skip phone network validation.", "tags": [ "Purchases (Debit wallet)" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "Sandbox transaction completed successfully", "reference": "ORDER-10003", "transaction_reference": "ORDER-10003", "amount": "320.00", "phone": "08012345678", "balance_before": "50000.00", "balance_after": "49680.00", "service": "data", "network": 1, "data_plan": 101, "plan_name": "1GB SME", "validity": "30 Days" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "buy-data-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "network": 1, "data_plan": 101, "phone": "08012345678", "ref": "ORDER-10003" } } } } } }, "\/cabletv": { "post": { "operationId": "buy_cable_post", "summary": "Subscribe a smartcard\/IUC number to a cable plan. Debits wallet and records a transaction.", "description": "Use \/api\/cable-details to discover provider IDs and plan IDs.\nRecords the transaction as processing (status 5) before contacting the provider, then updates status to 0\/1.\nThe endpoint supports alternate body keys for compatibility.", "tags": [ "Purchases (Debit wallet)" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "Sandbox transaction completed successfully", "reference": "ORDER-10005", "transaction_reference": "ORDER-10005", "amount": "3600.00", "phone": "08012345678", "balance_before": "50000.00", "balance_after": "46400.00", "service": "cable_tv", "provider": 1, "plan": 11, "iuc": "1234567890", "customer_name": "SANDBOX CUSTOMER" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "buy-cable-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "provider": 1, "plan": 11, "iuc": "1234567890", "phone": "08012345678", "ref": "ORDER-10005" } } } } } }, "\/electricity": { "post": { "operationId": "buy_electricity_post", "summary": "Buy electricity units for a meter number. Debits wallet and records a transaction.", "description": "Minimum purchase enforced: \u20a61000.\nExtra charges may apply based on platform configuration and provider rates.\nOn success, the unit token is returned immediately in msg and token, and is appended into the transaction description (servicedesc).\nThe success response also includes ref, reference and description so applications can show a complete receipt immediately.\nTo retrieve the token later, call \/api\/transactions and read description for that reference.", "tags": [ "Purchases (Debit wallet)" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "Sandbox transaction completed successfully", "reference": "ORDER-10006", "transaction_reference": "ORDER-10006", "amount": "5000.00", "phone": "08012345678", "balance_before": "50000.00", "balance_after": "45000.00", "service": "electricity", "provider": 1, "meter_number": "12345678901", "meter_type": "PREPAID", "customer_name": "SANDBOX CUSTOMER", "token": "1234-5678-9012-3456-7890", "units": "42.50" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "buy-electricity-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "provider": 1, "meter_number": "12345678901", "metertype": "PREPAID", "amount": 5000, "phone": "08012345678", "ref": "ORDER-10006" } } } } } }, "\/exam": { "post": { "operationId": "buy_exam_post", "summary": "Buy one or more exam PIN tokens.", "description": "Provider must be available (providerStatus = On).\nOn success, the PIN is returned in multiple keys for compatibility: msg, pin, pins, token.\nThe PIN is also appended into the transaction description (servicedesc).", "tags": [ "Purchases (Debit wallet)" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "Status": "successful", "msg": "SBX-1234-5678-9012", "pin": "SBX-1234-5678-9012", "pins": [ "SBX-1234-5678-9012" ], "token": "SBX-1234-5678-9012", "reference": "ORDER-10007", "provider": 1, "quantity": 1 } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "buy-exam-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "provider": 1, "quantity": 1, "ref": "ORDER-10007" } } } } } }, "\/vendor\/dashboard": { "get": { "operationId": "vendor_api_dashboard_get", "summary": "Balances, users, transactions, payment and withdrawal KPIs plus recent transactions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "vendor": { "id": 1001, "name": "John Doe", "type": "vendor" }, "balances": { "main_wallet": "50000.00", "commission_wallet": "3500.00", "referral_wallet": "750.00" }, "kpis": { "users": 125, "transactions": 1840, "successful_transactions": 1772, "payments_received": "425000.00", "pending_withdrawals": "0.00" }, "recent_transactions": [ { "id": 7001, "reference": "SBX-TXN-001", "service": "Data", "description": "1GB MTN SME to 08012345678", "amount": "320.00", "status": "success", "date": "2026-07-11 09:45:00" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "example": "30d" } ] } }, "\/vendor\/quick-setup": { "get": { "operationId": "vendor_api_quick_setup_get", "summary": "Return the same setup checks and incomplete-item guidance used by the vendor quick-setup page.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "completion_percent": 86, "completed_steps": 6, "total_steps": 7, "checks": [ { "key": "website", "label": "Configure VTUPlug website", "complete": true, "url": "\/user\/vendor-website" }, { "key": "payment_method", "label": "Enable a payment method", "complete": true, "url": "\/user\/vendor-payment-methods" }, { "key": "telegram", "label": "Connect Telegram BOT", "complete": false, "url": "\/user\/vendor-telegram-bot-settings" } ], "next_action": { "key": "telegram", "label": "Connect Telegram BOT", "url": "\/user\/vendor-telegram-bot-settings" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] } }, "\/vendor\/website": { "get": { "operationId": "vendor_api_website_get", "summary": "Read or update the vendor VTUPlug website, CMS, branding, SEO and PWA configuration.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "website": { "domain": "sandbox-vendor.example.test", "site_name": "Sandbox VTU Store", "status": "active", "theme": "premium", "primary_color": "#2563eb", "pwa_enabled": true, "seo_title": "Sandbox VTU Store" }, "cms": { "hero_title": "Instant airtime, data and bill payments", "hero_subtitle": "Fast and secure digital services" }, "action_result": { "saved": true, "message": "Sandbox website settings validated; no production data was changed." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_website_post", "summary": "Read or update the vendor VTUPlug website, CMS, branding, SEO and PWA configuration.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "website": { "domain": "sandbox-vendor.example.test", "site_name": "Sandbox VTU Store", "status": "active", "theme": "premium", "primary_color": "#2563eb", "pwa_enabled": true, "seo_title": "Sandbox VTU Store" }, "cms": { "hero_title": "Instant airtime, data and bill payments", "hero_subtitle": "Fast and secure digital services" }, "action_result": { "saved": true, "message": "Sandbox website settings validated; no production data was changed." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-website-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_website", "site_name": "My VTU Store", "hero_title": "Instant digital services", "primary_color": "#2563eb", "pwa_enabled": true } } } } }, "patch": { "operationId": "vendor_api_website_patch", "summary": "Read or update the vendor VTUPlug website, CMS, branding, SEO and PWA configuration.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "website": { "domain": "sandbox-vendor.example.test", "site_name": "Sandbox VTU Store", "status": "active", "theme": "premium", "primary_color": "#2563eb", "pwa_enabled": true, "seo_title": "Sandbox VTU Store" }, "cms": { "hero_title": "Instant airtime, data and bill payments", "hero_subtitle": "Fast and secure digital services" }, "action_result": { "saved": true, "message": "Sandbox website settings validated; no production data was changed." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-website-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_website", "site_name": "My VTU Store", "hero_title": "Instant digital services", "primary_color": "#2563eb", "pwa_enabled": true } } } } } }, "\/vendor\/website-traffic": { "get": { "operationId": "vendor_api_website_traffic_get", "summary": "Return vendor website visits, visitors, devices, referrers, locations and period comparisons.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "period": { "from": "2026-07-05", "to": "2026-07-11" }, "totals": { "visits": 4200, "unique_visitors": 2850, "pageviews": 9600, "bounce_rate": 28.4 }, "devices": [ { "name": "Mobile", "visits": 3400 }, { "name": "Desktop", "visits": 800 } ], "top_pages": [ { "path": "\/", "pageviews": 3500 }, { "path": "\/data", "pageviews": 1900 } ], "referrers": [ { "source": "Direct", "visits": 2300 }, { "source": "Google", "visits": 1200 } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "example": "30d" }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 } ] } }, "\/vendor\/whatsapp-bot": { "get": { "operationId": "vendor_api_whatsapp_bot_get", "summary": "Read\/update the BOT number and session duration; securely reveal, lock or regenerate the vendor webhook secret.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "enabled": true, "bot_whatsapp_number": "2348012345678", "session_expires_hours": 24, "webhook_url": "https:\/\/example.test\/webhook\/vendor\/whatsapp\/1001", "secret": { "configured": true, "masked": "abcd****************wxyz" }, "action_result": { "saved": true, "message": "Sandbox validation completed." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_whatsapp_bot_post", "summary": "Read\/update the BOT number and session duration; securely reveal, lock or regenerate the vendor webhook secret.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "enabled": true, "bot_whatsapp_number": "2348012345678", "session_expires_hours": 24, "webhook_url": "https:\/\/example.test\/webhook\/vendor\/whatsapp\/1001", "secret": { "configured": true, "masked": "abcd****************wxyz" }, "action_result": { "saved": true, "message": "Sandbox validation completed." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-whatsapp-bot-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_bot_whatsapp_number", "bot_whatsapp_number": "2348012345678", "bot_session_expires": 24 } } } } }, "patch": { "operationId": "vendor_api_whatsapp_bot_patch", "summary": "Read\/update the BOT number and session duration; securely reveal, lock or regenerate the vendor webhook secret.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "enabled": true, "bot_whatsapp_number": "2348012345678", "session_expires_hours": 24, "webhook_url": "https:\/\/example.test\/webhook\/vendor\/whatsapp\/1001", "secret": { "configured": true, "masked": "abcd****************wxyz" }, "action_result": { "saved": true, "message": "Sandbox validation completed." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-whatsapp-bot-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_bot_whatsapp_number", "bot_whatsapp_number": "2348012345678", "bot_session_expires": 24 } } } } } }, "\/vendor\/telegram-bot": { "get": { "operationId": "vendor_api_telegram_bot_get", "summary": "Read\/update the Telegram BOT token, profile, commands, menu button, webhook, test messages and secret key.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "enabled": true, "bot_username": "sandbox_databoom_bot", "description": "Sandbox vendor assistant", "commands": [ { "command": "start", "description": "Start the BOT" }, { "command": "balance", "description": "Check wallet balance" } ], "menu_button": { "type": "web_app", "url": "https:\/\/sandbox.example.test\/bot" }, "webhook": { "configured": true, "pending_update_count": 0 }, "token_masked": "1234************abcd", "action_result": { "ok": true, "description": "Sandbox Telegram action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_telegram_bot_post", "summary": "Read\/update the Telegram BOT token, profile, commands, menu button, webhook, test messages and secret key.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "enabled": true, "bot_username": "sandbox_databoom_bot", "description": "Sandbox vendor assistant", "commands": [ { "command": "start", "description": "Start the BOT" }, { "command": "balance", "description": "Check wallet balance" } ], "menu_button": { "type": "web_app", "url": "https:\/\/sandbox.example.test\/bot" }, "webhook": { "configured": true, "pending_update_count": 0 }, "token_masked": "1234************abcd", "action_result": { "ok": true, "description": "Sandbox Telegram action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-telegram-bot-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "set_commands", "commands": [ { "command": "balance", "description": "Check wallet balance" }, { "command": "data", "description": "Buy data" } ] } } } } }, "patch": { "operationId": "vendor_api_telegram_bot_patch", "summary": "Read\/update the Telegram BOT token, profile, commands, menu button, webhook, test messages and secret key.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "enabled": true, "bot_username": "sandbox_databoom_bot", "description": "Sandbox vendor assistant", "commands": [ { "command": "start", "description": "Start the BOT" }, { "command": "balance", "description": "Check wallet balance" } ], "menu_button": { "type": "web_app", "url": "https:\/\/sandbox.example.test\/bot" }, "webhook": { "configured": true, "pending_update_count": 0 }, "token_masked": "1234************abcd", "action_result": { "ok": true, "description": "Sandbox Telegram action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-telegram-bot-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "set_commands", "commands": [ { "command": "balance", "description": "Check wallet balance" }, { "command": "data", "description": "Buy data" } ] } } } } } }, "\/vendor\/help": { "get": { "operationId": "vendor_api_help_get", "summary": "Return the full vendor help catalogue and setup diagnostics.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "categories": [ { "id": "getting-started", "title": "Getting started", "description": "Set up the essential parts of your vendor account.", "articles": [ { "title": "Configure your website", "slug": "configure-website", "summary": "Set branding, domain, PWA and contact details." }, { "title": "Enable payment collection", "slug": "enable-payment-collection", "summary": "Choose and configure AutoStatement or PocketFi." } ] }, { "id": "bots", "title": "BOT channels", "description": "Connect and manage WhatsApp and Telegram.", "articles": [ { "title": "Connect Telegram BOT", "slug": "connect-telegram-bot", "summary": "Add a BOT token, commands, menu and webhook." } ] } ], "diagnostics": { "website_ready": true, "payment_collection_ready": true, "whatsapp_ready": true, "telegram_ready": false }, "support": { "email": "support@example.test", "whatsapp": "2348012345678" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "getting-started" } ] } }, "\/vendor\/withdrawals": { "get": { "operationId": "vendor_api_withdrawals_get", "summary": "List balances, accounts and withdrawals; add\/delete accounts, transfer commission or request withdrawal.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "balances": { "commission_wallet": "3500.00", "main_wallet": "50000.00" }, "limits": { "minimum": "1000.00", "maximum": "500000.00", "interval_hours": 24 }, "accounts": [ { "id": 91, "bank_name": "Access Bank", "account_number": "0123456789", "account_name": "SANDBOX VENDOR", "status": "verified" } ], "withdrawals": [ { "id": 81, "reference": "SBX-WD-001", "amount": "2000.00", "status": "paid", "created_at": "2026-07-10 14:00:00" } ], "action_result": { "reference": "SBX-F88F87C58631F4", "status": "simulated", "message": "Sandbox withdrawal action accepted without moving funds." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_withdrawals_post", "summary": "List balances, accounts and withdrawals; add\/delete accounts, transfer commission or request withdrawal.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "balances": { "commission_wallet": "3500.00", "main_wallet": "50000.00" }, "limits": { "minimum": "1000.00", "maximum": "500000.00", "interval_hours": 24 }, "accounts": [ { "id": 91, "bank_name": "Access Bank", "account_number": "0123456789", "account_name": "SANDBOX VENDOR", "status": "verified" } ], "withdrawals": [ { "id": 81, "reference": "SBX-WD-001", "amount": "2000.00", "status": "paid", "created_at": "2026-07-10 14:00:00" } ], "action_result": { "reference": "SBX-F88F87C58631F4", "status": "simulated", "message": "Sandbox withdrawal action accepted without moving funds." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-withdrawals-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "withdraw", "account_id": 91, "amount": 2000, "password": "YOUR_PASSWORD", "pin": "1234" } } } } }, "delete": { "operationId": "vendor_api_withdrawals_delete", "summary": "List balances, accounts and withdrawals; add\/delete accounts, transfer commission or request withdrawal.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "balances": { "commission_wallet": "3500.00", "main_wallet": "50000.00" }, "limits": { "minimum": "1000.00", "maximum": "500000.00", "interval_hours": 24 }, "accounts": [ { "id": 91, "bank_name": "Access Bank", "account_number": "0123456789", "account_name": "SANDBOX VENDOR", "status": "verified" } ], "withdrawals": [ { "id": 81, "reference": "SBX-WD-001", "amount": "2000.00", "status": "paid", "created_at": "2026-07-10 14:00:00" } ], "action_result": { "reference": "SBX-F88F87C58631F4", "status": "simulated", "message": "Sandbox withdrawal action accepted without moving funds." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-withdrawals-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "withdraw", "account_id": 91, "amount": 2000, "password": "YOUR_PASSWORD", "pin": "1234" } } } } } }, "\/vendor\/bot-business": { "get": { "operationId": "vendor_api_bot_business_get", "summary": "Expose business settings, commands, broadcasts, tickets, schedules, analytics and supported console actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "settings": { "business_name": "Sandbox VTU Store", "timezone": "Africa\/Lagos", "currency": "NGN" }, "metrics": { "conversations": 620, "resolved": 580, "open_tickets": 8, "automation_rate": 92.5 }, "commands": [ { "command": "data", "enabled": true }, { "command": "airtime", "enabled": true } ], "broadcasts": [ { "id": 1, "title": "Weekend promo", "status": "sent", "recipients": 420 } ], "tickets": [ { "id": 11, "subject": "Data delay", "status": "open", "priority": "high" } ], "action_result": { "ok": true, "message": "Sandbox business-console action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_bot_business_post", "summary": "Expose business settings, commands, broadcasts, tickets, schedules, analytics and supported console actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "settings": { "business_name": "Sandbox VTU Store", "timezone": "Africa\/Lagos", "currency": "NGN" }, "metrics": { "conversations": 620, "resolved": 580, "open_tickets": 8, "automation_rate": 92.5 }, "commands": [ { "command": "data", "enabled": true }, { "command": "airtime", "enabled": true } ], "broadcasts": [ { "id": 1, "title": "Weekend promo", "status": "sent", "recipients": 420 } ], "tickets": [ { "id": 11, "subject": "Data delay", "status": "open", "priority": "high" } ], "action_result": { "ok": true, "message": "Sandbox business-console action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-business-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_business_settings", "business_name": "My VTU Store", "timezone": "Africa\/Lagos" } } } } }, "patch": { "operationId": "vendor_api_bot_business_patch", "summary": "Expose business settings, commands, broadcasts, tickets, schedules, analytics and supported console actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "settings": { "business_name": "Sandbox VTU Store", "timezone": "Africa\/Lagos", "currency": "NGN" }, "metrics": { "conversations": 620, "resolved": 580, "open_tickets": 8, "automation_rate": 92.5 }, "commands": [ { "command": "data", "enabled": true }, { "command": "airtime", "enabled": true } ], "broadcasts": [ { "id": 1, "title": "Weekend promo", "status": "sent", "recipients": 420 } ], "tickets": [ { "id": 11, "subject": "Data delay", "status": "open", "priority": "high" } ], "action_result": { "ok": true, "message": "Sandbox business-console action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-business-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_business_settings", "business_name": "My VTU Store", "timezone": "Africa\/Lagos" } } } } }, "delete": { "operationId": "vendor_api_bot_business_delete", "summary": "Expose business settings, commands, broadcasts, tickets, schedules, analytics and supported console actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "settings": { "business_name": "Sandbox VTU Store", "timezone": "Africa\/Lagos", "currency": "NGN" }, "metrics": { "conversations": 620, "resolved": 580, "open_tickets": 8, "automation_rate": 92.5 }, "commands": [ { "command": "data", "enabled": true }, { "command": "airtime", "enabled": true } ], "broadcasts": [ { "id": 1, "title": "Weekend promo", "status": "sent", "recipients": 420 } ], "tickets": [ { "id": 11, "subject": "Data delay", "status": "open", "priority": "high" } ], "action_result": { "ok": true, "message": "Sandbox business-console action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-business-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_business_settings", "business_name": "My VTU Store", "timezone": "Africa\/Lagos" } } } } } }, "\/vendor\/bot-staff": { "get": { "operationId": "vendor_api_bot_staff_get", "summary": "List and manage vendor BOT staff and delegated web access through the business-console action engine.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "staff": [ { "id": 41, "name": "Ada Support", "email": "ada@example.test", "role": "support", "status": "active", "permissions": [ "view_conversations", "reply", "view_orders" ] } ], "settings": { "maximum_staff": 10 }, "metrics": { "active_staff": 1, "pending_invites": 0 }, "action_result": { "ok": true, "message": "Sandbox staff action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_bot_staff_post", "summary": "List and manage vendor BOT staff and delegated web access through the business-console action engine.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "staff": [ { "id": 41, "name": "Ada Support", "email": "ada@example.test", "role": "support", "status": "active", "permissions": [ "view_conversations", "reply", "view_orders" ] } ], "settings": { "maximum_staff": 10 }, "metrics": { "active_staff": 1, "pending_invites": 0 }, "action_result": { "ok": true, "message": "Sandbox staff action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-staff-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_staff", "name": "Ada Support", "email": "ada@example.com", "role": "support", "permissions": [ "view_conversations", "reply" ] } } } } }, "patch": { "operationId": "vendor_api_bot_staff_patch", "summary": "List and manage vendor BOT staff and delegated web access through the business-console action engine.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "staff": [ { "id": 41, "name": "Ada Support", "email": "ada@example.test", "role": "support", "status": "active", "permissions": [ "view_conversations", "reply", "view_orders" ] } ], "settings": { "maximum_staff": 10 }, "metrics": { "active_staff": 1, "pending_invites": 0 }, "action_result": { "ok": true, "message": "Sandbox staff action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-staff-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_staff", "name": "Ada Support", "email": "ada@example.com", "role": "support", "permissions": [ "view_conversations", "reply" ] } } } } }, "delete": { "operationId": "vendor_api_bot_staff_delete", "summary": "List and manage vendor BOT staff and delegated web access through the business-console action engine.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "staff": [ { "id": 41, "name": "Ada Support", "email": "ada@example.test", "role": "support", "status": "active", "permissions": [ "view_conversations", "reply", "view_orders" ] } ], "settings": { "maximum_staff": 10 }, "metrics": { "active_staff": 1, "pending_invites": 0 }, "action_result": { "ok": true, "message": "Sandbox staff action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-staff-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_staff", "name": "Ada Support", "email": "ada@example.com", "role": "support", "permissions": [ "view_conversations", "reply" ] } } } } } }, "\/vendor\/settings": { "get": { "operationId": "vendor_api_settings_get", "summary": "Read redacted settings; save business\/referral\/pricing values, per-network markups, SMTP configuration and branding.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "business": { "name": "Sandbox VTU Store", "email": "support@example.test", "phone": "2348012345678", "address": "1 Sandbox Avenue" }, "pricing": { "automatic_updates": true, "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } }, "referral": { "enabled": true, "bonus_percent": 1 }, "smtp": { "configured": true, "host": "smtp.example.test", "port": 587, "username": "support@example.test", "password": "********" }, "branding": { "logo_light": "\/uploads\/vendor\/sandbox-logo.png" }, "action_result": { "saved": true, "message": "Sandbox settings validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_settings_post", "summary": "Read redacted settings; save business\/referral\/pricing values, per-network markups, SMTP configuration and branding.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "business": { "name": "Sandbox VTU Store", "email": "support@example.test", "phone": "2348012345678", "address": "1 Sandbox Avenue" }, "pricing": { "automatic_updates": true, "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } }, "referral": { "enabled": true, "bonus_percent": 1 }, "smtp": { "configured": true, "host": "smtp.example.test", "port": 587, "username": "support@example.test", "password": "********" }, "branding": { "logo_light": "\/uploads\/vendor\/sandbox-logo.png" }, "action_result": { "saved": true, "message": "Sandbox settings validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-settings-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_settings", "business_name": "My VTU Store", "support_email": "support@example.com", "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } } } } } }, "patch": { "operationId": "vendor_api_settings_patch", "summary": "Read redacted settings; save business\/referral\/pricing values, per-network markups, SMTP configuration and branding.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "business": { "name": "Sandbox VTU Store", "email": "support@example.test", "phone": "2348012345678", "address": "1 Sandbox Avenue" }, "pricing": { "automatic_updates": true, "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } }, "referral": { "enabled": true, "bonus_percent": 1 }, "smtp": { "configured": true, "host": "smtp.example.test", "port": 587, "username": "support@example.test", "password": "********" }, "branding": { "logo_light": "\/uploads\/vendor\/sandbox-logo.png" }, "action_result": { "saved": true, "message": "Sandbox settings validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-settings-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_settings", "business_name": "My VTU Store", "support_email": "support@example.com", "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } } } } } }, "delete": { "operationId": "vendor_api_settings_delete", "summary": "Read redacted settings; save business\/referral\/pricing values, per-network markups, SMTP configuration and branding.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "business": { "name": "Sandbox VTU Store", "email": "support@example.test", "phone": "2348012345678", "address": "1 Sandbox Avenue" }, "pricing": { "automatic_updates": true, "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } }, "referral": { "enabled": true, "bonus_percent": 1 }, "smtp": { "configured": true, "host": "smtp.example.test", "port": 587, "username": "support@example.test", "password": "********" }, "branding": { "logo_light": "\/uploads\/vendor\/sandbox-logo.png" }, "action_result": { "saved": true, "message": "Sandbox settings validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-settings-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_settings", "business_name": "My VTU Store", "support_email": "support@example.com", "network_percentages": { "mtn": { "user": 5, "agent": 3, "vendor": 1.5 } } } } } } } }, "\/vendor\/payment-methods": { "get": { "operationId": "vendor_api_payment_methods_get", "summary": "List\/configure DataBoom AutoStatement, private AutoStatement and PocketFi; search vendor users, manage private accounts, notifications, imports, matching and linked virtual accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "methods": [ { "key": "databoom_autostatement", "name": "DataBoom AutoStatement", "enabled": true, "priority": 1 }, { "key": "private_autostatement", "name": "Private AutoStatement", "enabled": true, "priority": 2 }, { "key": "pocketfi", "name": "PocketFi", "enabled": true, "priority": 3 } ], "private_banks": [ { "id": 10, "bank_name": "Providus Bank", "account_number": "9999999999", "account_name": "SANDBOX COLLECTIONS", "enabled": true } ], "pocketfi": { "configured": true, "business_id": "SBX-BUSINESS", "api_token": "25459|********", "secret_key": "********" }, "notification_settings": { "email": true, "telegram": true, "web_push": true }, "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox payment-method action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_payment_methods_post", "summary": "List\/configure DataBoom AutoStatement, private AutoStatement and PocketFi; search vendor users, manage private accounts, notifications, imports, matching and linked virtual accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "methods": [ { "key": "databoom_autostatement", "name": "DataBoom AutoStatement", "enabled": true, "priority": 1 }, { "key": "private_autostatement", "name": "Private AutoStatement", "enabled": true, "priority": 2 }, { "key": "pocketfi", "name": "PocketFi", "enabled": true, "priority": 3 } ], "private_banks": [ { "id": 10, "bank_name": "Providus Bank", "account_number": "9999999999", "account_name": "SANDBOX COLLECTIONS", "enabled": true } ], "pocketfi": { "configured": true, "business_id": "SBX-BUSINESS", "api_token": "25459|********", "secret_key": "********" }, "notification_settings": { "email": true, "telegram": true, "web_push": true }, "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox payment-method action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-payment-methods-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_method", "method_key": "private_autostatement", "enabled": true, "settings": { "request_expiry_minutes": 30, "exact_amount_margin": 50 } } } } } }, "patch": { "operationId": "vendor_api_payment_methods_patch", "summary": "List\/configure DataBoom AutoStatement, private AutoStatement and PocketFi; search vendor users, manage private accounts, notifications, imports, matching and linked virtual accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "methods": [ { "key": "databoom_autostatement", "name": "DataBoom AutoStatement", "enabled": true, "priority": 1 }, { "key": "private_autostatement", "name": "Private AutoStatement", "enabled": true, "priority": 2 }, { "key": "pocketfi", "name": "PocketFi", "enabled": true, "priority": 3 } ], "private_banks": [ { "id": 10, "bank_name": "Providus Bank", "account_number": "9999999999", "account_name": "SANDBOX COLLECTIONS", "enabled": true } ], "pocketfi": { "configured": true, "business_id": "SBX-BUSINESS", "api_token": "25459|********", "secret_key": "********" }, "notification_settings": { "email": true, "telegram": true, "web_push": true }, "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox payment-method action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-payment-methods-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_method", "method_key": "private_autostatement", "enabled": true, "settings": { "request_expiry_minutes": 30, "exact_amount_margin": 50 } } } } } }, "delete": { "operationId": "vendor_api_payment_methods_delete", "summary": "List\/configure DataBoom AutoStatement, private AutoStatement and PocketFi; search vendor users, manage private accounts, notifications, imports, matching and linked virtual accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "methods": [ { "key": "databoom_autostatement", "name": "DataBoom AutoStatement", "enabled": true, "priority": 1 }, { "key": "private_autostatement", "name": "Private AutoStatement", "enabled": true, "priority": 2 }, { "key": "pocketfi", "name": "PocketFi", "enabled": true, "priority": 3 } ], "private_banks": [ { "id": 10, "bank_name": "Providus Bank", "account_number": "9999999999", "account_name": "SANDBOX COLLECTIONS", "enabled": true } ], "pocketfi": { "configured": true, "business_id": "SBX-BUSINESS", "api_token": "25459|********", "secret_key": "********" }, "notification_settings": { "email": true, "telegram": true, "web_push": true }, "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox payment-method action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-payment-methods-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save_method", "method_key": "private_autostatement", "enabled": true, "settings": { "request_expiry_minutes": 30, "exact_amount_margin": 50 } } } } } } }, "\/vendor\/payment-requests": { "get": { "operationId": "vendor_api_payment_requests_get", "summary": "List private payment requests or create exact-amount DataBoom AutoStatement, private AutoStatement or PocketFi instructions for a vendor user.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "request": { "id": 501, "reference": "SBX-449F99B3B721B2", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "method_key": "private_autostatement", "requested_amount": "5000.00", "exact_amount": "5017.43", "bank": { "name": "Providus Bank", "account_number": "9999999999", "account_name": "SANDBOX COLLECTIONS" }, "status": "pending", "expires_at": "2026-07-28 07:09:57" }, "instructions": "Transfer the exact amount before the expiry time." } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_payment_requests_post", "summary": "List private payment requests or create exact-amount DataBoom AutoStatement, private AutoStatement or PocketFi instructions for a vendor user.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "request": { "id": 501, "reference": "SBX-449F99B3B721B2", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "method_key": "private_autostatement", "requested_amount": "5000.00", "exact_amount": "5017.43", "bank": { "name": "Providus Bank", "account_number": "9999999999", "account_name": "SANDBOX COLLECTIONS" }, "status": "pending", "expires_at": "2026-07-28 07:09:57" }, "instructions": "Transfer the exact amount before the expiry time." } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-payment-requests-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "user_id": 9001, "amount": 5000, "method_key": "private_autostatement" } } } } } }, "\/vendor\/payments": { "get": { "operationId": "vendor_api_payments_get", "summary": "Query private bank deposits, normalized payment events and wallet transactions with detailed user and status filters.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "summary": { "total_received": "125000.00", "matched": "118000.00", "unmatched": "7000.00" }, "payments": [ { "id": 601, "source": "private_autostatement", "reference": "SBX-PAY-001", "vendor_user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "bank_name": "Providus Bank", "sender_name": "SANDBOX CUSTOMER", "amount": "5017.43", "expected_amount": "5017.43", "status": "credited", "received_at": "2026-07-11 09:30:00", "credited_transaction_reference": "SBX-CREDIT-001" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "example": "all" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "credited" }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-11" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/linked-accounts": { "get": { "operationId": "vendor_api_linked_accounts_get", "summary": "Return a vendor user\u2019s linked private payer names, PocketFi virtual accounts and DataBoom AutoStatement accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "private_payer_names": [ { "id": 71, "payer_name": "SANDBOX CUSTOMER", "bank_name": "Access Bank", "status": "verified" } ], "pocketfi_accounts": [ { "id": 72, "bank_name": "Wema Bank", "account_number": "1234567890", "account_name": "SANDBOX CUSTOMER", "status": "active" } ], "databoom_accounts": [ { "bank_name": "Moniepoint", "account_number": "8888888888", "account_name": "DATABOOM \/ SANDBOX CUSTOMER", "status": "active" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_linked_accounts_post", "summary": "Return a vendor user\u2019s linked private payer names, PocketFi virtual accounts and DataBoom AutoStatement accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "private_payer_names": [ { "id": 71, "payer_name": "SANDBOX CUSTOMER", "bank_name": "Access Bank", "status": "verified" } ], "pocketfi_accounts": [ { "id": 72, "bank_name": "Wema Bank", "account_number": "1234567890", "account_name": "SANDBOX CUSTOMER", "status": "active" } ], "databoom_accounts": [ { "bank_name": "Moniepoint", "account_number": "8888888888", "account_name": "DATABOOM \/ SANDBOX CUSTOMER", "status": "active" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-linked-accounts-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "user_id": 9001 } } } } } }, "\/vendor\/users": { "get": { "operationId": "vendor_api_users_get", "summary": "List, inspect, create, update, block, securely adjust wallets or delete vendor users without transaction history.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox vendor-user action simulated.", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_users_post", "summary": "List, inspect, create, update, block, securely adjust wallets or delete vendor users without transaction history.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox vendor-user action simulated.", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "create_user", "first_name": "Sandbox", "last_name": "Customer", "email": "customer@example.com", "phone": "08012345678", "password": "StrongPassword123!", "pin": "1234", "wallet": 0 } } } } }, "patch": { "operationId": "vendor_api_users_patch", "summary": "List, inspect, create, update, block, securely adjust wallets or delete vendor users without transaction history.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox vendor-user action simulated.", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "create_user", "first_name": "Sandbox", "last_name": "Customer", "email": "customer@example.com", "phone": "08012345678", "password": "StrongPassword123!", "pin": "1234", "wallet": 0 } } } } }, "delete": { "operationId": "vendor_api_users_delete", "summary": "List, inspect, create, update, block, securely adjust wallets or delete vendor users without transaction history.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } ], "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox vendor-user action simulated.", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "create_user", "first_name": "Sandbox", "last_name": "Customer", "email": "customer@example.com", "phone": "08012345678", "password": "StrongPassword123!", "pin": "1234", "wallet": 0 } } } } } }, "\/vendor\/users\/list": { "get": { "operationId": "vendor_api_users_list_get", "summary": "Return every user owned by the authenticated vendor by default, with optional search, filters, balances and activity metrics.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "vendor_id": 1001, "users": [ { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": { "code": 0, "key": "active", "label": "Active" }, "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00", "account_type": { "code": 1, "key": "user", "label": "User" }, "total_balance": "12950.00", "transaction_count": 24, "successful_transaction_count": 22, "transaction_volume": "18450.00", "payment_count": 3, "payments_received": "15000.00", "last_transaction_at": "2026-07-11 09:45:00", "last_payment_at": "2026-07-11 09:30:00" } ], "summary": { "vendor_total": 1, "filtered_total": 1, "active": 1, "blocked": 0, "verification_required": 0, "wallet_total": "12500.00", "referral_wallet_total": "450.00", "combined_user_balance": "12950.00" }, "filters": { "q": "", "status": null, "type": null, "has_balance": null, "min_wallet": null, "max_wallet": null, "min_referral_wallet": null, "max_referral_wallet": null, "referrer_user_id": null, "only_with_transactions": false, "sort_by": "id", "sort_dir": "DESC" }, "notice": "", "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/users\/view": { "get": { "operationId": "vendor_api_users_view_get", "summary": "View one vendor-owned user by ID, email, phone, username or identifier, including balances, security state, transactions, payments, referrals and linked payment accounts.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "vendor_id": 1001, "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": { "code": 0, "key": "active", "label": "Active" }, "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00", "account_type": { "code": 1, "key": "user", "label": "User" }, "total_balance": "12950.00" }, "all_safe_fields": { "sId": 9001, "vendor_sId": 1001, "sApiKey": "1234************************7890", "sFname": "Sandbox", "sLname": "Customer", "sUsername": "sandbox.customer", "sEmail": "customer@example.test", "sPhone": "2348012345678", "sCountry": "Nigeria", "sState": "Anambra", "sCity": "Awka", "sAddress": "1 Sandbox Avenue", "sType": 1, "sWallet": "12500.00", "sRefWallet": "450.00", "sRegStatus": 0, "sRegDate": "2026-07-01 10:00:00", "sLastActivity": "2026-07-11 09:45:00", "sReferal": "" }, "security": { "api_key_masked": "1234************************7890", "sandbox_api_key_masked": "sbx_************************7890", "pin_configured": true, "password_configured": true, "force_password_change": false, "pin_status": 1 }, "balances": { "main": "12500.00", "referral": "450.00", "total": "12950.00" }, "transactions": { "summary": { "total": 24, "successful": 22, "pending": 0, "processing": 1, "failed": 1, "reversed": 0, "successful_volume": "18450.00", "profit": "680.00", "last_transaction_at": "2026-07-11 09:45:00" }, "recent": [ { "id": 7001, "reference": "SBX-TXN-001", "transref": "SBX-TXN-001", "servicename": "Data", "servicedesc": "1GB MTN SME to 08012345678", "amount": "320.00", "status": 0, "oldbal": "12820.00", "newbal": "12500.00", "profit": "20.00", "date": "2026-07-11 09:45:00", "autostatement_transid": "", "status_meta": { "code": 0, "key": "successful", "label": "Successful" } } ] }, "payments": { "summary": { "count": 3, "amount": "15000.00", "last_payment_at": "2026-07-11 09:30:00" }, "recent": [ { "id": 601, "method_key": "private_autostatement", "reference": "SBX-PAY-001", "amount": "5017.43", "bank_name": "Providus Bank", "account_number": "9999999999", "vendor_alert_status": "sent", "created_at": "2026-07-11 09:30:00" } ] }, "referrals": { "referrer": null, "count": 1, "recent": [ { "id": 9002, "name": "Sandbox Referral", "email": "referral@example.test", "phone": "2348099999999", "wallet": "2500.00", "referral_wallet": "0.00", "status": { "code": 0, "key": "active", "label": "Active" } } ] }, "linked_accounts": { "user": { "id": 9001, "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678" }, "private_autostatement": [ { "id": 71, "sender_name": "SANDBOX CUSTOMER", "bank_name": "Access Bank", "account_number": "0123456789", "account_name": "SANDBOX COLLECTIONS" } ], "pocketfi": [ { "id": 72, "bank_name": "Wema Bank", "account_number": "1234567890", "account_name": "SANDBOX CUSTOMER", "status": "active" } ], "databoom_autostatement": { "linked_names": [ "SANDBOX CUSTOMER" ], "accounts": [ { "bank_name": "Moniepoint", "account_number": "8888888888", "account_name": "DATABOOM \/ SANDBOX CUSTOMER" } ], "message": "Sandbox linked accounts returned." } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "latest" }, { "name": "recent_limit", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 20 } ] } }, "\/vendor\/users\/manage": { "post": { "operationId": "vendor_api_users_manage_post", "summary": "Create or securely manage one vendor-owned user through profile, status, wallet, password, PIN, messaging and deletion actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "managed_action": "capabilities", "result": { "supported_actions": [ "create_user", "update_user", "set_status", "block", "activate", "require_verification", "update_wallet", "update_refwallet", "set_password", "set_pin", "send", "pause", "resume", "meta", "delete" ], "user_lookup_fields": [ "user_id", "email", "phone", "username", "identifier" ], "security_required_for": [ "update_wallet", "update_refwallet", "delete" ], "wallets": [ "main", "referral" ], "statuses": [ { "code": 0, "key": "active", "label": "Active" }, { "code": 1, "key": "blocked", "label": "Blocked" }, { "code": 3, "key": "verification_required", "label": "Email verification required" } ], "account_types": [ { "code": 1, "key": "user", "label": "User" }, { "code": 2, "key": "agent", "label": "Agent" }, { "code": 3, "key": "vendor", "label": "Vendor" } ] } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-manage-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "capabilities" } } } } }, "put": { "operationId": "vendor_api_users_manage_put", "summary": "Create or securely manage one vendor-owned user through profile, status, wallet, password, PIN, messaging and deletion actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "managed_action": "capabilities", "result": { "supported_actions": [ "create_user", "update_user", "set_status", "block", "activate", "require_verification", "update_wallet", "update_refwallet", "set_password", "set_pin", "send", "pause", "resume", "meta", "delete" ], "user_lookup_fields": [ "user_id", "email", "phone", "username", "identifier" ], "security_required_for": [ "update_wallet", "update_refwallet", "delete" ], "wallets": [ "main", "referral" ], "statuses": [ { "code": 0, "key": "active", "label": "Active" }, { "code": 1, "key": "blocked", "label": "Blocked" }, { "code": 3, "key": "verification_required", "label": "Email verification required" } ], "account_types": [ { "code": 1, "key": "user", "label": "User" }, { "code": 2, "key": "agent", "label": "Agent" }, { "code": 3, "key": "vendor", "label": "Vendor" } ] } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-manage-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "capabilities" } } } } }, "patch": { "operationId": "vendor_api_users_manage_patch", "summary": "Create or securely manage one vendor-owned user through profile, status, wallet, password, PIN, messaging and deletion actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "managed_action": "capabilities", "result": { "supported_actions": [ "create_user", "update_user", "set_status", "block", "activate", "require_verification", "update_wallet", "update_refwallet", "set_password", "set_pin", "send", "pause", "resume", "meta", "delete" ], "user_lookup_fields": [ "user_id", "email", "phone", "username", "identifier" ], "security_required_for": [ "update_wallet", "update_refwallet", "delete" ], "wallets": [ "main", "referral" ], "statuses": [ { "code": 0, "key": "active", "label": "Active" }, { "code": 1, "key": "blocked", "label": "Blocked" }, { "code": 3, "key": "verification_required", "label": "Email verification required" } ], "account_types": [ { "code": 1, "key": "user", "label": "User" }, { "code": 2, "key": "agent", "label": "Agent" }, { "code": 3, "key": "vendor", "label": "Vendor" } ] } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-manage-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "capabilities" } } } } }, "delete": { "operationId": "vendor_api_users_manage_delete", "summary": "Create or securely manage one vendor-owned user through profile, status, wallet, password, PIN, messaging and deletion actions.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "managed_action": "capabilities", "result": { "supported_actions": [ "create_user", "update_user", "set_status", "block", "activate", "require_verification", "update_wallet", "update_refwallet", "set_password", "set_pin", "send", "pause", "resume", "meta", "delete" ], "user_lookup_fields": [ "user_id", "email", "phone", "username", "identifier" ], "security_required_for": [ "update_wallet", "update_refwallet", "delete" ], "wallets": [ "main", "referral" ], "statuses": [ { "code": 0, "key": "active", "label": "Active" }, { "code": 1, "key": "blocked", "label": "Blocked" }, { "code": 3, "key": "verification_required", "label": "Email verification required" } ], "account_types": [ { "code": 1, "key": "user", "label": "User" }, { "code": 2, "key": "agent", "label": "Agent" }, { "code": 3, "key": "vendor", "label": "Vendor" } ] } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-users-manage-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "capabilities" } } } } } }, "\/vendor\/catalog\/airtime": { "get": { "operationId": "vendor_api_catalog_airtime_get", "summary": "Read the vendor\u2019s complete airtime catalogue with network, package type, subscriber, agent and vendor charge percentages, margins and optional amount quotations.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "catalog": "airtime", "read_only": true, "currency": "NGN", "items": [ { "id": 1, "system_id": 1, "network": { "id": 1, "vendor_network_row_id": 1, "external_id": "1", "name": "MTN", "logo": "\/assets\/logo\/mtn.png", "vendor_active": true, "system_active": true, "active": true }, "package": { "type": "VTU", "vendor_service_active": true, "system_service_active": true, "active": true }, "pricing": { "currency": "NGN", "model": "percentage_of_face_value", "vendor_cost_percent": 98, "subscriber_charge_percent": 99, "agent_charge_percent": 98.8, "vendor_charge_percent": 98.5, "subscriber_discount_percent": 1, "agent_discount_percent": 1.2, "vendor_discount_percent": 1.5, "subscriber_margin_percent": 1, "agent_margin_percent": 0.8, "vendor_margin_percent": 0.5 }, "selected_price": { "role": "subscriber", "charge_percent": 99, "discount_percent": 1 }, "quote": { "face_value": 1000, "vendor_cost": 980, "subscriber_price": 990, "agent_price": 988, "vendor_price": 985 } } ], "groups": [], "facets": { "networks": [ { "id": 1, "name": "MTN", "active": true, "count": 1 } ], "types": [ { "name": "VTU", "count": 1 } ] }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "filters_applied": { "network": "MTN", "amount": 1000 }, "all_results": false } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "network", "in": "query", "required": false, "schema": { "type": "string" }, "example": "MTN" }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1000 }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "network" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/catalog\/data-plans": { "get": { "operationId": "vendor_api_catalog_data_plans_get", "summary": "Read all vendor data plans with network metadata, package details, subscriber, agent and vendor prices, margins, status, grouping and advanced filters.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "catalog": "data_plans", "read_only": true, "currency": "NGN", "items": [ { "id": 101, "system_id": 241, "provider_plan_id": "297", "name": "1 GB SME", "network": { "id": 1, "vendor_network_row_id": 1, "external_id": "1", "name": "MTN", "logo": "\/assets\/logo\/mtn.png", "vendor_active": true, "system_active": true, "active": true }, "package": { "bytes": 1000, "size_mb": 1000, "size_gb": 1, "validity_days": 30, "type": "SME", "category": "normal", "variant_group": "normal", "variant_eligible": true, "variant_note": null, "vendor_service_active": true, "system_service_active": true, "vendor_plan_active": true, "system_plan_active": true, "active": true }, "pricing": { "currency": "NGN", "vendor_cost": 285, "subscriber": 320, "agent": 310, "vendor": 300, "subscriber_margin": 35, "agent_margin": 25, "vendor_margin": 15 }, "selected_price": { "role": "agent", "amount": 310, "currency": "NGN" }, "auto_update": { "override": false, "subscriber_profit_percent": 0, "agent_profit_percent": 0, "vendor_profit_percent": 0 }, "created_at": "2026-07-01 10:00:00", "updated_at": "2026-07-11 10:00:00" } ], "groups": [ { "key": "SME", "count": 1, "items": [] } ], "facets": { "networks": [ { "id": 1, "name": "MTN", "active": true, "count": 1 } ], "types": [ { "name": "SME", "count": 1 } ], "categories": [ { "name": "normal", "count": 1 } ] }, "pagination": { "page": 1, "per_page": 5000, "total": 1, "pages": 1 }, "filters_applied": { "network": "MTN", "status": true, "price_for": "agent" }, "all_results": true, "network_bulk_listing_supported": true } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "network", "in": "query", "required": false, "schema": { "type": "string" }, "example": "MTN" }, { "name": "all_for_network", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "active" }, { "name": "price_for", "in": "query", "required": false, "schema": { "type": "string" }, "example": "agent" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "type" } ] } }, "\/vendor\/catalog\/cable": { "get": { "operationId": "vendor_api_catalog_cable_get", "summary": "Read all vendor cable packages with correctly resolved providers, subscriber, agent and vendor prices, API cost, margins and advanced filters.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "catalog": "cable_plans", "read_only": true, "currency": "NGN", "items": [ { "id": 11, "system_id": 6, "provider_plan_id": "33", "name": "DStv Padi", "type": null, "validity_days": 30, "provider": { "id": 2, "system_id": 2, "provider_code": "2", "name": "DSTV", "logo": "\/assets\/logo\/dstv.png", "vendor_active": true, "system_active": true, "active": true }, "pricing": { "currency": "NGN", "vendor_cost": 4400, "subscriber": 4500, "agent": 4475, "vendor": 4450, "subscriber_margin": 100, "agent_margin": 75, "vendor_margin": 50 }, "selected_price": { "role": "subscriber", "amount": 4500, "currency": "NGN" } } ], "groups": [], "facets": { "providers": [ { "id": 2, "system_id": 2, "provider_code": "2", "name": "DSTV", "active": true, "count": 1 } ] }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "filters_applied": { "provider": "DSTV", "status": true, "price_for": "subscriber" }, "all_results": false, "provider_bulk_listing_supported": true } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "example": "DSTV" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "active" }, { "name": "price_for", "in": "query", "required": false, "schema": { "type": "string" }, "example": "subscriber" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "provider" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/catalog\/electricity": { "get": { "operationId": "vendor_api_catalog_electricity_get", "summary": "Read the vendor\u2019s electricity providers, availability, amount-based pricing formula and optional quotations for subscribers, agents and vendor-level users.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "catalog": "electricity_providers", "read_only": true, "currency": "NGN", "items": [ { "id": 9, "system_id": 9, "provider_code": "26", "name": "Enugu Electric", "abbreviation": "ENUGU", "logo": "\/assets\/logo\/enuguelectric.png", "vendor_active": true, "system_active": true, "active": true, "pricing": { "currency": "NGN", "model": "variable_amount", "service_charge": 100, "discount_percent": 0, "profit_percent": 0.5, "subscriber_formula": "amount + service_charge - (amount \u00d7 discount_percent \u00f7 100)", "agent_formula": "same_as_subscriber", "vendor_formula": "same_as_subscriber", "roles_share_same_price": true }, "quote": { "face_value": 5000, "service_charge": 100, "discount_amount": 0, "subscriber_price": 5100, "agent_price": 5100, "vendor_price": 5100, "system_cost": 5025, "vendor_gross_margin": 75, "legacy_profit_formula_result": 125 } } ], "groups": [], "pricing_note": "Electricity uses an amount-based formula. The current vendor panel applies the same payable amount to all three roles.", "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "filters_applied": { "status": true, "amount": 5000 }, "all_results": false } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "active" }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 5000 }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "provider" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "example": "asc" } ] } }, "\/vendor\/catalog\/exams": { "get": { "operationId": "vendor_api_catalog_exams_get", "summary": "Read the vendor\u2019s exam providers with buying price, subscriber, agent and vendor selling prices, margins, availability and advanced filters.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "catalog": "exam_pins", "read_only": true, "currency": "NGN", "items": [ { "id": 1, "system_id": 1, "provider_code": "1", "name": "WAEC", "logo": "\/assets\/logo\/waec.png", "vendor_active": true, "system_active": true, "active": true, "pricing": { "currency": "NGN", "panel_buying_price": 5100, "system_cost": 5500, "subscriber": 5600, "agent": 5600, "vendor": 5600, "roles_share_same_price": true, "panel_margin": 500, "effective_margin": 100, "markup_percent": 9.8 } } ], "groups": [], "pricing_note": "The current vendor panel stores one selling price per exam provider, so all three role prices are identical.", "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "filters_applied": { "status": true }, "all_results": false } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "active" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "price" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "example": "asc" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/catalog\/networks": { "get": { "operationId": "vendor_api_catalog_networks_get", "summary": "Read vendor and central network\/service availability switches, identifiers and airtime\/data-plan counts for every network.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "catalog": "networks_and_service_availability", "read_only": true, "items": [ { "id": 1, "system_id": 1, "external_id": "1", "name": "MTN", "logo": "\/assets\/logo\/mtn.png", "active": true, "services": { "network": { "vendor_active": true, "system_active": true, "active": true }, "vtu": { "vendor_active": true, "system_active": true, "active": true }, "share_and_sell": { "vendor_active": true, "system_active": true, "active": true }, "airtime_pin": { "vendor_active": false, "system_active": true, "active": false }, "sme": { "vendor_active": true, "system_active": true, "active": true }, "gifting": { "vendor_active": true, "system_active": true, "active": true }, "corporate": { "vendor_active": true, "system_active": true, "active": true }, "data_pin": { "vendor_active": false, "system_active": false, "active": false } }, "catalogue_counts": { "airtime_packages": 2, "data_plans": 210, "active_data_plans": 205 }, "identifiers": { "sme": "1", "gifting": "1", "corporate": "1", "vtu": "1", "share_and_sell": "1" } } ], "facets": { "service_totals": { "network": { "total": 1, "active": 1 }, "vtu": { "total": 1, "active": 1 }, "share_and_sell": { "total": 1, "active": 1 }, "airtime_pin": { "total": 1, "active": 0 }, "sme": { "total": 1, "active": 1 }, "gifting": { "total": 1, "active": 1 }, "corporate": { "total": 1, "active": 1 }, "data_pin": { "total": 1, "active": 0 } } }, "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "filters_applied": { "service": "sme", "service_status": true }, "all_results": false } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "example": "sme" }, { "name": "service_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "active" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "network" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "example": "asc" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/catalog\/summary": { "get": { "operationId": "vendor_api_catalog_summary_get", "summary": "Return service counts, active counts, network data-plan totals, upgrade fees and direct links to every read-only vendor catalogue endpoint.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "read_only": true, "catalog_counts": { "airtime": { "total": 8, "effective_active": 8 }, "data_plans": { "total": 630, "vendor_enabled": 612, "effective_active": 598 }, "cable_plans": { "total": 15, "providers": 3, "vendor_enabled_providers": 3, "effective_active_providers": 3, "effective_active_plans": 15 }, "electricity": { "total": 11, "vendor_enabled": 11, "effective_active": 11 }, "exams": { "total": 4, "vendor_enabled": 4, "effective_active": 4 }, "networks": { "total": 4, "effective_active": 4 } }, "networks": [ { "vendor_network_row_id": 1, "id": 1, "name": "MTN", "external_id": "1", "logo": "\/assets\/logo\/mtn.png", "data_plan_count": 210, "enabled_data_plan_count": 205, "vendor_active": true, "system_active": true, "active": true } ], "upgrade_fees": { "agent": 100, "vendor": 200, "referral_bonus_percent": 100 }, "electricity_service_charge": 100, "endpoints": { "airtime": "\/api\/vendor\/catalog\/airtime", "data_plans": "\/api\/vendor\/catalog\/data-plans", "cable": "\/api\/vendor\/catalog\/cable", "electricity": "\/api\/vendor\/catalog\/electricity", "exams": "\/api\/vendor\/catalog\/exams", "networks": "\/api\/vendor\/catalog\/networks", "upgrade_plans": "\/api\/vendor\/upgrade-plans" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] } }, "\/vendor\/upgrade-plans": { "get": { "operationId": "vendor_api_upgrade_plans_get", "summary": "List the vendor\u2019s Subscriber, Agent and Vendor plans, configured upgrade fees, referral upgrade bonus and an optional quote for one vendor-owned user.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "currency": "NGN", "plans": [ { "key": "subscriber", "type": 1, "name": "Subscriber", "fee": 0, "can_upgrade_to": false, "can_downgrade_to": true, "is_current": true, "direction": "current" }, { "key": "agent", "type": 2, "name": "Agent", "fee": 100, "can_upgrade_to": true, "can_downgrade_to": true, "is_current": false, "direction": "upgrade" }, { "key": "vendor", "type": 3, "name": "Vendor", "fee": 200, "can_upgrade_to": true, "can_downgrade_to": false, "is_current": false, "direction": "upgrade" } ], "referral_upgrade_bonus_percent": 100, "billing_modes": { "user_wallet": "Charges the vendor user wallet and requires the user transaction PIN.", "no_charge": "Vendor-authorized manual plan change requiring the vendor password and PIN; no automatic downgrade refund." }, "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "quote": { "current_level": "Customer", "current_type": 1, "wallet": 12500, "referral_upgrade_bonus_percent": 100, "options": { "agent": { "key": "agent", "label": "Agent", "target_type": 2, "fee": 100, "configured": true, "eligible": true, "balance_ok": true, "shortfall": 0 }, "vendor": { "key": "vendor", "label": "Vendor", "target_type": 3, "fee": 200, "configured": true, "eligible": true, "balance_ok": true, "shortfall": 0 } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "latest" } ] } }, "\/vendor\/users\/plan": { "get": { "operationId": "vendor_api_user_plan_get", "summary": "Quote, upgrade or downgrade a vendor-owned user. Wallet upgrades use the configured fee and user PIN; vendor-authorized manual changes require the vendor password and PIN.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "action": "upgrade", "billing_mode": "user_wallet", "reference": "SBX-VPLAN-001", "amount_charged": 100, "automatic_refund": false, "previous_plan": { "type": 1, "name": "Customer" }, "new_plan": { "type": 2, "name": "agent" }, "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00", "account_type": { "code": 2, "key": "agent", "label": "Agent" } }, "message": "Sandbox plan change simulated. No production user or wallet was changed." } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "latest" }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "example": "quote" } ] }, "post": { "operationId": "vendor_api_user_plan_post", "summary": "Quote, upgrade or downgrade a vendor-owned user. Wallet upgrades use the configured fee and user PIN; vendor-authorized manual changes require the vendor password and PIN.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "action": "upgrade", "billing_mode": "user_wallet", "reference": "SBX-VPLAN-001", "amount_charged": 100, "automatic_refund": false, "previous_plan": { "type": 1, "name": "Customer" }, "new_plan": { "type": 2, "name": "agent" }, "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00", "account_type": { "code": 2, "key": "agent", "label": "Agent" } }, "message": "Sandbox plan change simulated. No production user or wallet was changed." } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-user-plan-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "upgrade", "user_id": "latest", "target_plan": "agent", "billing_mode": "user_wallet", "user_pin": "1234" } } } } }, "patch": { "operationId": "vendor_api_user_plan_patch", "summary": "Quote, upgrade or downgrade a vendor-owned user. Wallet upgrades use the configured fee and user PIN; vendor-authorized manual changes require the vendor password and PIN.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "action": "upgrade", "billing_mode": "user_wallet", "reference": "SBX-VPLAN-001", "amount_charged": 100, "automatic_refund": false, "previous_plan": { "type": 1, "name": "Customer" }, "new_plan": { "type": 2, "name": "agent" }, "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00", "account_type": { "code": 2, "key": "agent", "label": "Agent" } }, "message": "Sandbox plan change simulated. No production user or wallet was changed." } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-user-plan-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "upgrade", "user_id": "latest", "target_plan": "agent", "billing_mode": "user_wallet", "user_pin": "1234" } } } } } }, "\/vendor\/users\/plan-history": { "get": { "operationId": "vendor_api_user_plan_history_get", "summary": "List vendor-owned user upgrade and downgrade records with user, amount, balance, date and action filters.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "items": [ { "id": 37, "reference": "SBX-UPGRADE-001", "action": "upgrade", "description": "Upgraded from Customer to Agent.", "amount": 100, "status": { "code": 0, "name": "success" }, "old_balance": 12600, "new_balance": 12500, "created_at": "2026-07-11 10:00:00", "user": { "id": 9001, "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "current_type": 2 } } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "filters_applied": [] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "action_type", "in": "query", "required": false, "schema": { "type": "string" }, "example": "upgrade" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] } }, "\/vendor\/transactions": { "get": { "operationId": "vendor_api_transactions_get", "summary": "Query detailed vendor transactions; generate printable receipt payloads and paginated CSV exports.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "transactions": [ { "id": 7001, "reference": "SBX-TXN-001", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "service": "Data", "description": "1GB MTN SME to 08012345678", "amount": "320.00", "old_balance": "12820.00", "new_balance": "12500.00", "status": "success", "date": "2026-07-11 09:45:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "export": null } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 9001 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "success" }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-11" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] }, "post": { "operationId": "vendor_api_transactions_post", "summary": "Query detailed vendor transactions; generate printable receipt payloads and paginated CSV exports.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "transactions": [ { "id": 7001, "reference": "SBX-TXN-001", "user": { "id": 9001, "vendor_sId": 1001, "first_name": "Sandbox", "last_name": "Customer", "name": "Sandbox Customer", "email": "customer@example.test", "phone": "2348012345678", "status": "active", "wallet": "12500.00", "referral_wallet": "450.00", "created_at": "2026-07-11 10:00:00" }, "service": "Data", "description": "1GB MTN SME to 08012345678", "amount": "320.00", "old_balance": "12820.00", "new_balance": "12500.00", "status": "success", "date": "2026-07-11 09:45:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "export": null } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-transactions-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "user_id": 9001, "status": "success", "date_from": "2026-07-01", "date_to": "2026-07-11", "page": 1, "per_page": 50 } } } } } }, "\/vendor\/airtime": { "get": { "operationId": "vendor_api_airtime_get", "summary": "List or update vendor airtime discounts, including bulk updates with the same discount-order and buy-discount safeguards as the vendor panel.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "networks": [ { "id": 1, "name": "MTN", "buy_discount": 3, "user_discount": 2.5, "agent_discount": 2, "vendor_discount": 1.5, "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox airtime pricing validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_airtime_post", "summary": "List or update vendor airtime discounts, including bulk updates with the same discount-order and buy-discount safeguards as the vendor panel.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "networks": [ { "id": 1, "name": "MTN", "buy_discount": 3, "user_discount": 2.5, "agent_discount": 2, "vendor_discount": 1.5, "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox airtime pricing validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-airtime-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 1, "aUserDiscount": 2.5, "aAgentDiscount": 2, "aVendorDiscount": 1.5 } } } } }, "patch": { "operationId": "vendor_api_airtime_patch", "summary": "List or update vendor airtime discounts, including bulk updates with the same discount-order and buy-discount safeguards as the vendor panel.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "networks": [ { "id": 1, "name": "MTN", "buy_discount": 3, "user_discount": 2.5, "agent_discount": 2, "vendor_discount": 1.5, "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox airtime pricing validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-airtime-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 1, "aUserDiscount": 2.5, "aAgentDiscount": 2, "aVendorDiscount": 1.5 } } } } } }, "\/vendor\/data-plans": { "get": { "operationId": "vendor_api_data_plans_get", "summary": "List or update vendor data-plan prices, availability and Auto Update overrides; bulk update or reprice using saved per-network percentages and system availability locks.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "plans": [ { "id": 101, "network": "MTN", "name": "1GB SME", "buy_price": "285.00", "user_price": "320.00", "agent_price": "310.00", "vendor_price": "300.00", "status": "On", "system_status": "On", "auto_update": true } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "updated": 1, "message": "Sandbox data-plan action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_data_plans_post", "summary": "List or update vendor data-plan prices, availability and Auto Update overrides; bulk update or reprice using saved per-network percentages and system availability locks.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "plans": [ { "id": 101, "network": "MTN", "name": "1GB SME", "buy_price": "285.00", "user_price": "320.00", "agent_price": "310.00", "vendor_price": "300.00", "status": "On", "system_status": "On", "auto_update": true } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "updated": 1, "message": "Sandbox data-plan action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-data-plans-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 101, "userprice": 320, "agentprice": 310, "vendorprice": 300, "is_active": true, "autoUpdateOverride": false } } } } }, "patch": { "operationId": "vendor_api_data_plans_patch", "summary": "List or update vendor data-plan prices, availability and Auto Update overrides; bulk update or reprice using saved per-network percentages and system availability locks.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "plans": [ { "id": 101, "network": "MTN", "name": "1GB SME", "buy_price": "285.00", "user_price": "320.00", "agent_price": "310.00", "vendor_price": "300.00", "status": "On", "system_status": "On", "auto_update": true } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "updated": 1, "message": "Sandbox data-plan action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-data-plans-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 101, "userprice": 320, "agentprice": 310, "vendorprice": 300, "is_active": true, "autoUpdateOverride": false } } } } } }, "\/vendor\/electricity": { "get": { "operationId": "vendor_api_electricity_get", "summary": "List, update, toggle and export vendor electricity-provider configuration.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "EEDC", "discount": 0.5, "charge": 100, "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox electricity action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_electricity_post", "summary": "List, update, toggle and export vendor electricity-provider configuration.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "EEDC", "discount": 0.5, "charge": 100, "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox electricity action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-electricity-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 1, "discount": 0.5, "providerStatus": true } } } } }, "patch": { "operationId": "vendor_api_electricity_patch", "summary": "List, update, toggle and export vendor electricity-provider configuration.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "EEDC", "discount": 0.5, "charge": 100, "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox electricity action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-electricity-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 1, "discount": 0.5, "providerStatus": true } } } } } }, "\/vendor\/cable": { "get": { "operationId": "vendor_api_cable_get", "summary": "List, update, toggle and export cable providers and plans, including bulk pricing with API-price and role-price safeguards.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "DStv", "status": "On", "plans": [ { "id": 11, "name": "DStv Padi", "api_price": "3500.00", "user_price": "3600.00", "agent_price": "3575.00", "vendor_price": "3550.00", "status": "On" } ] } ], "action_result": { "updated": 1, "message": "Sandbox cable action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_cable_post", "summary": "List, update, toggle and export cable providers and plans, including bulk pricing with API-price and role-price safeguards.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "DStv", "status": "On", "plans": [ { "id": 11, "name": "DStv Padi", "api_price": "3500.00", "user_price": "3600.00", "agent_price": "3575.00", "vendor_price": "3550.00", "status": "On" } ] } ], "action_result": { "updated": 1, "message": "Sandbox cable action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-cable-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "plan_save", "cpId": 11, "userprice": 3600, "agentprice": 3575, "vendorprice": 3550, "status": true } } } } }, "patch": { "operationId": "vendor_api_cable_patch", "summary": "List, update, toggle and export cable providers and plans, including bulk pricing with API-price and role-price safeguards.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "DStv", "status": "On", "plans": [ { "id": 11, "name": "DStv Padi", "api_price": "3500.00", "user_price": "3600.00", "agent_price": "3575.00", "vendor_price": "3550.00", "status": "On" } ] } ], "action_result": { "updated": 1, "message": "Sandbox cable action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-cable-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "plan_save", "cpId": 11, "userprice": 3600, "agentprice": 3575, "vendorprice": 3550, "status": true } } } } } }, "\/vendor\/exams": { "get": { "operationId": "vendor_api_exams_get", "summary": "List, update, toggle and export vendor exam providers, selling prices and availability; selling price must exceed buying price.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "WAEC Result Checker", "buy_price": "3800.00", "selling_price": "3900.00", "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox exam action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_exams_post", "summary": "List, update, toggle and export vendor exam providers, selling prices and availability; selling price must exceed buying price.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "WAEC Result Checker", "buy_price": "3800.00", "selling_price": "3900.00", "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox exam action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-exams-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 1, "price": 3900, "providerStatus": true } } } } }, "patch": { "operationId": "vendor_api_exams_patch", "summary": "List, update, toggle and export vendor exam providers, selling prices and availability; selling price must exceed buying price.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "providers": [ { "id": 1, "name": "WAEC Result Checker", "buy_price": "3800.00", "selling_price": "3900.00", "status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox exam action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-exams-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "update", "id": 1, "price": 3900, "providerStatus": true } } } } } }, "\/vendor\/networks": { "get": { "operationId": "vendor_api_networks_get", "summary": "List or update network IDs and per-service availability switches.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "networks": [ { "id": 1, "name": "MTN", "network_id": "1", "sme_id": "1", "gifting_id": "1", "corporate_id": "1", "vtu_id": "1", "network_status": "On", "sme_status": "On", "gifting_status": "On", "corporate_status": "On", "vtu_status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox network action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_networks_post", "summary": "List or update network IDs and per-service availability switches.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "networks": [ { "id": 1, "name": "MTN", "network_id": "1", "sme_id": "1", "gifting_id": "1", "corporate_id": "1", "vtu_id": "1", "network_status": "On", "sme_status": "On", "gifting_status": "On", "corporate_status": "On", "vtu_status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox network action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-networks-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "set_status", "id": 1, "field": "smeStatus", "value": "On" } } } } }, "patch": { "operationId": "vendor_api_networks_patch", "summary": "List or update network IDs and per-service availability switches.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "networks": [ { "id": 1, "name": "MTN", "network_id": "1", "sme_id": "1", "gifting_id": "1", "corporate_id": "1", "vtu_id": "1", "network_status": "On", "sme_status": "On", "gifting_status": "On", "corporate_status": "On", "vtu_status": "On" } ], "action_result": { "updated": 1, "message": "Sandbox network action validated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-networks-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "set_status", "id": 1, "field": "smeStatus", "value": "On" } } } } } }, "\/vendor\/bot-stats": { "get": { "operationId": "vendor_api_bot_stats_get", "summary": "Return BOT KPIs\/logs and use live conversation controls to send, pause or resume Telegram BOT conversations.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "kpis": { "messages_today": 840, "active_conversations": 26, "completed_orders": 112, "failed_orders": 3, "average_response_seconds": 1.4 }, "channels": [ { "channel": "Telegram", "messages": 520 }, { "channel": "WhatsApp", "messages": 320 } ], "conversations": [ { "sender": "2348012345678", "channel": "telegram", "state": "awaiting_plan", "status": "active", "updated_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox conversation action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_bot_stats_post", "summary": "Return BOT KPIs\/logs and use live conversation controls to send, pause or resume Telegram BOT conversations.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "kpis": { "messages_today": 840, "active_conversations": 26, "completed_orders": 112, "failed_orders": 3, "average_response_seconds": 1.4 }, "channels": [ { "channel": "Telegram", "messages": 520 }, { "channel": "WhatsApp", "messages": 320 } ], "conversations": [ { "sender": "2348012345678", "channel": "telegram", "state": "awaiting_plan", "status": "active", "updated_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox conversation action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-stats-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "send", "sender": "2348012345678", "channel": "telegram", "message": "Your request has been resolved." } } } } }, "patch": { "operationId": "vendor_api_bot_stats_patch", "summary": "Return BOT KPIs\/logs and use live conversation controls to send, pause or resume Telegram BOT conversations.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "kpis": { "messages_today": 840, "active_conversations": 26, "completed_orders": 112, "failed_orders": 3, "average_response_seconds": 1.4 }, "channels": [ { "channel": "Telegram", "messages": 520 }, { "channel": "WhatsApp", "messages": 320 } ], "conversations": [ { "sender": "2348012345678", "channel": "telegram", "state": "awaiting_plan", "status": "active", "updated_at": "2026-07-11 10:00:00" } ], "action_result": { "ok": true, "message": "Sandbox conversation action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-bot-stats-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "send", "sender": "2348012345678", "channel": "telegram", "message": "Your request has been resolved." } } } } } }, "\/vendor\/announcements": { "get": { "operationId": "vendor_api_announcements_get", "summary": "List, create, edit, enable, disable or delete vendor announcements\/notifications.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "announcements": [ { "id": 31, "title": "Scheduled maintenance", "message": "Service maintenance starts at 11:00 PM.", "type": "info", "audience": "all", "status": "active", "starts_at": "2026-07-11 20:00:00", "ends_at": "2026-07-12 01:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox announcement action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_announcements_post", "summary": "List, create, edit, enable, disable or delete vendor announcements\/notifications.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "announcements": [ { "id": 31, "title": "Scheduled maintenance", "message": "Service maintenance starts at 11:00 PM.", "type": "info", "audience": "all", "status": "active", "starts_at": "2026-07-11 20:00:00", "ends_at": "2026-07-12 01:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox announcement action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-announcements-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save", "title": "Scheduled maintenance", "message": "Service maintenance begins at 11 PM.", "type": "web", "status": "active" } } } } }, "patch": { "operationId": "vendor_api_announcements_patch", "summary": "List, create, edit, enable, disable or delete vendor announcements\/notifications.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "announcements": [ { "id": 31, "title": "Scheduled maintenance", "message": "Service maintenance starts at 11:00 PM.", "type": "info", "audience": "all", "status": "active", "starts_at": "2026-07-11 20:00:00", "ends_at": "2026-07-12 01:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox announcement action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-announcements-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save", "title": "Scheduled maintenance", "message": "Service maintenance begins at 11 PM.", "type": "web", "status": "active" } } } } }, "delete": { "operationId": "vendor_api_announcements_delete", "summary": "List, create, edit, enable, disable or delete vendor announcements\/notifications.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "announcements": [ { "id": 31, "title": "Scheduled maintenance", "message": "Service maintenance starts at 11:00 PM.", "type": "info", "audience": "all", "status": "active", "starts_at": "2026-07-11 20:00:00", "ends_at": "2026-07-12 01:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox announcement action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-announcements-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "save", "title": "Scheduled maintenance", "message": "Service maintenance begins at 11 PM.", "type": "web", "status": "active" } } } } } }, "\/vendor\/campaigns": { "get": { "operationId": "vendor_api_campaigns_get", "summary": "List\/view\/create\/draft\/queue\/pause\/resume\/cancel\/delete Telegram, Web Push and In-App campaigns.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "campaigns": [ { "id": 21, "channel": "web_push", "title": "Weekend data promo", "message": "Get discounted data plans this weekend.", "status": "sent", "estimated_recipients": 420, "sent_count": 415, "failed_count": 5, "created_at": "2026-07-11 08:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox campaign action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_campaigns_post", "summary": "List\/view\/create\/draft\/queue\/pause\/resume\/cancel\/delete Telegram, Web Push and In-App campaigns.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "campaigns": [ { "id": 21, "channel": "web_push", "title": "Weekend data promo", "message": "Get discounted data plans this weekend.", "status": "sent", "estimated_recipients": 420, "sent_count": 415, "failed_count": 5, "created_at": "2026-07-11 08:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox campaign action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-campaigns-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "queue", "channel": "web_push", "name": "Weekend promo", "subject": "Discounted data plans", "body": "Get discounted data plans this weekend.", "filters": { "all_active_users": true } } } } } }, "patch": { "operationId": "vendor_api_campaigns_patch", "summary": "List\/view\/create\/draft\/queue\/pause\/resume\/cancel\/delete Telegram, Web Push and In-App campaigns.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "campaigns": [ { "id": 21, "channel": "web_push", "title": "Weekend data promo", "message": "Get discounted data plans this weekend.", "status": "sent", "estimated_recipients": 420, "sent_count": 415, "failed_count": 5, "created_at": "2026-07-11 08:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox campaign action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-campaigns-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "queue", "channel": "web_push", "name": "Weekend promo", "subject": "Discounted data plans", "body": "Get discounted data plans this weekend.", "filters": { "all_active_users": true } } } } } }, "delete": { "operationId": "vendor_api_campaigns_delete", "summary": "List\/view\/create\/draft\/queue\/pause\/resume\/cancel\/delete Telegram, Web Push and In-App campaigns.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "campaigns": [ { "id": 21, "channel": "web_push", "title": "Weekend data promo", "message": "Get discounted data plans this weekend.", "status": "sent", "estimated_recipients": 420, "sent_count": 415, "failed_count": 5, "created_at": "2026-07-11 08:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox campaign action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-campaigns-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "queue", "channel": "web_push", "name": "Weekend promo", "subject": "Discounted data plans", "body": "Get discounted data plans this weekend.", "filters": { "all_active_users": true } } } } } } }, "\/vendor\/push-subscribers": { "get": { "operationId": "vendor_api_push_subscribers_get", "summary": "List push subscribers and safely change or revoke subscription status.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "subscribers": [ { "id": 11, "vendor_user_id": 9001, "name": "Sandbox Customer", "endpoint": "https:\/\/push.example.test\/subscription\/********", "browser": "Chrome", "device": "Android", "status": "active", "subscribed_at": "2026-07-10 12:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox subscription action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] }, "post": { "operationId": "vendor_api_push_subscribers_post", "summary": "List push subscribers and safely change or revoke subscription status.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "subscribers": [ { "id": 11, "vendor_user_id": 9001, "name": "Sandbox Customer", "endpoint": "https:\/\/push.example.test\/subscription\/********", "browser": "Chrome", "device": "Android", "status": "active", "subscribed_at": "2026-07-10 12:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox subscription action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-push-subscribers-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "status", "id": 11, "status": "disabled" } } } } }, "patch": { "operationId": "vendor_api_push_subscribers_patch", "summary": "List push subscribers and safely change or revoke subscription status.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "subscribers": [ { "id": 11, "vendor_user_id": 9001, "name": "Sandbox Customer", "endpoint": "https:\/\/push.example.test\/subscription\/********", "browser": "Chrome", "device": "Android", "status": "active", "subscribed_at": "2026-07-10 12:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox subscription action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-push-subscribers-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "status", "id": 11, "status": "disabled" } } } } }, "delete": { "operationId": "vendor_api_push_subscribers_delete", "summary": "List push subscribers and safely change or revoke subscription status.", "description": "A valid active subscribers.sApiKey is required.\nThe authenticated account must have sType = 3. Valid non-vendor API keys receive HTTP 403.\nEvery database operation is automatically scoped to the authenticated vendor_sId; request bodies cannot override the vendor scope.\nPOST\/PATCH\/DELETE requests may send X-Idempotency-Key to safely replay the same request.\nLogo actions accept multipart\/form-data. Export actions return structured JSON or CSV text inside the normal JSON envelope instead of forcing a browser download.\nWhere documented, sensitive account, wallet, withdrawal and WhatsApp-secret operations require the vendor password and PIN in addition to the vendor API key.", "tags": [ "Vendor-specific API" ], "security": [ { "VendorTokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "subscribers": [ { "id": 11, "vendor_user_id": 9001, "name": "Sandbox Customer", "endpoint": "https:\/\/push.example.test\/subscription\/********", "browser": "Chrome", "device": "Android", "status": "active", "subscribed_at": "2026-07-10 12:00:00" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 }, "action_result": { "ok": true, "message": "Sandbox subscription action simulated." } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "vendor_token_required", "message": "This endpoint accepts API keys belonging to vendor accounts only.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "vendor-api-push-subscribers-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "action": "status", "id": 11, "status": "disabled" } } } } } }, "\/payments\/methods": { "get": { "operationId": "payment_methods_get", "summary": "List user-accessible payment methods and current AutoStatement banks.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "methods": [ { "key": "databoom_autostatement", "name": "DataBoom AutoStatement", "enabled": true }, { "key": "bank_transfer", "name": "Bank Transfer", "enabled": true } ], "recommended": "databoom_autostatement" } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] } }, "\/payments\/banks": { "get": { "operationId": "payment_banks_get", "summary": "List enabled AutoStatement bank accounts.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "banks": [ { "code": "000013", "name": "GTBank" }, { "code": "000014", "name": "Access Bank" }, { "code": "000015", "name": "Zenith Bank" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] } }, "\/payments\/request": { "post": { "operationId": "payment_request_post", "summary": "Create an exact-amount AutoStatement payment request for the authenticated user.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "payment_request": { "reference": "FUND-10001", "requested_amount": "5000.00", "exact_amount": "5012.37", "bank_name": "Moniepoint", "account_number": "8888888888", "account_name": "DATABOOM \/ SANDBOX USER", "status": "pending", "expires_at": "2026-07-28 07:09:57" }, "instructions": "Transfer the exact amount shown. The sandbox will not receive or credit real money." } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "payment-request-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "amount": 5000, "reference": "FUND-10001" } } } } } }, "\/payments\/request-status": { "get": { "operationId": "payment_request_status_get", "summary": "Check whether a transfer matching a reference or exact amount has been received.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "found": true, "status": "received", "request": { "reference": "FUND-10001", "exact_amount": "1012.37", "status": "received", "received_at": "2026-07-11 10:05:00" }, "payments": [ { "reference": "SBX-BANK-001", "amount": "1012.37", "sender_name": "SANDBOX USER", "bank_name": "Access Bank", "status": "matched" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "example": "FUND-10001" } ] }, "post": { "operationId": "payment_request_status_post", "summary": "Check whether a transfer matching a reference or exact amount has been received.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "found": true, "status": "received", "request": { "reference": "FUND-10001", "exact_amount": "1012.37", "status": "received", "received_at": "2026-07-11 10:05:00" }, "payments": [ { "reference": "SBX-BANK-001", "amount": "1012.37", "sender_name": "SANDBOX USER", "bank_name": "Access Bank", "status": "matched" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "payment-request-status-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "reference": "FUND-10001" } } } } } }, "\/payments\/history": { "get": { "operationId": "payment_history_get", "summary": "List the authenticated user\u2019s AutoStatement bank payments and related wallet transactions.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "payments": [ { "id": 1, "reference": "SBX-BANK-001", "requested_amount": "1000.00", "exact_amount": "1012.37", "amount_received": "1012.37", "bank_name": "Moniepoint", "sender_name": "SANDBOX USER", "status": "credited", "received_at": "2026-07-11 10:05:00", "credited_transaction_reference": "SBX-CREDIT-001" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-11" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 50 } ] }, "post": { "operationId": "payment_history_post", "summary": "List the authenticated user\u2019s AutoStatement bank payments and related wallet transactions.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "payments": [ { "id": 1, "reference": "SBX-BANK-001", "requested_amount": "1000.00", "exact_amount": "1012.37", "amount_received": "1012.37", "bank_name": "Moniepoint", "sender_name": "SANDBOX USER", "status": "credited", "received_at": "2026-07-11 10:05:00", "credited_transaction_reference": "SBX-CREDIT-001" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "pages": 1 } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Recommended for write and payment requests to prevent accidental duplicates.", "schema": { "type": "string", "maxLength": 190 }, "example": "payment-history-10001" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object" }, "example": { "date_from": "2026-07-01", "date_to": "2026-07-11", "page": 1, "per_page": 50 } } } } } }, "\/payments\/linked-accounts": { "get": { "operationId": "payment_linked_accounts_get", "summary": "List the authenticated user\u2019s verified payer names and enabled bank accounts.", "description": "Any active DataBoom user API key may use this endpoint.\nThe server forces owner_id=0 and external_user_id to the authenticated user, so one user cannot query another user\u2019s payments.\nUse X-Idempotency-Key for payment-request POST retries.", "tags": [ "Payments & AutoStatement" ], "security": [ { "TokenAuth": [] }, { "SandboxTokenAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application\/json": { "example": { "status": "success", "data": { "user": { "id": 1001, "name": "John Doe" }, "accounts": [ { "provider": "databoom_autostatement", "bank_name": "Moniepoint", "account_number": "8888888888", "account_name": "DATABOOM \/ SANDBOX USER", "status": "active" }, { "provider": "pocketfi", "bank_name": "Wema Bank", "account_number": "1234567890", "account_name": "SANDBOX USER", "status": "active" } ] } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application\/json": { "example": { "status": "fail", "code": "invalid_token", "message": "The supplied API key is invalid.", "request_id": "f6de4a7c9a3b4e7d" } } } }, "429": { "description": "Rate limited", "content": { "application\/json": { "example": { "status": "fail", "code": "sandbox_rate_limit", "message": "Sandbox request limit exceeded. Try again in one minute.", "environment": "sandbox", "sandbox": true, "request_id": "sbx_0123456789abcdef0123" } } } }, "500": { "description": "Server Error" } }, "x-databoom-sandbox-supported": true, "parameters": [ { "name": "X-API-Environment", "in": "header", "required": false, "description": "Set to sandbox when using a sandbox API key. The sandbox key itself remains required.", "schema": { "type": "string", "enum": [ "sandbox" ] }, "example": "sandbox" } ] } } } }