{ "openapi": "3.0.3", "info": { "title": "SYSNAV M-Pesa Payment Gateway API", "version": "1.0.0", "description": "A multi-tenant payment gateway that unifies **Safaricom Daraja**, **KCB Buni** and **Equity Jenga** behind one REST API.\n\n## Authentication\nProtected endpoints accept either:\n- an **API key** via the `X-API-Key` header (or `?apiKey=` query param), or\n- a **JWT** via `Authorization: Bearer ` (issued after OTP login).\n\n## Providers\nThe same request body works for all three rails — the gateway routes to whichever provider is stored on the client's active credential record.", "contact": { "name": "SYSNAV Support", "email": "support@navipos.co.ke" } }, "servers": [ { "url": "https://payments.navipos.co.ke", "description": "Current environment" } ], "tags": [ { "name": "System", "description": "Health and diagnostics" }, { "name": "Authentication", "description": "Registration, login and OTP verification" }, { "name": "Clients", "description": "Client account and provider credentials" }, { "name": "Payments", "description": "STK push, C2B and transactions" }, { "name": "QR Payments", "description": "Public scan-to-pay endpoints" }, { "name": "Webhooks", "description": "Inbound provider callbacks" }, { "name": "SMS", "description": "SMS credentials, templates and campaigns" }, { "name": "Email", "description": "SMTP configuration and delivery" }, { "name": "Dashboard", "description": "Aggregate statistics" }, { "name": "Reconciliation", "description": "Settlement reconciliation" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "API key or JWT token required" } } }, "RegisterClient": { "type": "object", "required": [ "name", "businessType", "email", "phone", "password" ], "properties": { "name": { "type": "string", "example": "My Business Ltd" }, "businessType": { "type": "string", "example": "Retail" }, "email": { "type": "string", "format": "email", "example": "owner@mybusiness.com" }, "phone": { "type": "string", "example": "254712345678" }, "password": { "type": "string", "format": "password", "example": "S3cure!pass" } } }, "DarajaCredentials": { "type": "object", "required": [ "consumerKey", "consumerSecret", "shortcode", "passkey", "environment" ], "properties": { "provider": { "type": "string", "enum": [ "daraja", "kcb", "equity" ], "default": "daraja" }, "consumerKey": { "type": "string" }, "consumerSecret": { "type": "string" }, "shortcode": { "type": "string", "example": "174379" }, "passkey": { "type": "string" }, "initiatorName": { "type": "string", "example": "testapi" }, "initiatorPassword": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } } }, "StkPush": { "type": "object", "required": [ "phoneNumber", "amount", "reference", "description" ], "properties": { "phoneNumber": { "type": "string", "example": "254712345678" }, "amount": { "type": "number", "example": 1000 }, "reference": { "type": "string", "example": "ORDER-123456" }, "description": { "type": "string", "example": "Payment for order #123456" }, "telco": { "type": "string", "enum": [ "Safaricom", "Equitel" ], "description": "Only used when provider is equity." } } }, "Transaction": { "type": "object", "properties": { "transactionId": { "type": "string" }, "phoneNumber": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, "mpesaReceiptNumber": { "type": "string" }, "accountReference": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "paths": { "/api/v1/health": { "get": { "tags": [ "System" ], "summary": "Health check", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "healthy", "timestamp": "2026-01-15T10:30:00+00:00", "version": "1.0.0", "services": { "database": "healthy", "api": "healthy" } } } } } } } }, "/api/v1/test-db": { "get": { "tags": [ "System" ], "summary": "Database connectivity test", "security": [], "responses": { "200": { "description": "Database reachable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/clients": { "post": { "tags": [ "Authentication" ], "summary": "Register a new client", "security": [], "description": "Creates a client account (status `inactive`) and dispatches an OTP by SMS and email for verification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterClient" } } } }, "responses": { "201": { "description": "Client created; OTP dispatched", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "clientId": "550e8400-e29b-41d4-a716-446655440000", "apiKey": "pk_live_7c3f…" }, "message": "Client registered. Verify the OTP sent to your phone/email." } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Clients" ], "summary": "Get authenticated client details", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Client details", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Login (step 1 — request OTP)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } } } } } }, "responses": { "200": { "description": "OTP dispatched", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/send-otp": { "post": { "tags": [ "Authentication" ], "summary": "Send / resend an OTP", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "OTP sent", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/auth/verify-otp": { "post": { "tags": [ "Authentication" ], "summary": "Verify OTP (step 2 — issue JWT)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string" }, "code": { "type": "string", "example": "123456" } } } } } }, "responses": { "200": { "description": "Verified; JWT returned", "content": { "application/json": { "schema": { "type": "object" }, "example": { "token": "eyJhbGciOi…", "expiresIn": 3600 } } } } } } }, "/api/v1/clients/{id}/credentials": { "post": { "tags": [ "Clients" ], "summary": "Store provider credentials", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DarajaCredentials" } } } }, "responses": { "201": { "description": "Credentials stored (encrypted at rest)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Clients" ], "summary": "Get stored credentials (masked)", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "responses": { "200": { "description": "Masked credentials", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stk-push": { "post": { "tags": [ "Payments" ], "summary": "Initiate STK push", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Sends an STK prompt to the customer via the client's active provider (Daraja, KCB or Equity).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StkPush" } } } }, "responses": { "200": { "description": "STK push accepted", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "transactionId": "txn_7a3f…", "checkoutRequestId": "ws_CO_…", "responseCode": "0", "status": "pending" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/c2b-register": { "post": { "tags": [ "Payments" ], "summary": "Register C2B validation/confirmation URLs", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shortCode", "validationUrl", "confirmationUrl" ], "properties": { "shortCode": { "type": "string", "example": "123456" }, "validationUrl": { "type": "string", "format": "uri" }, "confirmationUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "URLs registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/c2b-simulate": { "post": { "tags": [ "Payments" ], "summary": "Simulate a C2B payment (sandbox only)", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shortCode", "phoneNumber", "amount" ], "properties": { "shortCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "amount": { "type": "number" }, "billRefNumber": { "type": "string" } } } } } }, "responses": { "200": { "description": "Simulation accepted", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/c2b-verify": { "get": { "tags": [ "Payments" ], "summary": "Verify C2B registration status", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions": { "get": { "tags": [ "Payments" ], "summary": "List transactions", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated transactions", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get a transaction", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transaction ID" } ], "responses": { "200": { "description": "Transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pay/{clientId}/info": { "get": { "tags": [ "QR Payments" ], "summary": "Get merchant info for a QR pay page", "security": [], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "responses": { "200": { "description": "Merchant display info", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/pay/{clientId}/initiate": { "post": { "tags": [ "QR Payments" ], "summary": "Initiate a scan-to-pay STK push", "security": [], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StkPush" } } } }, "responses": { "200": { "description": "STK push accepted", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/pay/{clientId}/status/{checkoutId}": { "get": { "tags": [ "QR Payments" ], "summary": "Poll QR payment status", "security": [], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" }, { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Checkout request ID" } ], "responses": { "200": { "description": "Current status", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/webhooks/mpesa": { "post": { "tags": [ "Webhooks" ], "summary": "Safaricom Daraja callback", "security": [], "description": "Called by the upstream provider — configure this URL with the provider, not from your app.", "responses": { "200": { "description": "Acknowledged", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/webhooks/kcb": { "post": { "tags": [ "Webhooks" ], "summary": "KCB Buni callback", "security": [], "description": "Called by the upstream provider — configure this URL with the provider, not from your app.", "responses": { "200": { "description": "Acknowledged", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/webhooks/equity": { "post": { "tags": [ "Webhooks" ], "summary": "Equity Jenga callback", "security": [], "description": "Called by the upstream provider — configure this URL with the provider, not from your app.", "responses": { "200": { "description": "Acknowledged", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/c2b-validation": { "post": { "tags": [ "Webhooks" ], "summary": "C2B validation callback", "security": [], "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/c2b-confirmation": { "post": { "tags": [ "Webhooks" ], "summary": "C2B confirmation callback", "security": [], "responses": { "200": { "description": "Acknowledged", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/clients/{id}/sms-config": { "post": { "tags": [ "SMS" ], "summary": "Save SMS provider config", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "tags": [ "SMS" ], "summary": "Get SMS provider config", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sms/balance": { "get": { "tags": [ "SMS" ], "summary": "Get SMS account balance", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sms/send": { "post": { "tags": [ "SMS" ], "summary": "Send an SMS campaign", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipients", "message" ], "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "example": [ "254712345678" ] }, "message": { "type": "string" }, "scheduleAt": { "type": "string", "format": "date-time" }, "flash": { "type": "boolean" }, "unicode": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Campaign queued", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sms/campaigns": { "get": { "tags": [ "SMS" ], "summary": "Campaign history", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Campaigns", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sms/campaigns/{id}": { "get": { "tags": [ "SMS" ], "summary": "Campaign detail", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Campaign ID" } ], "responses": { "200": { "description": "Campaign", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sms/templates": { "get": { "tags": [ "SMS" ], "summary": "List local templates", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "SMS" ], "summary": "Save a local template", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/clients/{id}/smtp": { "post": { "tags": [ "Email" ], "summary": "Save SMTP config", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "tags": [ "Email" ], "summary": "Get SMTP config", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Client ID" } ], "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/email/send": { "post": { "tags": [ "Email" ], "summary": "Send an email", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "subject", "body" ], "properties": { "to": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "body": { "type": "string" } } } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/dashboard/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Aggregate statistics", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/reconciliation/report": { "get": { "tags": [ "Reconciliation" ], "summary": "Reconciliation report", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/reconciliation/mismatches": { "get": { "tags": [ "Reconciliation" ], "summary": "List mismatches", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Mismatches", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/reconciliation/resolve/{id}": { "post": { "tags": [ "Reconciliation" ], "summary": "Resolve a mismatch", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Mismatch ID" } ], "responses": { "200": { "description": "Resolved", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/reconciliation/run": { "post": { "tags": [ "Reconciliation" ], "summary": "Trigger a reconciliation run", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Run started", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }