{ "openapi": "3.0.0", "info": { "description": "API Gateway for SmartPay NFC Card Payment System - Comprehensive payment, card management, agent operations, and admin authentication. All /api/v1 routes require authentication using either API Key or JWT token.", "title": "SmartPay NFC Card Payment API", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "API Support", "email": "support@smartpay.sl" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0" }, "paths": { "/account-rules": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "List account rules for all KYC levels", "tags": [ "Account Rules" ], "summary": "List all account rules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create new balance and transaction limits for a KYC level (admin only)", "tags": [ "Account Rules" ], "summary": "Create account rules for KYC level", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateAccountRulesRequest" } } }, "description": "Account rules configuration", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/account-rules/{id}": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update existing account rules for a KYC level (admin only)", "tags": [ "Account Rules" ], "summary": "Update account rules", "parameters": [ { "description": "Account Rules ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UpdateAccountRulesRequest" } } }, "description": "Updated account rules", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/account-rules/{kyc_level}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get balance and transaction limits for a specific KYC level", "tags": [ "Account Rules" ], "summary": "Get account rules for KYC level", "parameters": [ { "description": "KYC Level (1-3)", "name": "kyc_level", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/admin/change-password": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Allows authenticated system users to change their password", "tags": [ "Admin" ], "summary": "Change user password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ChangePasswordRequest" } } }, "description": "Password change details", "required": true }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "401": { "description": "Unauthorized or incorrect old password", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/admin/login": { "post": { "description": "Authenticates an admin user or processor and returns a JWT token", "tags": [ "Admin" ], "summary": "User login (Admin or Processor)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.LoginRequest" } } }, "description": "Login credentials", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.LoginResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/admin/logout": { "post": { "description": "Revokes the refresh token to prevent future token refreshes", "tags": [ "Admin" ], "summary": "Logout and revoke refresh token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.LogoutRequest" } } }, "description": "Refresh token to revoke", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/admin/me": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns details of the currently authenticated user", "tags": [ "Admin" ], "summary": "Get current logged-in user details", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UserInfo" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/admin/refresh": { "post": { "description": "Issues a new access token using a valid refresh token", "tags": [ "Admin" ], "summary": "Refresh access token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.RefreshTokenRequest" } } }, "description": "Refresh token", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.LoginResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/admin/transactions": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get all transactions with optional filtering (admin only)", "tags": [ "Admin" ], "summary": "List all transactions (Admin)", "parameters": [ { "description": "Number of records (max 100)", "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "description": "Offset for pagination", "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "description": "Filter by transaction type (e.g., agent_cashin, transfer_p2p)", "name": "transaction_type", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by status (e.g., completed, pending)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Start date filter (YYYY-MM-DD)", "name": "start_date", "in": "query", "schema": { "type": "string" } }, { "description": "End date filter (YYYY-MM-DD)", "name": "end_date", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by user/subscriber ID", "name": "user_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of transactions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/admin/users": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of all system users (admin only)", "tags": [ "Admin" ], "summary": "List all system users", "parameters": [ { "description": "Filter by role", "name": "role", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by status", "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ListUsersResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Allows system admin to create new users with roles (admin, sales, agent, etc.)", "tags": [ "Admin" ], "summary": "Create a new system user", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateUserRequest" } } }, "description": "User details", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateUserResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/admin/users/{id}/status": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Activates, suspends, or deactivates a user account", "tags": [ "Admin" ], "summary": "Update user status", "parameters": [ { "description": "User ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UpdateUserStatusRequest" } } }, "description": "Status update", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/agents": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "List agents with optional filtering by type and parent", "tags": [ "Agents" ], "summary": "List all agents", "parameters": [ { "description": "Filter by agent type (super_agent or sub_agent)", "name": "agent_type", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by parent agent ID", "name": "parent_agent_id", "in": "query", "schema": { "type": "string" } }, { "description": "Number of results to return", "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "description": "Offset for pagination", "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Register a super-agent or sub-agent for the system. Only admins can register super-agents. Both admins and super-agents can register sub-agents.", "tags": [ "Agents" ], "summary": "Register a new agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.RegisterAgentRequest" } } }, "description": "Agent registration details", "required": true }, "responses": { "201": { "description": "Agent registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.RegisterAgentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/cashin": { "post": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Process cash-in transaction from agent to subscriber. Agent authenticates with their own PIN, not subscriber's PIN.", "tags": [ "Agents" ], "summary": "Agent cash-in transaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.AgentCashInRequest" } } }, "description": "Cash-in details", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/lookup": { "get": { "description": "Check if a phone number belongs to a registered agent", "tags": [ "Agents" ], "summary": "Lookup agent by phone number", "parameters": [ { "description": "Phone number in E.164 format", "name": "phone_number", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/transfer": { "post": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Super-agent transfers float to their sub-agent. Super-agent ID is auto-detected from logged-in user. Admin can specify super_agent_id.", "tags": [ "Agents" ], "summary": "Transfer float to sub-agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.TransferToSubAgentRequest" } } }, "description": "Transfer details", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/{id}": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get detailed information about an agent", "tags": [ "Agents" ], "summary": "Get agent details", "parameters": [ { "description": "Agent ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/{id}/balance": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get current float balance for an agent", "tags": [ "Agents" ], "summary": "Get agent balance", "parameters": [ { "description": "Agent ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/{id}/change-pin": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Change an agent's PIN by providing the current PIN and new PIN", "tags": [ "Agents" ], "summary": "Change agent PIN", "parameters": [ { "description": "Agent ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ChangeAgentPINRequest" } } }, "description": "PIN change details", "required": true }, "responses": { "200": { "description": "PIN changed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request or PIN", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agents/{id}/fund": { "post": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Add float to an agent's account. Admin can fund any agent. Super-agent can fund their sub-agents.", "tags": [ "Agents" ], "summary": "Fund agent account", "parameters": [ { "description": "Agent ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.FundAgentRequest" } } }, "description": "Fund amount", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api-keys": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "List all API keys with optional status filter", "tags": [ "API Keys" ], "summary": "List all API keys", "parameters": [ { "description": "Filter by status", "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "revoked", "expired" ] } } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create a new API key for third-party integration", "tags": [ "API Keys" ], "summary": "Create a new API key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateAPIKeyRequest" } } }, "description": "API key details", "required": true }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api-keys/scopes": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get predefined scope templates for common integrations", "tags": [ "API Keys" ], "summary": "Get predefined scope templates", "responses": { "200": { "description": "Scope templates", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api-keys/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get details of a specific API key (without the actual key). Processors can only view their own API key.", "tags": [ "API Keys" ], "summary": "Get API key details", "parameters": [ { "description": "API Key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api-keys/{id}/revoke": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Revoke an API key to prevent further use", "tags": [ "API Keys" ], "summary": "Revoke an API key", "parameters": [ { "description": "API Key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key revoked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api-keys/{id}/stats": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get usage statistics for an API key. Processors can only view stats for their own API key.", "tags": [ "API Keys" ], "summary": "Get API key usage statistics", "parameters": [ { "description": "API Key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key usage statistics", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/public/subscribers": { "post": { "description": "Create a new subscriber without authentication. Intended for third-party integrations.", "tags": [ "Subscribers" ], "summary": "Create new subscriber (public endpoint)", "requestBody": { "$ref": "#/components/requestBodies/handler.RegisterSubscriberRequest" }, "responses": { "201": { "description": "Subscriber created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of all NFC cards with optional filters", "tags": [ "Cards" ], "summary": "List all cards", "parameters": [ { "description": "Page number (default 1)", "name": "page", "in": "query", "schema": { "type": "integer" } }, { "description": "Page size (default 50)", "name": "page_size", "in": "query", "schema": { "type": "integer" } }, { "description": "Filter by status (active, blocked, pending)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by card type (parent, child)", "name": "card_type", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by subscriber ID", "name": "subscriber_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of cards", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/child": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Create a child card linked to parent subscriber with spending limits. Requires parent's PIN for authentication and a separate PIN for the child's card transactions. The child will use their own PIN when making payments for security.", "tags": [ "Cards" ], "summary": "Create child card", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateChildCardRequest" } } }, "description": "Child card details", "required": true }, "responses": { "201": { "description": "Child card created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/child/change-pin": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Parent changes the PIN for a child card. Requires parent's PIN for authentication, current child PIN, and new child PIN. The child uses their PIN when making payments for security.", "tags": [ "Cards" ], "summary": "Change child card PIN", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ChangeChildCardPINRequest" } } }, "description": "Change child card PIN details", "required": true }, "responses": { "200": { "description": "PIN changed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/link": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Link a parent NFC card to a subscriber account", "tags": [ "Cards" ], "summary": "Link parent card to subscriber", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.LinkCardRequest" } } }, "description": "Link card details", "required": true }, "responses": { "200": { "description": "Card linked successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/upload-csv": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Admin uploads CSV file containing Serial No. and MAC Address (supports both 6-octet and 7-octet formats). Valid records are inserted with status = \"Unassigned\"", "tags": [ "Cards" ], "summary": "Upload NFC cards via CSV file", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "CSV file with columns: serial_number, mac_address", "type": "string", "format": "binary" }, "batch_id": { "description": "Batch identifier", "type": "string" } }, "required": [ "file", "batch_id" ] } } }, "required": true }, "responses": { "200": { "description": "Upload successful with error log if any", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid CSV format", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/{serial}": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get NFC card details by serial number", "tags": [ "Cards" ], "summary": "Get card details", "parameters": [ { "description": "Card Serial Number", "name": "serial", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/{serial}/block": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Block an NFC card with a reason", "tags": [ "Cards" ], "summary": "Block a card", "parameters": [ { "description": "Card Serial Number", "name": "serial", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.BlockCardRequest" } } }, "description": "Block reason", "required": true }, "responses": { "200": { "description": "Card blocked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/cards/{serial}/unblock": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Unblock a previously blocked NFC card", "tags": [ "Cards" ], "summary": "Unblock a card", "parameters": [ { "description": "Card Serial Number", "name": "serial", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UnblockCardRequest" } } }, "description": "PIN for non-admin users" }, "responses": { "200": { "description": "Card unblocked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/compliance/alerts": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get a list of compliance alerts with optional filters", "tags": [ "Compliance Alerts" ], "summary": "List compliance alerts", "parameters": [ { "description": "Filter by subscriber ID", "name": "subscriber_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by status (open/investigating/resolved/false_positive)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Limit number of results", "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "description": "Offset for pagination", "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Manually create a compliance alert (compliance and admin only)", "tags": [ "Compliance Alerts" ], "summary": "Create a compliance alert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateComplianceAlertRequest" } } }, "description": "Alert details", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/compliance/alerts/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve details of a specific compliance alert", "tags": [ "Compliance Alerts" ], "summary": "Get compliance alert by ID", "parameters": [ { "description": "Alert ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update the status of a compliance alert", "tags": [ "Compliance Alerts" ], "summary": "Update compliance alert status", "parameters": [ { "description": "Alert ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UpdateComplianceAlertRequest" } } }, "description": "Updated alert details", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/compliance/alerts/{id}/resolve": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Mark a compliance alert as resolved or false positive", "tags": [ "Compliance Alerts" ], "summary": "Resolve a compliance alert", "parameters": [ { "description": "Alert ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ResolveAlertRequest" } } }, "description": "Resolution details", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/compliance/rules": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get a list of all monitoring rules with optional status filter", "tags": [ "Monitoring Rules" ], "summary": "List all monitoring rules", "parameters": [ { "description": "Filter by status (active/inactive)", "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create a new transaction monitoring rule with thresholds and actions", "tags": [ "Monitoring Rules" ], "summary": "Create a new monitoring rule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateMonitoringRuleRequest" } } }, "description": "Monitoring Rule Details", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/compliance/rules/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve details of a specific monitoring rule", "tags": [ "Monitoring Rules" ], "summary": "Get a monitoring rule by ID", "parameters": [ { "description": "Monitoring Rule ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update an existing monitoring rule's thresholds and settings", "tags": [ "Monitoring Rules" ], "summary": "Update a monitoring rule", "parameters": [ { "description": "Monitoring Rule ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UpdateMonitoringRuleRequest" } } }, "description": "Updated Rule Details", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Soft delete a monitoring rule by setting it to inactive", "tags": [ "Monitoring Rules" ], "summary": "Delete a monitoring rule", "parameters": [ { "description": "Monitoring Rule ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/fee-settings": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get all configured fee settings", "tags": [ "Fee Settings" ], "summary": "List all fee settings", "parameters": [ { "description": "Filter by transaction type", "name": "transaction_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update existing or create new fee settings (admin only)", "tags": [ "Fee Settings" ], "summary": "Update or create fee settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.FeeSettingsRequest" } } }, "description": "Fee settings configuration", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/fee-settings/{transaction_type}/{party_type}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get configured fee settings for a specific combination", "tags": [ "Fee Settings" ], "summary": "Get fee settings for specific transaction and party", "parameters": [ { "description": "Transaction Type", "name": "transaction_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Party Type", "name": "party_type", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Remove custom fee settings and revert to defaults (admin only)", "tags": [ "Fee Settings" ], "summary": "Delete fee settings", "parameters": [ { "description": "Transaction Type", "name": "transaction_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Party Type", "name": "party_type", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pep/request-access": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Generate and send OTP for accessing a PEP account (requires PEP authorization)", "tags": [ "PEP Access" ], "summary": "Request OTP for PEP account access", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.RequestPEPAccessRequest" } } }, "description": "PEP access request", "required": true }, "responses": { "200": { "description": "OTP sent successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Not authorized for PEP access", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pep/verify-access": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Verify the OTP code and grant access to PEP account", "tags": [ "PEP Access" ], "summary": "Verify OTP for PEP account access", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.VerifyPEPAccessRequest" } } }, "description": "OTP verification", "required": true }, "responses": { "200": { "description": "Access granted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid OTP", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pos/lookup-card": { "post": { "description": "Get card ownership and balance by serial number or MAC address (with or without colons)", "tags": [ "POS" ], "summary": "Lookup card information", "requestBody": { "$ref": "#/components/requestBodies/handler.POSLookupCardRequest" }, "responses": { "200": { "description": "Card information retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "operationId": "post-pos-lookup-card" } }, "/pos/payment": { "post": { "description": "Process NFC card payment at Smart PAY POS terminal", "tags": [ "POS" ], "summary": "Process POS payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.AppPaymentRequest" } } }, "description": "POS payment details", "required": true }, "responses": { "200": { "description": "Payment approved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Payment declined", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pos/refund": { "post": { "description": "Refund a previous POS payment transaction", "tags": [ "POS" ], "summary": "Refund POS payment", "requestBody": { "$ref": "#/components/requestBodies/handler.POSRefundRequest" }, "responses": { "200": { "description": "Refund processed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refund failed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "operationId": "post-pos-refund" } }, "/pos/verify-card": { "post": { "description": "Verify card status and balance before payment", "tags": [ "POS" ], "summary": "Verify NFC card", "requestBody": { "$ref": "#/components/requestBodies/handler.POSVerifyCardRequest" }, "responses": { "200": { "description": "Card verified", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Card verification failed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "operationId": "post-pos-verify-card" } }, "/payment": { "post": { "description": "Process an in-app SmartPay payment", "tags": [ "Payment" ], "summary": "Process in-app payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.POSPaymentRequest" } } }, "description": "In-app payment details", "required": true }, "responses": { "200": { "description": "Payment approved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Payment declined", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/payment/lookup-card": { "post": { "description": "Get card ownership and balance by serial number or MAC address (with or without colons)", "tags": [ "POS" ], "summary": "Lookup card information", "requestBody": { "$ref": "#/components/requestBodies/handler.POSLookupCardRequest" }, "responses": { "200": { "description": "Card information retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "operationId": "post-payment-lookup-card" } }, "/payment/refund": { "post": { "description": "Refund a previous POS payment transaction", "tags": [ "POS" ], "summary": "Refund POS payment", "requestBody": { "$ref": "#/components/requestBodies/handler.POSRefundRequest" }, "responses": { "200": { "description": "Refund processed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refund failed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "operationId": "post-payment-refund" } }, "/payment/verify-account": { "post": { "description": "Verify if an SmartPay account ID exists in the database (HMAC authenticated endpoint for processors)", "tags": [ "POS" ], "summary": "Verify if account ID exists", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.VerifyAccountExistsRequest" } } }, "description": "Account verification details", "required": true }, "responses": { "200": { "description": "Account verification result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/payment/verify-card": { "post": { "description": "Verify card status and balance before payment", "tags": [ "POS" ], "summary": "Verify NFC card", "requestBody": { "$ref": "#/components/requestBodies/handler.POSVerifyCardRequest" }, "responses": { "200": { "description": "Card verified", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Card verification failed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "operationId": "post-payment-verify-card" } }, "/processors": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve list of all payment processors with pagination", "tags": [ "Processors" ], "summary": "List all processors", "parameters": [ { "description": "Limit", "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of processors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Register a new payment processor (merchant) with associated subscriber account", "tags": [ "Processors" ], "summary": "Create new payment processor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateProcessorRequest" } } }, "description": "Processor details", "required": true }, "responses": { "200": { "description": "Processor created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/processors/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve details of a specific processor by ID", "tags": [ "Processors" ], "summary": "Get processor details", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Processor details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Processor not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update name, phone number, or email of an existing processor", "tags": [ "Processors" ], "summary": "Update processor details", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UpdateProcessorRequest" } } }, "description": "Updated processor details", "required": true }, "responses": { "200": { "description": "Processor updated successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Processor not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/processors/{id}/api-credentials": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Processor retrieves their API key details from their dashboard (keys are not returned). Processors can only view their own credentials.", "tags": [ "Processors" ], "summary": "Get processor API credentials", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API credentials retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/processors/{id}/reclaim": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Submit a request to reclaim funds from processor account (admin will review)", "tags": [ "Processors" ], "summary": "Create reclaim request", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.CreateReclaimRequestRequest" } } }, "description": "Reclaim request details", "required": true }, "responses": { "200": { "description": "Reclaim request created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Processor not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/processors/{id}/suspend": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Suspend a processor to prevent transactions", "tags": [ "Processors" ], "summary": "Suspend a processor", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.SuspendProcessorRequest" } } }, "description": "Suspension reason", "required": true }, "responses": { "200": { "description": "Processor suspended successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Processor not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/processors/{id}/transactions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve transaction history for a processor account", "tags": [ "Processors" ], "summary": "Get processor transaction history", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Number of transactions to return (default: 20, max: 100)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Offset for pagination (default: 0)", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transaction history retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Processor not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/processors/{id}/transfer": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Transfer money from processor account to any SmartPay subscriber account", "tags": [ "Processors" ], "summary": "Transfer funds from processor to account", "parameters": [ { "description": "Processor ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ProcessorTransferRequest" } } }, "description": "Transfer details", "required": true }, "responses": { "200": { "description": "Transfer completed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Processor or account not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/reclaim-requests": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Processors" ], "summary": "List reclaim requests", "parameters": [ { "description": "Processor ID filter", "name": "processor_id", "in": "query", "schema": { "type": "string" } }, { "description": "Status filter (pending, approved, rejected)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Limit", "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of reclaim requests", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/reclaim-requests/{id}/review": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Approve or reject a pending reclaim request", "tags": [ "Processors" ], "summary": "Review reclaim request (Admin only)", "parameters": [ { "description": "Reclaim Request ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ReviewReclaimRequestRequest" } } }, "description": "Review details", "required": true }, "responses": { "200": { "description": "Request reviewed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of all subscribers with their details including balance", "tags": [ "Subscribers" ], "summary": "List all subscribers", "parameters": [ { "description": "Page number (default 1)", "name": "page", "in": "query", "schema": { "type": "integer" } }, { "description": "Page size (default 50)", "name": "page_size", "in": "query", "schema": { "type": "integer" } }, { "description": "Filter by status (active, blocked, pending)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by KYC level (1, 2, 3)", "name": "kyc_level", "in": "query", "schema": { "type": "integer" } }, { "description": "Filter by district", "name": "district", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of subscribers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Register a new subscriber with KYC details", "tags": [ "Subscribers" ], "summary": "Register a new subscriber", "requestBody": { "$ref": "#/components/requestBodies/handler.RegisterSubscriberRequest" }, "responses": { "201": { "description": "Subscriber created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/lookup": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get subscriber details by phone number", "tags": [ "Subscribers" ], "summary": "Get subscriber by phone number", "parameters": [ { "description": "Phone number", "name": "phone_number", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscriber details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/{id}": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get subscriber details by subscriber ID", "tags": [ "Subscribers" ], "summary": "Get subscriber details", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscriber details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "put": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Update subscriber information including KYC level and VULT wallet ID", "tags": [ "Subscribers" ], "summary": "Update subscriber details", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.UpdateSubscriberRequest" } } }, "description": "Update details", "required": true }, "responses": { "200": { "description": "Update successful", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/{id}/block": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Block a subscriber account with a reason", "tags": [ "Subscribers" ], "summary": "Block a subscriber", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.BlockSubscriberRequest" } } }, "description": "Block reason", "required": true }, "responses": { "200": { "description": "Block successful", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/{id}/cards": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "List all NFC cards linked to a subscriber", "tags": [ "Cards" ], "summary": "List subscriber cards", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of cards", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/{id}/change-pin": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Change a subscriber's 4-digit PIN", "tags": [ "Subscribers" ], "summary": "Change subscriber PIN", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.ChangeSubscriberPINRequest" } } }, "description": "PIN change details", "required": true }, "responses": { "200": { "description": "PIN changed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request or PIN", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/{id}/unblock": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Unblock a previously blocked subscriber account", "tags": [ "Subscribers" ], "summary": "Unblock a subscriber", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unblock successful", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/subscribers/{id}/verify-pin": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Verify a subscriber's PIN for authentication", "tags": [ "Subscribers" ], "summary": "Verify subscriber PIN", "parameters": [ { "description": "Subscriber ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.VerifyPINRequest" } } }, "description": "PIN to verify", "required": true }, "responses": { "200": { "description": "PIN verification result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/transactions/suspicious": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve transactions flagged as suspicious by fraud detection system", "tags": [ "Compliance" ], "summary": "Get suspicious transactions", "parameters": [ { "description": "Page number", "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "description": "Records per page (max 100)", "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "description": "Start date (YYYY-MM-DD)", "name": "from_date", "in": "query", "schema": { "type": "string" } }, { "description": "End date (YYYY-MM-DD)", "name": "to_date", "in": "query", "schema": { "type": "string" } }, { "description": "Risk severity: low, medium, high, critical, all", "name": "severity", "in": "query", "schema": { "type": "string", "default": "\"all\"" } }, { "description": "Review status: pending, under_review, cleared, confirmed, all", "name": "status", "in": "query", "schema": { "type": "string", "default": "\"all\"" } }, { "description": "Filter by subscriber ID", "name": "subscriber_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by agent ID", "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "description": "Transaction type filter", "name": "transaction_type", "in": "query", "schema": { "type": "string", "default": "\"all\"" } }, { "description": "Minimum amount filter", "name": "min_amount", "in": "query", "schema": { "type": "number" } }, { "description": "Maximum amount filter", "name": "max_amount", "in": "query", "schema": { "type": "number" } }, { "description": "Sort field: created_at, amount, severity, risk_score", "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "\"created_at\"" } }, { "description": "Sort order: asc, desc", "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "\"desc\"" } } ], "responses": { "200": { "description": "Suspicious transactions retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/transactions/suspicious/summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve aggregated statistics about suspicious transactions", "tags": [ "Compliance" ], "summary": "Get suspicious transactions summary", "parameters": [ { "description": "Start date (YYYY-MM-DD)", "name": "from_date", "in": "query", "schema": { "type": "string", "default": "\"30 days ago\"" } }, { "description": "End date (YYYY-MM-DD)", "name": "to_date", "in": "query", "schema": { "type": "string", "default": "\"today\"" } } ], "responses": { "200": { "description": "Summary statistics retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wallet/account-statement": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get comprehensive financial statement for a subscriber with all transactions within date range. Returns data for PDF generation and WhatsApp delivery.", "tags": [ "Wallet" ], "summary": "Request account statement (PDF only)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.GetAccountStatementRequest" } } }, "description": "Account statement request", "required": true }, "responses": { "200": { "description": "Statement data for PDF generation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wallet/balance/{subscriber_id}": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get current wallet balance for a subscriber (requires PIN verification)", "tags": [ "Wallet" ], "summary": "Get wallet balance", "parameters": [ { "description": "Subscriber ID", "name": "subscriber_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.GetBalanceRequest" } } }, "description": "PIN for verification", "required": true }, "responses": { "200": { "description": "Balance retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request or PIN", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wallet/fund-from-vult": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Top-up SmartPay wallet from VULT wallet account", "tags": [ "Wallet" ], "summary": "Fund SmartPay wallet from VULT", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.FundFromVultRequest" } } }, "description": "Fund from VULT details", "required": true }, "responses": { "200": { "description": "Wallet funded successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wallet/transactions/{subscriber_id}": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Get transaction history for a subscriber (requires PIN verification)", "tags": [ "Wallet" ], "summary": "Get transaction history", "parameters": [ { "description": "Subscriber ID", "name": "subscriber_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.GetTransactionHistoryRequest" } } }, "description": "Transaction history request with PIN", "required": true }, "responses": { "200": { "description": "Transaction history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request or PIN", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wallet/transfer-p2p": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Transfer funds between SmartPay users by card serial", "tags": [ "Wallet" ], "summary": "Peer-to-peer transfer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.TransferP2PRequest" } } }, "description": "P2P transfer details", "required": true }, "responses": { "200": { "description": "Transfer successful", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wallet/transfer-to-vult": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Move funds from SmartPay wallet back to VULT wallet", "tags": [ "Wallet" ], "summary": "Transfer from SmartPay to VULT wallet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.TransferToVultRequest" } } }, "description": "Transfer to VULT details", "required": true }, "responses": { "200": { "description": "Transfer successful", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/webhooks/vult/cashin": { "post": { "description": "HMAC-protected webhook for Vult to credit subscriber wallets", "tags": [ "Webhooks" ], "summary": "Vult cash-in webhook", "parameters": [ { "description": "HMAC-SHA256 signature of request body", "name": "X-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.VultCashInWebhookRequest" } } }, "description": "Cash-in details", "required": true }, "responses": { "200": { "description": "Cash-in successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.VultCashInWebhookResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Invalid signature", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/audit/logs": { "get": { "summary": "Audit Logs", "description": "Query system audit logs", "tags": [ "Admin" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "security": [ { "BearerAuth": [] } ] } }, "/compliance/check": { "post": { "summary": "Check Compliance", "description": "Validate a transaction against compliance rules", "tags": [ "Compliance" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber_id": { "type": "string" }, "amount": { "type": "integer" }, "transaction_type": { "type": "string" }, "recent_transaction_count": { "type": "integer" }, "is_new_location": { "type": "boolean" } }, "required": [ "subscriber_id", "amount", "transaction_type" ] } } }, "required": true }, "security": [ { "BearerAuth": [] } ] } }, "/partner/account-status": { "post": { "summary": "Account Status", "description": "Check if subscriber account exists", "tags": [ "Partner" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "X-API-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Partner-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string" }, "card_serial": { "type": "string" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/partner/cashin": { "post": { "summary": "Cash In", "description": "Credit subscriber wallet via partner", "tags": [ "Partner" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "X-API-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Partner-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string" }, "card_serial": { "type": "string" }, "amount": { "type": "integer" }, "reference": { "type": "string" } }, "required": [ "amount", "reference" ] } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/partner/transaction-history": { "post": { "summary": "Transaction History", "description": "Get partner's transaction history", "tags": [ "Partner" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "X-API-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Partner-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/wallet/transfer": { "post": { "summary": "Internal Transfer", "description": "Transfer funds between accounts internally", "tags": [ "Wallet" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from_account_id": { "type": "string" }, "to_account_id": { "type": "string" }, "amount": { "type": "string" }, "pin": { "type": "string" }, "description": { "type": "string" } }, "required": [ "from_account_id", "to_account_id", "amount", "pin" ] } } }, "required": true }, "security": [ { "BearerAuth": [] } ] } }, "/external/whatsapp": { "post": { "summary": "WhatsApp Webhook", "description": "WhatsApp message webhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "message": { "type": "string" }, "from": { "type": "string" }, "phoneE164": { "type": "string" } }, "required": [ "event", "message", "from", "phoneE164" ] } } }, "required": true } } } }, "servers": [ { "url": "https://olive-gateway-a6ba.onrender.com/api/v1" } ], "components": { "requestBodies": { "handler.RegisterSubscriberRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.RegisterSubscriberRequest" } } }, "description": "Subscriber registration details", "required": true }, "handler.POSLookupCardRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.POSLookupCardRequest" } } }, "description": "Card lookup details", "required": true }, "handler.POSRefundRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.POSRefundRequest" } } }, "description": "Refund details", "required": true }, "handler.POSVerifyCardRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.POSVerifyCardRequest" } } }, "description": "Card verification details", "required": true } }, "securitySchemes": { "ApiKeyAuth": { "description": "API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'", "type": "apiKey", "name": "Authorization", "in": "header" }, "BearerAuth": { "description": "JWT token from admin login for administrative operations. Format: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'", "type": "apiKey", "name": "Authorization", "in": "header" } }, "schemas": { "handler.AgentCashInRequest": { "type": "object", "required": [ "agent_id", "agent_pin", "amount", "subscriber_id" ], "properties": { "agent_id": { "type": "string" }, "agent_pin": { "description": "Agent's PIN for authentication", "type": "string" }, "amount": { "description": "Accepts decimal format like \"50.00\" or \"50\"", "type": "string" }, "card_serial": { "type": "string" }, "subscriber_id": { "type": "string" } } }, "handler.BlockCardRequest": { "type": "object", "required": [ "reason" ], "properties": { "pin": { "type": "string", "example": "1234" }, "reason": { "type": "string", "example": "Lost card" } } }, "handler.BlockSubscriberRequest": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Suspicious activity detected" } } }, "handler.ChangeAgentPINRequest": { "type": "object", "required": [ "new_pin", "old_pin" ], "properties": { "new_pin": { "type": "string" }, "old_pin": { "type": "string" } } }, "handler.ChangeChildCardPINRequest": { "type": "object", "required": [ "card_serial", "new_child_pin", "old_child_pin", "parent_pin", "parent_subscriber_id" ], "properties": { "card_serial": { "type": "string", "example": "OLIV0002" }, "new_child_pin": { "type": "string", "example": "9999" }, "old_child_pin": { "type": "string", "example": "5678" }, "parent_pin": { "type": "string", "example": "1234" }, "parent_subscriber_id": { "type": "string", "example": "parent-uuid" } } }, "handler.ChangePasswordRequest": { "type": "object", "required": [ "new_password", "old_password" ], "properties": { "new_password": { "type": "string" }, "old_password": { "type": "string" } } }, "handler.ChangeSubscriberPINRequest": { "type": "object", "required": [ "new_pin", "old_pin" ], "properties": { "new_pin": { "type": "string" }, "old_pin": { "type": "string" } } }, "handler.CreateAPIKeyRequest": { "type": "object", "required": [ "name", "scopes" ], "properties": { "description": { "type": "string" }, "expires_in_days": { "type": "integer" }, "integration_type": { "description": "whatsapp, smart_pay, vult, agent_app", "type": "string" }, "ip_whitelist": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "rate_limit": { "type": "integer" }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "handler.CreateAccountRulesRequest": { "type": "object", "required": [ "daily_transaction_limit", "kyc_level", "max_balance", "monthly_transaction_limit", "single_transaction_limit", "status" ], "properties": { "daily_transaction_limit": {}, "effective_date": { "type": "string" }, "kyc_level": {}, "max_balance": {}, "monthly_transaction_limit": {}, "single_transaction_limit": {}, "status": { "type": "string", "enum": [ "active", "inactive" ] } } }, "handler.CreateChildCardRequest": { "type": "object", "required": [ "card_serial", "child_holder_name", "child_pin", "child_relationship", "parent_subscriber_id", "pin" ], "properties": { "allocated_amount": { "description": "Amount in SLE (will be converted to cents internally)", "type": "integer", "example": 200000 }, "card_serial": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "OLIV0002" }, "child_holder_name": { "type": "string", "example": "Jane Doe" }, "child_phone_number": { "type": "string", "example": "+23276123456" }, "child_pin": { "type": "string", "example": "5678" }, "child_relationship": { "type": "string", "example": "daughter" }, "daily_limit": { "description": "Amount in SLE (will be converted to cents internally)", "type": "integer", "example": 25000 }, "effective_date": { "type": "string", "example": "2025-10-20" }, "monthly_limit": { "description": "Amount in SLE (will be converted to cents internally)", "type": "integer", "example": 250000 }, "parent_subscriber_id": { "type": "string", "example": "parent-uuid" }, "pin": { "type": "string", "example": "1234" } } }, "handler.CreateComplianceAlertRequest": { "type": "object", "required": [ "alert_type", "details", "subscriber_id" ], "properties": { "alert_type": { "type": "string" }, "details": { "type": "string" }, "rule_id": { "type": "integer" }, "subscriber_id": { "type": "string" } } }, "handler.CreateMonitoringRuleRequest": { "type": "object", "required": [ "action_on_trigger", "notification_recipient", "rule_name", "status" ], "properties": { "action_on_trigger": { "type": "string", "enum": [ "alert", "block", "review" ] }, "amount_threshold": {}, "daily_transaction_limit": {}, "description": { "type": "string" }, "frequency_threshold": {}, "geolocation_check": { "type": "boolean" }, "high_value_alert_threshold": {}, "max_transaction_amount": {}, "min_transaction_amount": {}, "notification_recipient": { "type": "string" }, "rule_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "suspicious_amount_threshold": {} } }, "handler.CreateProcessorRequest": { "type": "object", "required": [ "email", "name", "password", "phone_number" ], "properties": { "email": { "type": "string", "example": "merchant@smartpay.sl" }, "name": { "type": "string", "example": "Smart PAY Merchant" }, "password": { "type": "string", "minLength": 6, "example": "SecurePass123" }, "phone_number": { "type": "string", "example": "0771234567" } } }, "handler.CreateReclaimRequestRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "example": "1000.00" }, "reason": { "type": "string", "example": "Cash out request for weekly settlements" } } }, "handler.CreateUserRequest": { "type": "object", "required": [ "email", "first_name", "last_name", "password", "role" ], "properties": { "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "password": { "type": "string" }, "pep_access_authorized": { "type": "boolean" }, "phone_number": { "type": "string" }, "role": { "type": "string" } } }, "handler.CreateUserResponse": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/handler.UserInfo" }, "user_id": { "type": "string" } } }, "handler.FeeSettingsRequest": { "type": "object", "required": [ "fee_type", "party_type", "transaction_type" ], "properties": { "credit_enabled": { "type": "boolean" }, "debit_enabled": { "type": "boolean" }, "fee_type": { "type": "string", "enum": [ "percentage", "flat" ] }, "fee_value": { "type": "number", "minimum": 0 }, "party_type": { "type": "string" }, "transaction_type": { "type": "string" } } }, "handler.FundAgentRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "description": "Accepts decimal format like \"1289.00\" or \"1289\"", "type": "string" } } }, "handler.FundFromVultRequest": { "type": "object", "required": [ "amount", "pin", "subscriber_id", "transaction_ref", "vult_wallet_id" ], "properties": { "amount": { "description": "Accepts decimal format like \"500.00\" or \"500\"", "type": "string", "example": "500.00" }, "pin": { "type": "string", "example": "1234" }, "subscriber_id": { "type": "string", "example": "subscriber-uuid" }, "transaction_ref": { "type": "string", "example": "VULT-TXN-123" }, "vult_wallet_id": { "type": "string", "example": "vult-wallet-123" } } }, "handler.GetAccountStatementRequest": { "type": "object", "required": [ "end_date", "start_date", "subscriber_id" ], "properties": { "end_date": { "type": "string", "example": "2025-11-08" }, "start_date": { "type": "string", "example": "2025-10-01" }, "subscriber_id": { "type": "string", "example": "subscriber-uuid" } } }, "handler.GetBalanceRequest": { "type": "object", "required": [ "pin" ], "properties": { "pin": { "type": "string", "example": "1234" } } }, "handler.GetTransactionHistoryRequest": { "type": "object", "required": [ "pin" ], "properties": { "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "pin": { "type": "string", "example": "1234" } } }, "handler.LinkCardRequest": { "type": "object", "required": [ "card_serial", "pin", "subscriber_id" ], "properties": { "card_serial": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "OLIV0001" }, "pin": { "type": "string", "example": "1234" }, "subscriber_id": { "type": "string", "example": "subscriber-uuid" } } }, "handler.ListUsersResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/handler.UserInfo" } } } }, "handler.LoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" } } }, "handler.LoginResponse": { "type": "object", "properties": { "expires_at": { "type": "integer" }, "refresh_expires_at": { "type": "integer" }, "refresh_token": { "type": "string" }, "success": { "type": "boolean" }, "token": { "type": "string" }, "user": { "$ref": "#/components/schemas/handler.UserInfo" } } }, "handler.LogoutRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "handler.POSLookupCardRequest": { "type": "object", "required": [ "card_identifier" ], "properties": { "card_identifier": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "CARD0001" } } }, "handler.AppPaymentRequest": { "type": "object", "required": [ "amount", "card_serial", "currency", "merchant_id", "pin", "processor_id", "transaction_ref" ], "properties": { "amount": { "description": "Accepts decimal format like \"150.00\" or \"150\"", "type": "string", "example": "150.00" }, "card_serial": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "CARD0001" }, "currency": { "type": "string", "example": "SLE" }, "merchant_id": { "type": "string", "example": "MERCHANT001" }, "merchant_name": { "description": "Display name for receipts", "type": "string", "example": "ABC Store" }, "metadata": { "type": "object", "additionalProperties": true }, "pin": { "type": "string", "example": "1234" }, "processor_id": { "description": "Processor account that receives the funds", "type": "string", "example": "proc-uuid-123" }, "transaction_ref": { "type": "string", "example": "APP-TXN-123" } } }, "handler.POSPaymentRequest": { "type": "object", "required": [ "amount", "card_serial", "currency", "merchant_id", "pin", "processor_id", "terminal_id", "transaction_ref" ], "properties": { "amount": { "description": "Accepts decimal format like \"150.00\" or \"150\"", "type": "string", "example": "150.00" }, "card_serial": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "CARD0001" }, "currency": { "type": "string", "example": "SLE" }, "merchant_id": { "type": "string", "example": "MERCHANT001" }, "merchant_name": { "description": "Display name for receipts", "type": "string", "example": "ABC Store" }, "metadata": { "type": "object", "additionalProperties": true }, "pin": { "type": "string", "example": "1234" }, "processor_id": { "description": "Processor account that receives the funds", "type": "string", "example": "proc-uuid-123" }, "terminal_id": { "type": "string", "example": "TERM001" }, "transaction_ref": { "type": "string", "example": "POS-TXN-123" } } }, "handler.POSRefundRequest": { "type": "object", "required": [ "amount", "initiated_by", "original_transaction_id", "reason" ], "properties": { "amount": { "description": "Accepts decimal format like \"150.00\" or \"150\"", "type": "string", "example": "150.00" }, "initiated_by": { "type": "string", "example": "admin-user-id" }, "original_transaction_id": { "type": "string", "example": "txn-uuid" }, "reason": { "type": "string", "example": "Customer returned goods" } } }, "handler.POSVerifyCardRequest": { "type": "object", "required": [ "card_serial", "pin" ], "properties": { "card_serial": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "CARD0001" }, "pin": { "type": "string", "example": "1234" } } }, "handler.ProcessorTransferRequest": { "type": "object", "required": [ "account_id", "amount" ], "properties": { "account_id": { "description": "Account ID from accounts table", "type": "string", "example": "acc_xyz123" }, "amount": { "type": "string", "example": "500.00" }, "description": { "type": "string", "example": "Payment for goods" } } }, "handler.RefreshTokenRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "handler.RegisterAgentRequest": { "type": "object", "required": [ "agent_pin", "agent_type", "business_address", "business_name", "contact_person", "district", "kyc_documents", "phone_number" ], "properties": { "agent_pin": { "type": "string", "example": "1234" }, "agent_type": { "description": "Required fields", "type": "string", "enum": [ "super_agent", "sub_agent" ], "example": "super_agent" }, "business_address": { "type": "string", "example": "45 Business Road" }, "business_name": { "type": "string", "example": "ABC Money Transfer" }, "commission_tier": { "description": "Default = 1", "type": "integer", "maximum": 3, "minimum": 1, "example": 1 }, "contact_person": { "type": "string", "example": "Michael Smith" }, "district": { "type": "string", "example": "Western Urban" }, "email": { "description": "Optional fields", "type": "string", "example": "michael@abc.com" }, "kyc_documents": { "type": "array", "items": { "type": "string" }, "example": [ "[\"https://s3.amazonaws.com/doc1.pdf\"]" ] }, "parent_agent_id": { "description": "Conditionally required", "type": "string", "example": "" }, "phone_number": { "type": "string", "example": "0778888888" }, "settlement_mode": { "description": "Default = instant", "type": "string", "enum": [ "instant", "weekly", "monthly" ], "example": "instant" } } }, "handler.RegisterAgentResponse": { "type": "object", "properties": { "agent_id": { "type": "string" }, "email": { "type": "string" }, "instructions": { "type": "string" }, "login_url": { "type": "string" }, "message": { "type": "string" }, "password": { "type": "string" }, "success": { "type": "boolean" } } }, "handler.RegisterSubscriberRequest": { "type": "object", "required": [ "first_name", "last_name", "phone_number", "pin" ], "properties": { "address": { "type": "string", "example": "123 Main St" }, "category": { "type": "string", "example": "retail" }, "certificate_url": { "type": "string", "example": "https://example.com/cert.pdf" }, "district": { "type": "string", "example": "Western Urban" }, "email": { "type": "string", "example": "john@example.com" }, "first_name": { "type": "string", "example": "John" }, "id_back_url": { "type": "string", "example": "https://example.com/id_back.jpg" }, "id_front_url": { "type": "string", "example": "https://example.com/id_front.jpg" }, "kyc_level": { "type": "integer", "example": 1 }, "last_name": { "type": "string", "example": "Doe" }, "max_child_cards": { "type": "integer", "example": 4 }, "national_id": { "type": "string", "example": "NID123456" }, "organisation_name": { "type": "string", "example": "ABC Company Ltd" }, "organisation_type": { "type": "string", "example": "Limited Company" }, "other_names": { "type": "string", "example": "Michael" }, "phone_number": { "type": "string", "example": "0771234567" }, "pin": { "type": "string", "example": "1234" }, "referral_code": { "type": "string", "example": "REF123" }, "registration_id_no": { "type": "string", "example": "RC123456" }, "relationship_manager_id": { "type": "integer", "example": 1 }, "whatsapp_number": { "type": "string", "example": "0771234567" } } }, "handler.RequestPEPAccessRequest": { "type": "object", "required": [ "subscriber_id" ], "properties": { "subscriber_id": { "type": "string" } } }, "handler.ResolveAlertRequest": { "type": "object", "properties": { "is_false_positive": { "type": "boolean" }, "resolution_notes": { "type": "string" }, "resolved_by": { "type": "string" } } }, "handler.ReviewReclaimRequestRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ], "example": "approve" }, "review_notes": { "type": "string", "example": "Approved for check payment" } } }, "handler.SuspendProcessorRequest": { "type": "object", "properties": { "reason": { "type": "string", "example": "Suspected fraudulent activity" } } }, "handler.TransferP2PRequest": { "type": "object", "required": [ "amount", "pin", "recipient_card_serial", "sender_id" ], "properties": { "amount": { "description": "Accepts decimal format like \"100.00\" or \"100\"", "type": "string", "example": "100.00" }, "memo": { "type": "string", "example": "Payment for lunch" }, "pin": { "type": "string", "example": "1234" }, "recipient_card_serial": { "description": "Supports any alphanumeric: CARD0001, 48290173K, etc.", "type": "string", "example": "CARD0002" }, "sender_id": { "type": "string", "example": "subscriber-uuid" } } }, "handler.TransferToSubAgentRequest": { "type": "object", "required": [ "amount", "sub_agent_id" ], "properties": { "amount": { "type": "integer" }, "sub_agent_id": { "type": "string" }, "super_agent_id": { "description": "Optional - auto-detected from logged-in user if not provided", "type": "string" } } }, "handler.TransferToVultRequest": { "type": "object", "required": [ "amount", "pin", "subscriber_id", "vult_wallet_id" ], "properties": { "amount": { "description": "Accepts decimal format like \"250.00\" or \"250\"", "type": "string", "example": "250.00" }, "pin": { "type": "string", "example": "1234" }, "subscriber_id": { "type": "string", "example": "subscriber-uuid" }, "vult_wallet_id": { "type": "string", "example": "vult-wallet-123" } } }, "handler.UnblockCardRequest": { "type": "object", "properties": { "pin": { "type": "string", "example": "1234" } } }, "handler.UpdateAccountRulesRequest": { "type": "object", "required": [ "daily_transaction_limit", "max_balance", "monthly_transaction_limit", "single_transaction_limit", "status" ], "properties": { "daily_transaction_limit": {}, "effective_date": { "type": "string" }, "max_balance": {}, "monthly_transaction_limit": {}, "single_transaction_limit": {}, "status": { "type": "string", "enum": [ "active", "inactive" ] } } }, "handler.UpdateComplianceAlertRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "investigating", "resolved", "false_positive" ] } } }, "handler.UpdateMonitoringRuleRequest": { "type": "object", "properties": { "action_on_trigger": { "type": "string", "enum": [ "alert", "block", "review" ] }, "amount_threshold": {}, "daily_transaction_limit": {}, "description": {}, "frequency_threshold": {}, "geolocation_check": { "type": "boolean" }, "high_value_alert_threshold": {}, "max_transaction_amount": {}, "min_transaction_amount": {}, "notification_recipient": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "suspicious_amount_threshold": {} } }, "handler.UpdateProcessorRequest": { "type": "object", "properties": { "email": { "type": "string", "example": "merchant@smartpay.sl" }, "name": { "type": "string", "example": "Smart PAY Merchant" }, "phone_number": { "type": "string", "example": "0771234567" } } }, "handler.UpdateSubscriberRequest": { "type": "object", "properties": { "address": { "type": "string", "example": "456 New St" }, "category": { "type": "string", "example": "vip" }, "district": { "type": "string", "example": "Western Rural" }, "email": { "type": "string", "example": "newemail@example.com" }, "id_back_url": { "type": "string", "example": "s3://bucket/kyc/subscriber-id/id-back/file.jpg" }, "id_front_url": { "type": "string", "example": "s3://bucket/kyc/subscriber-id/id-front/file.jpg" }, "kyc_level": { "type": "integer", "example": 2 }, "max_child_cards": { "type": "integer", "example": 100 }, "national_id": { "type": "string", "example": "ID123456789" }, "relationship_manager_id": { "type": "integer", "example": 1 }, "vult_wallet_id": { "type": "string", "example": "VULT123456" } } }, "handler.UpdateUserStatusRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "handler.UserInfo": { "type": "object", "properties": { "account_id": { "description": "For processors", "type": "string" }, "agent_id": { "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "last_login_at": { "type": "string" }, "last_name": { "type": "string" }, "name": { "description": "For processors", "type": "string" }, "pep_access_authorized": { "type": "boolean" }, "phone_number": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "user_type": { "description": "\"admin\" or \"processor\"", "type": "string" } } }, "handler.VerifyPEPAccessRequest": { "type": "object", "required": [ "otp_code", "subscriber_id" ], "properties": { "otp_code": { "type": "string" }, "subscriber_id": { "type": "string" } } }, "handler.VerifyPINRequest": { "type": "object", "required": [ "pin" ], "properties": { "pin": { "type": "string", "example": "1234" } } }, "handler.VultCashInWebhookRequest": { "type": "object", "required": [ "amount", "card_serial" ], "properties": { "amount": { "type": "integer" }, "card_serial": { "type": "string" }, "phone_number": { "type": "string" } } }, "handler.VultCashInWebhookResponse": { "type": "object", "properties": { "message": { "type": "string" }, "new_balance": { "type": "integer" }, "success": { "type": "boolean" }, "transaction_id": { "type": "string" } } }, "handler.VerifyAccountExistsRequest": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string", "example": "acc_12345678" } } } } } }