{ "openapi": "3.1.0", "info": { "title": "Spotflow", "description": "", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "description": "Production server", "url": "https://api.spotflow.co/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/plans/{plan-id}/subscriptions": { "get": { "description": "Retrieve details of all subscriptions associated with a customer's plan ID.", "operationId": "SubscriptionsbyPlan", "parameters": [ { "name": "plan-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionsPlanResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/subscriptions": { "get": { "description": "Retrieve details of all subscriptions associated with a customer's plan ID or customer's email.", "operationId": "listSubscriptions", "parameters": [ { "name": "customerId", "in": "query", "required": false, "description": "The unique identifier of the customer Id whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } }, { "name": "email", "in": "query", "required": false, "description": "The unique identifier of the email whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ListSubscriptionsResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/subscriptions/{subscription-id}": { "get": { "description": "Retrieve details of all subscriptions associated with a subscription ID.", "operationId": "SubscriptionDetails", "parameters": [ { "name": "subscription-id", "in": "path", "required": true, "description": "The unique identifier of the subscription whose details are to be retrieved.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/subscriptions/{subscription-id}/activate": { "post": { "description": "Activate a subscription with the plan Id.", "operationId": "ActivateSubscription", "parameters": [ { "name": "subscription-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/subscriptions/{subscription-id}/cancel": { "post": { "description": "Cancel a subscription with the plan Id.", "operationId": "CancelSubscription", "parameters": [ { "name": "subscription-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/subscriptions/{subscription-id}/payment-method": { "get": { "operationId": "getSubscriptionPaymentMethod", "summary": "Get payment method associated with a subscription", "description": "Returns the payment method currently linked to the subscription. The response shape depends on whether the payment method is a card or mobile money (MOMO).", "parameters": [ { "name": "subscription-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment method retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "examples": { "card": { "summary": "Card payment method", "value": { "type": "card", "firstSix": "506124", "lastFour": "5456", "cardType": "verve", "accountHolderName": "Jane Doe", "expirationMonth": 11, "expirationYear": 2026 } }, "momo": { "summary": "Mobile money payment method", "value": { "type": "momo", "operator": "MTN", "accountHolderName": "Jane Doe", "phoneNumber": "+2348012345678" } } } } } }, "404": { "description": "Subscription not found, or no payment method is linked to it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "updateSubscriptionPaymentMethod", "summary": "Update payment method associated with a subscription", "description": "Replaces the payment method linked to the subscription. Send either an encrypted card payload or a mobile money payload, depending on the payment type being set.", "tags": ["Payment Method"], "parameters": [ { "name": "subscription-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodUpdateRequest" }, "examples": { "card": { "summary": "Update to a card payment method", "value": { "encryptedCard": "string" } }, "momo": { "summary": "Update to a mobile money payment method", "value": { "mobileMoney": { "otp": "string", "code": "string", "name": "string", "phoneNumber": "string" } } } } } } }, "responses": { "200": { "description": "Payment method updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "examples": { "card": { "summary": "Card payment method", "value": { "type": "card", "firstSix": "506124", "lastFour": "5456", "cardType": "verve", "accountHolderName": "Jane Doe", "expirationMonth": 11, "expirationYear": 2026 } }, "momo": { "summary": "Mobile money payment method", "value": { "type": "momo", "operator": "MTN", "accountHolderName": "Jane Doe", "phoneNumber": "+2348012345678" } } } } } }, "400": { "description": "Invalid request body (e.g. wrong OTP/code, malformed encrypted card)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/plans": { "get": { "description": "Retrieve details of all subscription plans available on your integration.", "operationId": "SubsciptionsPlan", "parameters": [ { "name": "title", "in": "query", "required": false, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string" } }, { "name": "internal-reference", "in": "query", "required": false, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlansResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } }, "post": { "description": "Create a subscription plan under your integration.", "operationId": "singleSubsciptionsPlan", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Standard Monthly Plan", "description": "Name or title of the plan" }, "cycleCount": { "type": "integer", "example": "3", "description": "Maximum billing cycles before the plan completes" }, "retrial": { "type": "integer", "example": "3", "description": "***Note that retrial only applies to card subscriptions, not mobile money.*** Retry count for failed card payments." }, "endDate": { "type": "string", "format": "date", "example": "2026-10-29", "description": "The date all subscription cycles end" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL" ], "description": "Billing frequency for the plan" }, "internalReference": { "type": "string", "description": "Internal reference code for the plan", "example": "PLAN-STD-001" }, "pricingOptions": { "type": "array", "description": "Pricing options for the plan", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount to be charged per billing cycle. ***If you plan to use this subscription plan for mobile money payments, make sure the currency matches a supported mobile money region. See [Mobile Money Subscriptions](/features/mobile-money-subscriptions) for supported currencies and providers.***" }, "currency": { "type": "string", "description": "Currency code for the plan (e.g. USD, NGN). ***If you plan to use this subscription plan for mobile money payments, make sure the currency matches a supported mobile money region. See [Mobile Money Subscriptions](/features/mobile-money-subscriptions) for supported currencies and providers.***", "example": "NGN" } }, "required": ["amount", "currency"] } }, "trial": { "type": "object", "properties": { "periodInDays": { "type": "number", "default": 0 }, "pricingList": { "type": "array", "description": "Pricing options for the trial period", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount to be charged during the trial period" }, "currency": { "type": "string", "description": "Currency code for the trial period (e.g. USD, NGN)", "example": "NGN" } }, "required": ["amount", "currency"] } } } } } } } } }, "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlanDetailsResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/plans/{plan-id}/cancel": { "post": { "description": "Cancel a subscription with the plan Id.", "operationId": "CancelSubscriptionPlan", "parameters": [ { "name": "plan-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/bulk-plans": { "post": { "description": "Create multiple subscription plans under your integration.", "operationId": "CreateBulkSubscriptionPlans", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file containing bulk subscription data. Must be a .csv file." }, "skipErrors": { "type": "boolean", "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "enum": [true, false] } }, "required": ["file"] }, "encoding": { "file": { "contentType": "text/csv" } } } } }, "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/plans/{plan-id}/activate": { "post": { "description": "Activate a subscription with the plan Id.", "operationId": "ActivateSubscriptionPlan", "parameters": [ { "name": "plan-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose subscriptions are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of subscription objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/plans/{plan-id}": { "get": { "description": "Retrieve details of a single subscription plan available on your integration.", "operationId": "GetSubscriptionPlan", "parameters": [ { "name": "plan-id", "in": "path", "required": true, "description": "The unique identifier of the plan whose details are to be retrieved.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successfully retrieved subscription plan details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Bad Request - Invalid plan ID provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } }, "post": { "description": "Create or update a subscription plan under your integration using the provided plan ID.", "operationId": "CreateOrUpdateSubscriptionPlan", "parameters": [ { "name": "plan-id", "in": "path", "required": true, "description": "Unique identifier for the plan to create or update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Standard Monthly Plan", "description": "Name or title of the plan" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", " QUARTERLY", "BIANNUAL", "ANNUAL" ], "description": "Billing frequency for the plan" }, "internalReference": { "type": "string", "description": "Internal reference code for the plan", "example": "PLAN-STD-001" }, "pricingOptions": { "type": "array", "description": "Pricing options for the plan", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount to be charged per billing cycle" }, "currency": { "type": "string", "description": "Currency code for the plan (e.g. USD, NGN)", "example": "NGN" } }, "required": ["amount", "currency"] } } } } } } }, "responses": { "201": { "description": "Subscription plan successfully created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanDetailsResponse" } } } }, "400": { "description": "Bad Request - Invalid request body or parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden - Insufficient permissions to create or modify the plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError403" } } } } } } }, "/accounts": { "get": { "description": "This retrieves and lists all the static virtual accounts you've created. This is both for your main account and static virtual accounts (sub-accounts).", "operationId": "ListStaticVirtualAccounts", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "accountTag", "in": "query", "required": false, "description": "This can either be static virtual accounts, or main-account.", "schema": { "type": "string", "enum": ["sub-account", "main-account"] } }, { "name": "currency", "in": "query", "required": false, "description": "Choose the currency you want for your static virtual account. According, to our currently supported currencies, this is in NGN or GHS.", "schema": { "type": "string", "enum": ["NGN", "GHS"] } }, { "name": "mode", "in": "query", "required": false, "description": "This can either be test or live mode.", "schema": { "type": "string", "enum": ["test", "live"] } }, { "name": "accountNumber", "in": "query", "required": false, "description": "This filters by the account number created for the static virtual accounts.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time", "example": "2025-02-28" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time", "example": "2025-03-03" } } ], "responses": { "200": { "description": "A JSON array of static virtual accounts objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StaticVirtualAccountsDetailsResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } }, "post": { "description": "Static virtual accounts are created only through the API and serve a unique purpose to act as a pocket of money where funds can sit in. Importantly, static virtual accounts do not require BVNs upon creation.", "operationId": "StaticVirtualAccountsCreation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN", "description": "According, to our currently supported currencies, this is in NGN and GHS." }, "accountName": { "type": "string", "example": "Quantum Technologies", "description": "Your desired name for your static virtual account." } } } } } }, "responses": { "200": { "description": "A JSON array of static virtual accounts objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStaticVirtualAccountsDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/accounts/{id}/deactivate": { "delete": { "description": "Deactivates a static virtual account, preventing it from receiving any further payments. Once deactivated, the account status is set to inactive and any incoming transfers to it will be rejected or returned. This action cannot be undone through this endpoint — a new static virtual account must be created if collections need to resume.", "operationId": "DeactivateStaticVirtualAccount", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the static virtual account to deactivate.", "schema": { "type": "string", "format": "uuid", "example": "65122475-eef0-47e6-8c47-ac461e0a080d" } } ], "responses": { "200": { "description": "The static virtual account has been deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateStaticVirtualAccountResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Bad Request - The account could not be deactivated (e.g. already inactive).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "404": { "description": "Not Found - No static virtual account found for the given ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } } } } }, "/balances": { "get": { "description": "Retrieves paginated balances for main accounts with optional currency, mode, and date filters.", "operationId": "ListBalances", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "currency", "in": "query", "required": false, "description": "Choose the currency you want for your sub account. According, to our currently supported currencies, this is in NGN or GHS.", "schema": { "type": "string", "enum": ["NGN", "GHS"] } }, { "name": "mode", "in": "query", "required": false, "description": "This can either be test or live mode.", "schema": { "type": "string", "enum": ["test", "live"] } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A JSON array of balances objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalanceListResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/balances/accounts/{accountNumber}/sub-balances": { "get": { "description": "Retrieves account balance details for all direct spotflow static virtual of the specified main account in both NGN and GHS.", "operationId": "ListSpotflowStaticVirtualAccountsBalances", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of balances objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalanceListResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/balances/accounts/{accountNumber}/balance": { "get": { "description": "Get account balance details for a specific spotflow-static virtual accounts before and after top-up in both NGN and GHS currency.", "operationId": "AccountBalance", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of balances objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountBalanceListResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/accounts/{id}": { "get": { "description": "Get details of your created spotflow static virtual account by its ID. You can get this in either NGN or GHS.", "operationId": "AccountID", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of account details objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticVirtualAccountsDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/virtual-accounts/temporary": { "post": { "description": "This endpoint is used to create a dynamic virtual account to receive payments.", "operationId": "DynamicAccountCreation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN", "description": "According, to our currently supported currencies, this is in NGN and GHS." }, "accountName": { "type": "string", "example": "Quantum Technologies", "description": "Your desired naming for your account." }, "amount": { "type": "number", "example": 5.00, "description": "The amount in the major unit of the currency, decimals allowed. For example 5.00 with currency GHS means five Ghana cedis, not five pesewas." }, "expiresIn": { "type": "number", "format": "int32", "description": "This is optional to add. By default, the time it takes for a virtual account to expire is 30 mins. However, you can customize the time to lesser as you desire." } } } } } }, "responses": { "200": { "description": "A JSON array of dynamic virtual account objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/virtual-accounts/{id}": { "get": { "description": "Get details of your created virtual account by its ID.", "operationId": "DynamicAccountID", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "This is the unique ID generated upon creation of your dynamic virtual account in either NGN or GHS.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of dynamic details objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/virtual-accounts": { "get": { "description": "This retrieves and lists all the active dynamic virtual accounts you created.", "operationId": "ListDynamicAccount", "parameters": [ { "name": "accountId", "in": "query", "required": true, "description": "This filters by the account ID created for the virtual accounts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of dynamic virtual account details objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DynamicDetailsResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/bulk": { "post": { "description": "You can use this endpoint to perform bulk bank account transfer to multiple bank accounts.", "operationId": "CreateBulkTransfer", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file containing bulk transfer data. Must be a .csv file." }, "category": { "type": "string", "description": "Specify a unique category of your choice for your company to track a transaction for later reconciliation." }, "currency": { "type": "string", "description": "Select the currency for the transfer. This is in our supported currency which is currently only NGN and GHS.", "enum": ["NGN", "GHS"] }, "narration": { "type": "string", "description": "This is optional information for you to give details about the reason for the transfer" } }, "required": ["file", "category", "currency", "narration"] }, "encoding": { "file": { "contentType": "text/csv" } } } } }, "responses": { "201": { "description": "Bulk transfer created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Bad Request - Invalid CSV or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } }, "get": { "description": "Get details of all bulk transfer files you have uploaded.", "operationId": "listBulkTransfers", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "query", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of bulk disbursements objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TransferDetailsResponse" } }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/bulk/{id}": { "get": { "description": "Get details of an uploaded bulk disbursement by its id.", "operationId": "BulkTransferID", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "This is the specific id used to get the individual transfer details in the uploaded bulk disbursement file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of bulk disbursement details objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/bulk/categories": { "get": { "description": "Get details of an uploaded bulk disbursement by the categories you created with.", "operationId": "BulkTransferCategories", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of bulk disbursement details objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "example": "string" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/bulk/{id}/transfers": { "get": { "description": "Get details of all bulk transfer files you have uploaded.", "operationId": "listBulkTransfersByID", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "This is the specific id used to get the individual transfer details in the uploaded bulk disbursement file.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "query", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of bulk disbursements objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TransferDetailsResponse" } }, "pageNumber": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 10 }, "totalElements": { "type": "integer", "example": 100 }, "totalPages": { "type": "integer", "example": 10 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/bulk/validate": { "post": { "description": "Use this endpoint to confirm your bulk disbursement CSV file has all the necessary details needed and won't fail when uploaded for the bulk transfer transaction.", "operationId": "ValidateBulkTransfer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Upload the file content and must in CSV format.", "format": "binary" } }, "required": ["file"] }, "example": { "file": "string" } } } }, "responses": { "201": { "description": "A JSON array of create bulk disbursement objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "failedRequests": { "type": "array", "default": [] }, "totalRequests": { "type": "number", "format": "int32" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers": { "post": { "description": "You can use this endpoint to perform bank account transfer from your main account", "operationId": "CreateSingleDisbursement", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid" }, "amount": { "type": "integer", "format": "float" }, "currency": { "type": "string" }, "destination": { "type": "object", "properties": { "accountNumber": { "type": "string" }, "accountName": { "type": "string" }, "bankCode": { "type": "string" } }, "branchCode": { "type": "string" } }, "narration": { "type": "string" } }, "required": [ "reference", "destination", "amount", "currency" ] } } } }, "responses": { "201": { "description": "A JSON array of create single disbursement objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/banks/{currency}": { "get": { "description": "Get details of all bulk transfer files you have uploaded.", "operationId": "TransferBank", "parameters": [ { "name": "currency", "in": "path", "required": true, "description": "Currently we support NGN or GHS", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of bank list objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "bankCode": { "type": "string", "example": "PB-56234" }, "bankName": { "type": "string", "example": "Nombank" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/resolve-account": { "get": { "description": "Get details of all bulk transfer files you have uploaded.", "operationId": "ResolveAccount", "parameters": [ { "name": "accountNumber", "in": "query", "required": true, "description": "This is the account number you want to get/validate.", "schema": { "type": "string" } }, { "name": "bankCode", "in": "query", "required": true, "description": "This is the bank code of the account number on our system.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": true, "description": "Select the currency for the payment charge. This is in our supported currency which is currently only NGN. Please note that only NGN accounts works with resolve bank accounts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of resolve transfers objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountName": { "type": "string", "example": "string" }, "accountNumber": { "type": "string", "example": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/reference/{reference}": { "get": { "description": "Get details of a particular transfer by its reference id.", "operationId": "TransactionReference", "parameters": [ { "name": "reference", "in": "path", "required": true, "description": "This is the reference id of the transfer that you made on your account using what's in the 'reference' and not 'spotflowReference.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferDetailsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/transfers/banks/{bank-code}/branches": { "get": { "description": "Retrieves a list of supported branches for a for transfers in the specified mode and selected currency", "operationId": "BranchesBankCode", "parameters": [ { "name": "bankCode", "in": "query", "required": true, "description": "This is the bank code of the account number on our system.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of bank branches objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bankCode": { "type": "string", "example": "string" }, "bankName": { "type": "string", "example": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionError401" } } } }, "400": { "description": "Not Found - No subscriptions found for the given plan ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/payments": { "get": { "description": "Get details of all payments collection done via your keys.", "operationId": "GetPaymentById", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default is 0).", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Number of items per page for pagination (default is 10).", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "reference", "in": "query", "required": false, "description": "The unique identifier of the payment.", "schema": { "type": "number", "format": "int32" } }, { "name": "query", "in": "query", "required": false, "description": "Use this to get payments by any internal reference you set when creating/initializing payments", "schema": { "type": "string", "example": "ref-db15ac7a-78c4-480d-afc4-2be8b2325399" } }, { "name": "status", "in": "query", "required": false, "description": "", "schema": { "type": "string", "description": "This can either be successful, failed or pending." } }, { "name": "channel", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": ["card", "bank_transfer", "mobile_money", "eft"], "description": "This can either be card, bank transfer, mobile_money, or eft for local currency payments." } }, { "name": "provider", "in": "query", "required": false, "description": "", "schema": { "type": "string", "description": "These are available payment providers on Spotflow." } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON array of payment objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } }, "pageNumber": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 10 }, "totalElements": { "type": "integer", "example": 100 }, "totalPages": { "type": "integer", "example": 10 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/payments/initialize": { "post": { "description": "This is Spotflow's Redirect Checkout. Initiate a payment request to generate a unique payment reference, payment code and checkout URL for your customers", "operationId": "IntializePayment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "example": "string", "description": "Specify a unique reference ID generated by your company to identify each customer." }, "amount": { "type": "number", "example": 5.00, "description": "The amount in the major unit of the currency, decimals allowed. For example 5.00 with currency GHS means five Ghana cedis, not five pesewas. This is not needed if you use a planId in your request." }, "expiresIn": { "type": "number", "example": 10, "description": "The default maximum expiry time is 30 mins. However, you can set yours to the time you desire. The least time you can set is 5 mins." }, "planId": { "type": "string", "example": "95eb086a-b11a-44b2-8422-a1955ca0fd9a", "description": "***Note that including this turns the payment into a subscription.** Omitting it makes it a one-time charge as it is used when paying for a subscription plan." }, "currency": { "type": "string", "enum": ["USD", "NGN", "GHS", "KES", "ZAR", "TZS", "XOF", "XAF"], "example": "USD", "description": "Select the currency for the payment charge. Can either be in USD or in the local currency of your collection region. If you put in USD, you have to put in the local currency of the region in the local currency request field." }, "countryCode": { "type": "string", "example": "CI", "description": "***Note that, this is only needed to be passed or used for XOF and XAF currency payments***. Country code of XOF countries like Cote D'voire with code CI, or XAF countries like Cameroon with code CM.", "if": { "properties": { "currency": { "enum": ["XOF", "XAF"] } } }, "then": { "required": ["countryCode"] } }, "localCurrency": { "type": "string", "enum": ["NGN", "GHS", "KES", "ZAR", "TZS"], "example": "NGN", "description": "This is the local currency of your region. Used only when currency is set to USD. According to the local region, this can either be in NGN, GHS, ZAR, TZS, KSH etc.", "if": { "properties": { "currency": { "const": "USD" } } }, "then": { "required": ["localCurrency"] } }, "callBackUrl": { "type": "string", "format": "url", "example": "https://yourapp.com/callback", "description": "This is the URL you want your users to be redirected to after making payments. You can also set this permanently on your Spotflow dashboard." }, "metadata": { "type": "object", "properties": { "productName": { "type": "string", "example": "Algo.ai" } }, "description": "This is information pertaining to additional details about your product or service. Under metadata, you have productName” as a field — This is necessary for you to add as it indicates the name of your product and helps to specify to your user what your product is called. You can add any other additional field as you deem fit." }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" } }, "required": ["email"], "description": "The customer’s email address" } }, "required": ["reference", "currency", "customer"] } } } }, "responses": { "200": { "description": "A JSON array of initialize payment objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid" }, "checkoutUrl": { "type": "string", "format": "url", "example": "https://checkout.spotflow.co/paymentCode" }, "paymentCode": { "type": "string", "example": "PAY123456789" }, "status": { "type": "string", "example": "pending" }, "mode": { "type": "string", "example": "TEST" }, "expiryTime": { "type": "string", "example": "2025-11-03T10:16:26.948278058" }, "callBackUrl": { "type": "string", "format": "url", "example": "https://yourapp.com/callback" }, "metadata": { "type": "object", "properties": { "productName": { "type": "string", "example": "Algo.ai" } }, "description": "This is information pertaining to additional details about your product or service." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/payments/authorize": { "post": { "description": "This authorizes a payment by pre-approving the transaction before final validation. Authorization required could be PIN, OTP, 3DS, AVS, etc. ", "operationId": "AuthorizePayment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "example": "string", "description": "Specify a unique reference ID generated by your company to identify each customer." }, "authorization": { "type": "object", "properties": { "otp": { "type": "string", "example": "0xxx" }, "pin": { "type": "string", "example": "01xx" } }, "description": "A confidential or secret code required to authenticate and verify identity for card transactions." } }, "required": ["reference", "authorization"] } } } }, "responses": { "200": { "description": "A JSON array of authorize payment objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "reference": { "type": "string", "example": "REF123456789" }, "spotflowReference": { "type": "string", "example": "SPF-REF-001" }, "amount": { "type": "number", "example": 100.0 }, "currency": { "type": "string", "example": "USD" }, "localAmount": { "type": "number", "example": 156000.0 }, "totalFees": { "type": "number", "example": 500.0 }, "localCurrency": { "type": "string", "example": "NGN" }, "channel": { "type": "string", "example": "card" }, "status": { "type": "string", "example": "SUCCESS" }, "providerMessage": { "type": "string", "example": "Please enter your OTP sent to your phone" }, "rate": { "type": "number", "example": 1560.0 }, "region": { "type": "string", "example": "Nigeria" }, "authorization": { "type": "object", "properties": { "mode": { "type": "string", "example": "otp" } } }, "card": { "type": "object", "properties": { "type": { "type": "string", "example": "VISA" }, "firstSix": { "type": "string", "example": "412345" }, "lastFour": { "type": "string", "example": "6789" } } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-10-17T15:21:11.287Z" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "orderId": "ORD-000123", "note": "First payment" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/payments/{payment-id}": { "get": { "description": "Get details of a specific payment by its ID", "operationId": "GetPaymentById", "parameters": [ { "name": "payment-id", "in": "path", "required": true, "description": "The unique identifier of the payment.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of payment objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "reference": { "type": "string", "example": "REF123456789" }, "spotflowReference": { "type": "string", "example": "SPF-REF-001" }, "amount": { "type": "number", "example": 100.0 }, "currency": { "type": "string", "example": "USD" }, "localAmount": { "type": "number", "example": 156000.0 }, "totalFees": { "type": "number", "example": 500.0 }, "localCurrency": { "type": "string", "example": "NGN" }, "channel": { "type": "string", "example": "card" }, "status": { "type": "string", "example": "SUCCESS" }, "rate": { "type": "number", "example": 1560.0 }, "region": { "type": "string", "example": "Nigeria" }, "authorization": { "type": "object", "properties": { "mode": { "type": "string", "example": "otp" } } }, "card": { "type": "object", "properties": { "type": { "type": "string", "example": "VISA" }, "firstSix": { "type": "string", "example": "412345" }, "lastFour": { "type": "string", "example": "6789" } } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-10-17T15:21:11.287Z" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "orderId": "ORD-000123", "note": "First payment" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } }, "/merchant/tax-status": { "get": { "summary": "Check Tax Activation Status", "description": "According to your request made, checks if your merchant account has been authorized by Spotflow to collect regional checkout taxes.", "responses": { "200": { "description": "Returns true if tax features are enabled for your account.", "content": { "application/json": { "schema": { "type": "boolean", "example": true } } } } } } }, "/tax-configurations": { "get": { "summary": "Get Tax Settings by Country/Region", "description": "Returns a list of all custom tax rules and rates configured for a specific country.", "parameters": [ { "name": "regionId", "in": "query", "required": true, "description": "The unique ID number for the country (e.g., `1` for Nigeria).", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "A list of configured tax settings.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxConfiguration" } } } } } } }, "post": { "summary": "Create a New Tax Setting", "description": "Adds a new tax rule to an approved country. You can set this up as a fixed flat fee or a percentage-based charge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["taxName", "taxType", "rate", "currency", "regionId"], "properties": { "taxName": { "type": "string", "example": "Stamp duty" }, "taxType": { "type": "string", "enum": ["flat", "percentage"], "example": "flat" }, "rate": { "type": "number", "example": 100.00 }, "currency": { "type": "string", "example": "NGN" }, "regionId": { "type": "integer", "example": 1 }, "capAmount": { "type": "number", "example": 2000 }, "thresholdAmount": { "type": "number", "example": 0 } } } } } }, "responses": { "201": { "description": "Tax setting created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxConfiguration" } } } } } } }, "/tax-configurations/{id}": { "put": { "summary": "Edit Tax Details", "description": "Updates the display name, amount, or maximum cap limit for an existing tax rule.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique ID of the specific tax rule you want to update.", "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxName": { "type": "string", "example": "Updated Service Charge Name" }, "rate": { "type": "number", "example": 50.00 }, "capAmount": { "type": "number", "example": 2000 } } } } } }, "responses": { "200": { "description": "Tax details updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxConfiguration" } } } } } } }, "/tax-configurations/{id}/status": { "put": { "summary": "Start or Stop Charging a Tax", "description": "Changes the status of a tax rule. Set to `active` to start charging your customers during checkout, or `inactive` to pause it.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique ID of the tax rule you want to activate or pause.", "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["active", "inactive"], "example": "inactive" } } } } } }, "responses": { "200": { "description": "Tax status updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxConfiguration" } } } } } } }, "/payments/verify": { "get": { "description": "Confirm the status of a payment", "operationId": "VerifyPayment", "parameters": [ { "name": "reference", "in": "query", "required": true, "description": "The unique identifier of the payment.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A JSON array of payment objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "400": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "ListSubscriptionsResponse": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the subscription." }, "customerId": { "type": "string", "format": "uuid", "description": "The unique identifier for the customer associated with the subscription." }, "planId": { "type": "string", "format": "uuid", "description": "The unique identifier for the plan associated with the subscription." }, "status": { "type": "string", "enum": ["active", "cancelled"], "description": "The current status of the subscription (e.g., active, canceled, past_due)." }, "startDate": { "type": "string", "format": "date-time", "description": "The date and time when the subscription started." }, "nextPaymentDate": { "type": "string", "format": "date-time", "description": "The date and time when the subscription started." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was created." }, "customer": { "type": "object", "description": "Details of the customer associated with the subscription.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the customer." }, "email": { "type": "string", "format": "email", "description": "The email address of the customer." }, "name": { "type": "string", "example": "John Doe", "description": "The full name of the customer." } }, "required": ["id", "email", "name"] }, "metadata": { "type": "object", "description": "A set of key-value pairs that can be attached to the subscription for storing additional information.", "properties": { "additionalProp1": { "type": "string", "example": "string" }, "additionalProp2": { "type": "string", "example": "string" }, "additionalProp3": { "type": "string", "example": "string" } } }, "currency": { "type": "string", "description": "The currency in which the subscription is billed,", "example": "NGN" }, "regionName": { "type": "string", "description": "The geographical region associated with the subscription.", "example": "Nigeria" }, "amount": { "type": "number", "format": "float", "description": "The amount to be charged for the subscription.", "example": 5000.0 } } } }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "TaxConfiguration": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "taxName": { "type": "string", "example": "VAT" }, "taxType": { "type": "string", "enum": ["flat", "percentage"], "example": "percentage" }, "rate": { "type": "number", "format": "float", "example": 7.50 }, "currency": { "type": "string", "example": "NGN" }, "capAmount": { "type": "number", "format": "float", "example": 2000.00 }, "thresholdAmount": { "type": "number", "format": "float", "example": 0.00 }, "regionId": { "type": "integer", "example": 1 }, "regionName": { "type": "string", "example": "Nigeria" }, "merchantName": { "type": "string", "example": "DEE LLC" }, "status": { "type": "string", "enum": ["active", "inactive"], "example": "active" }, "template": { "type": "boolean", "example": false }, "templateId": { "type": "integer", "example": 1 } } }, "SubscriptionsPlanResponse": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the subscription." }, "customerId": { "type": "string", "format": "uuid", "description": "The unique identifier for the customer associated with the subscription." }, "planId": { "type": "string", "format": "uuid", "description": "The unique identifier for the plan associated with the subscription." }, "status": { "type": "string", "enum": ["active", "inactive"], "description": "The current status of the subscription (e.g., active, canceled, inacitve)." }, "startDate": { "type": "string", "format": "date-time", "description": "The date and time when the subscription started." }, "nextPaymentDate": { "type": "string", "format": "date-time", "description": "The date and time when the subscription started." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was created." }, "customer": { "type": "object", "description": "Details of the customer associated with the subscription.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the customer." }, "email": { "type": "string", "format": "email", "description": "The email address of the customer." }, "name": { "type": "string", "example": "John Doe", "description": "The full name of the customer." } }, "required": ["id", "email", "name"] }, "metadata": { "type": "object", "description": "A set of key-value pairs that can be attached to the subscription for storing additional information.", "properties": { "additionalProp1": { "type": "string", "example": "string" }, "additionalProp2": { "type": "string", "example": "string" }, "additionalProp3": { "type": "string", "example": "string" } } }, "currency": { "type": "string", "description": "The currency in which the subscription is billed,", "example": "NGN" }, "regionName": { "type": "string", "description": "The geographical region associated with the subscription.", "example": "Nigeria" }, "amount": { "type": "number", "format": "float", "description": "The amount to be charged for the subscription.", "example": 5000.0 } } } }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "SubscriptionDetails": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the subscription" }, "customerId": { "type": "string", "format": "uuid", "description": "Identifier of the customer associated with this subscription" }, "planId": { "type": "string", "format": "uuid", "description": "Identifier of the subscribed plan" }, "status": { "type": "string", "enum": ["active", "inactive"], "description": "Current status of the subscription (e.g. active, inactive)" }, "startDate": { "type": "string", "format": "date-time", "description": "Date when the subscription started" }, "nextPaymentDate": { "type": "string", "format": "date-time", "description": "Next scheduled payment date" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the subscription was created" }, "customer": { "type": "object", "description": "Details about the customer", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer" }, "name": { "type": "string", "example": "John Doe", "description": "Full name of the customer" }, "email": { "type": "string", "format": "email", "description": "Email address of the customer" }, "phoneNumber": { "type": "string", "example": "+234 80 7855 4801", "description": "Phone number of the customer" } }, "required": ["id", "name", "email"] }, "metadata": { "type": "object", "description": "Additional custom data associated with the subscription", "properties": { "additionalProp1": { "type": "string", "example": "string" }, "additionalProp2": { "type": "string", "example": "string" }, "additionalProp3": { "type": "string", "example": "string" } } }, "currency": { "type": "string", "description": "The currency in which the subscription is billed,", "example": "NGN" }, "regionName": { "type": "string", "description": "The geographical region associated with the subscription.", "example": "Nigeria" }, "amount": { "type": "number", "format": "float", "description": "The amount to be charged for the subscription.", "example": 5000.0 } }, "required": [ "id", "customerId", "planId", "status", "startDate", "currency", "amount" ] }, "SubscriptionActivateResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the plan" }, "title": { "type": "string", "example": "string", "description": "Name or title of the plan" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", " QUARTERLY", "BIANNUAL", "ANNUAL" ], "description": "Billing frequency for the plan" }, "internalReference": { "type": "string", "description": "Internal reference code for the plan", "example": "string" }, "amount": { "type": "number", "description": "Amount to be charged per billing cycle" }, "currency": { "type": "string", "description": "Currency code for the plan (e.g. USD, NGN)", "example": "NGN" }, "status": { "type": "string", "enum": ["active", "inactive"], "description": "Current status of the plan (e.g. active, inactive)" }, "regions": { "type": "array", "description": "List of region codes or names where this plan is available", "items": { "type": "string", "example": "string" } }, "subscribers": { "type": "integer", "description": "Number of users currently subscribed to this plan" }, "subscriptions": { "type": "integer", "description": "Total number of subscriptions created for this plan" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the plan was created" }, "trial": { "type": "object", "description": "Trial configuration for this plan", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the trial" }, "planId": { "type": "string", "format": "uuid", "description": "Associated plan ID for this trial" }, "periodInDays": { "type": "integer", "description": "Duration of the trial period in days" }, "pricingList": { "type": "array", "description": "Pricing details during the trial period", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["FLAT", "TIERED"], "description": "Type of pricing applied" }, "amount": { "type": "number", "description": "Amount charged during the trial" }, "currency": { "type": "string", "description": "Currency code (e.g. NGN, USD)", "example": "NGN" } }, "required": ["type", "amount", "currency"] } } }, "required": ["id", "planId", "periodInDays"] }, "pricingOptions": { "type": "array", "description": "List of available pricing options for the plan", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount for this pricing option" }, "currency": { "type": "string", "example": "NGN", "description": "Currency code (e.g. NGN, USD)" } }, "required": ["amount", "currency"] } } }, "required": [ "id", "title", "frequency", "amount", "currency", "status", "createdAt" ] }, "PlansResponse": { "type": "object", "description": "Paginated list of plan details", "properties": { "content": { "type": "array", "description": "List of plan items", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the plan" }, "title": { "type": "string", "description": "Name or title of the plan" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", " QUARTERLY", "BIANNUAL", "ANNUAL" ], "description": "Billing frequency for the plan" }, "internalReference": { "type": "string", "description": "Internal reference code for the plan" }, "amount": { "type": "number", "description": "Amount to be charged per billing cycle" }, "currency": { "type": "string", "description": "Currency code for the plan (e.g. USD, NGN)" }, "status": { "type": "string", "description": "Current status of the plan (e.g. active, inactive)" }, "regions": { "type": "array", "description": "List of region codes or names where this plan is available", "items": { "type": "string" } }, "subscribers": { "type": "integer", "description": "Number of users currently subscribed to this plan" }, "subscriptions": { "type": "integer", "description": "Total number of subscriptions created for this plan" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the plan was created" }, "trial": { "type": "object", "description": "Trial configuration for this plan", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the trial" }, "planId": { "type": "string", "format": "uuid", "description": "Associated plan ID for this trial" }, "periodInDays": { "type": "integer", "description": "Duration of the trial period in days" }, "pricingList": { "type": "array", "description": "Pricing details during the trial period", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["FLAT", "TIERED"], "description": "Type of pricing applied" }, "amount": { "type": "number", "description": "Amount charged during the trial" }, "currency": { "type": "string", "description": "Currency code (e.g. NGN, USD)" } }, "required": ["type", "amount", "currency"] } } }, "required": ["id", "planId", "periodInDays"] }, "pricingOptions": { "type": "array", "description": "List of available pricing options for the plan", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount for this pricing option" }, "currency": { "type": "string", "description": "Currency code (e.g. NGN, USD)" } }, "required": ["amount", "currency"] } } }, "required": [ "id", "title", "frequency", "amount", "currency", "status", "createdAt" ] } }, "pageNumber": { "type": "integer", "description": "Current page number" }, "pageSize": { "type": "integer", "description": "Number of records per page" }, "totalElements": { "type": "integer", "description": "Total number of plan records" }, "totalPages": { "type": "integer", "description": "Total number of available pages" } }, "required": [ "content", "pageNumber", "pageSize", "totalElements", "totalPages" ] }, "CardPaymentMethod": { "type": "object", "description": "Card payment method details", "properties": { "type": { "type": "string", "enum": ["card"], "description": "Discriminator identifying this as a card payment method" }, "firstSix": { "type": "string", "description": "First six digits of the card (BIN)", "example": "506124" }, "lastFour": { "type": "string", "description": "Last four digits of the card", "example": "5456" }, "cardType": { "type": "string", "description": "Card scheme/brand", "example": "verve" }, "accountHolderName": { "type": "string", "description": "Name of the account/card holder", "example": "Jane Doe" }, "expirationMonth": { "type": "integer", "minimum": 1, "maximum": 12, "example": 11 }, "expirationYear": { "type": "integer", "example": 2026 } }, "required": [ "type", "firstSix", "lastFour", "cardType", "expirationMonth", "expirationYear" ] }, "MomoPaymentMethod": { "type": "object", "description": "Mobile money payment method details", "properties": { "type": { "type": "string", "enum": ["momo"], "description": "Discriminator identifying this as a mobile money payment method" }, "operator": { "type": "string", "description": "Mobile money operator/network", "example": "MTN" }, "accountHolderName": { "type": "string", "description": "Name of the account holder", "example": "Jane Doe" }, "phoneNumber": { "type": "string", "description": "Mobile money phone number", "example": "+2348012345678" } }, "required": ["type", "operator", "phoneNumber"] }, "PaymentMethodResponse": { "oneOf": [ { "$ref": "#/components/schemas/CardPaymentMethod" }, { "$ref": "#/components/schemas/MomoPaymentMethod" } ], "discriminator": { "propertyName": "type", "mapping": { "card": "#/components/schemas/CardPaymentMethod", "momo": "#/components/schemas/MomoPaymentMethod" } } }, "CardPaymentMethodUpdateRequest": { "type": "object", "description": "Update payload for setting a card as the payment method", "properties": { "encryptedCard": { "type": "string", "description": "Encrypted card payload generated client-side" } }, "required": ["encryptedCard"] }, "MomoPaymentMethodUpdateRequest": { "type": "object", "description": "Update payload for setting mobile money as the payment method", "properties": { "mobileMoney": { "type": "object", "properties": { "otp": { "type": "string", "description": "One-time PIN sent to the phone number for verification" }, "code": { "type": "string", "description": "Authorization/verification code for the mobile money transaction" }, "name": { "type": "string", "description": "Name of the account holder" }, "phoneNumber": { "type": "string", "description": "Mobile money phone number" } }, "required": ["otp", "code", "name", "phoneNumber"] } }, "required": ["mobileMoney"] }, "PaymentMethodUpdateRequest": { "oneOf": [ { "$ref": "#/components/schemas/CardPaymentMethodUpdateRequest" }, { "$ref": "#/components/schemas/MomoPaymentMethodUpdateRequest" } ] }, "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } }, "SubscriptionPlanDetailsResponse": { "type": "object", "description": "Represents detailed information about a subscription plan including pricing, trial, and region availability.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the subscription plan (UUID)." }, "title": { "type": "string", "example": "string", "description": "The title or name of the subscription plan." }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "BIANNUAL", "ANNUAL" ], "description": "Billing frequency for the subscription plan." }, "internalReference": { "type": "string", "example": "string", "description": "Internal reference code or identifier for the plan." }, "amount": { "type": "number", "description": "The cost amount for the subscription plan." }, "currency": { "type": "string", "example": "NGN", "description": "The currency of the subscription plan (e.g., NGN, USD)." }, "status": { "type": "string", "enum": ["ACTIVE", "INACTIVE", "ARCHIVED"], "description": "The current status of the subscription plan." }, "regions": { "type": "array", "items": { "type": "string" }, "description": "List of regions where this plan is available." }, "subscribers": { "type": "integer", "description": "Total number of active subscribers under this plan." }, "subscriptions": { "type": "integer", "description": "Total number of subscriptions created for this plan." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the plan was created." }, "trial": { "type": "object", "description": "Details about the trial period associated with this plan.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the trial configuration." }, "planId": { "type": "string", "format": "uuid", "description": "The plan ID this trial configuration is associated with." }, "periodInDays": { "type": "integer", "description": "Number of days for the trial period." }, "pricingList": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["FLAT", "TIERED"], "description": "The pricing model for the trial period." }, "amount": { "type": "number", "description": "The cost amount during the trial period." }, "currency": { "type": "string", "example": "NGN", "description": "Currency used for the trial pricing." } } }, "description": "List of pricing configurations for the trial." } } }, "pricingOptions": { "type": "array", "description": "Different pricing options available for the plan.", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "The cost amount for this pricing option." }, "currency": { "type": "string", "example": "NGN", "description": "The currency code for this pricing option (e.g., NGN, USD)." } } } } }, "required": [ "id", "title", "frequency", "amount", "currency", "status", "createdAt" ] }, "AccountBalanceListResponse": { "type": "object", "properties": { "accountNumber": { "type": "string", "example": "7706438396" }, "currency": { "type": "string", "example": "GHS" }, "balance": { "type": "number", "format": "float", "example": 3.0 }, "availableBalance": { "type": "number", "format": "float", "example": 3.0 }, "accountTag": { "type": "string", "example": "main-account" }, "parentAccountNumber": { "type": "string", "example": "string" } }, "required": ["accountNumber", "currency", "balance", "availableBalance"] }, "SubAccountDetailsResponse": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "accountName": { "type": "string", "example": "Main GHS Account" }, "accountNumber": { "type": "string", "example": "7706438396" }, "parentAccountId": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "currency": { "type": "string", "example": "GHS" }, "mode": { "type": "string", "enum": ["live", "test"], "example": "live" }, "accountTag": { "type": "string", "example": "main-account" }, "status": { "type": "string", "example": "active" }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-07-22T11:25:28.792959Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-08-07T11:56:49.337647Z" }, "accountDetails": { "type": "object", "properties": { "accountName": { "type": "string", "example": "SPOTFLOW/Quantum Technologies" }, "accountNumber": { "type": "string", "example": "7806438396" }, "bankName": { "type": "string", "example": "Testbank MFB" } } } } } }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "id", "balanceId", "accountName", "accountNumber", "parentAccountId", "currency", "mode", "status", "createdAt" ] }, "StaticVirtualAccountsDetailsResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "balanceId": { "type": "string", "example": "bln_52448a75-248e-4277-932f-5af5c325d372" }, "accountName": { "type": "string", "example": "Main GHS Account" }, "accountNumber": { "type": "string", "example": "7706438396" }, "parentAccountId": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "currency": { "type": "string", "example": "GHS" }, "mode": { "type": "string", "enum": ["live", "test"], "example": "live" }, "accountTag": { "type": "string", "example": "main-account" }, "status": { "type": "string", "example": "active" }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-07-22T11:25:28.792959Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-08-07T11:56:49.337647Z" }, "accountDetails": { "type": "object", "properties": { "accountName": { "type": "string", "example": "SPOTFLOW/Quantum Technologies" }, "accountNumber": { "type": "string", "example": "7806438396" }, "bankName": { "type": "string", "example": "Testbank MFB" } } } }, "required": [ "id", "balanceId", "accountName", "accountNumber", "parentAccountId", "currency", "mode", "status", "createdAt" ] }, "CreateStaticVirtualAccountsDetailsResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "balanceId": { "type": "string", "example": "bln_52448a75-248e-4277-932f-5af5c325d372" }, "accountName": { "type": "string", "example": "Quantum Technologies" }, "accountNumber": { "type": "string", "example": "7706438396" }, "parentAccountId": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "currency": { "type": "string", "example": "NGN" }, "mode": { "type": "string", "enum": ["live", "test"], "example": "live" }, "accountTag": { "type": "string", "example": "main-account" }, "status": { "type": "string", "example": "active" }, "accountDetails": { "type": "object", "properties": { "accountName": { "type": "string", "example": "SPOTFLOW/Quantum Technologies" }, "accountNumber": { "type": "string", "example": "7806438396" }, "bankName": { "type": "string", "example": "Testbank MFB" } } } }, "required": [ "id", "balanceId", "accountName", "accountNumber", "parentAccountId", "currency", "mode", "status" ] }, "DeactivateStaticVirtualAccountResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "65122475-eef0-47e6-8c47-ac461e0a080d" }, "parentAccountId": { "type": "string", "format": "uuid", "example": "0863bce7-2202-4f9a-8546-06fcbf7203e0" }, "autoSweep": { "type": "boolean", "example": false }, "currency": { "type": "string", "example": "NGN" }, "mode": { "type": "string", "enum": ["test", "live"], "example": "live" }, "accountTag": { "type": "string", "example": "sub-account" }, "status": { "type": "string", "example": "inactive", "description": "Reflects the account's current state after deactivation." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-08-06T09:59:21.074471Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-08-14T09:52:22.830371Z" }, "accountDetails": { "$ref": "#/components/schemas/VirtualAccountDetails" }, "virtualAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualAccountDetails" } } } }, "VirtualAccountDetails": { "type": "object", "properties": { "provider": { "type": "string", "example": "AELLA" }, "accountName": { "type": "string", "example": "SP/pord" }, "accountNumber": { "type": "string", "example": "0217222147" }, "bankName": { "type": "string", "example": "Aella Microfinance Bank" }, "default": { "type": "boolean", "example": true }, "depositAddresses": { "type": "array", "items": { "type": "string" } }, "countryCode": { "type": "string", "example": "NG" } } }, "DynamicDetailsResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "accountNumber": { "type": "string", "example": "7706438396" }, "accountName": { "type": "string", "example": "Quantum Technologies" }, "bankName": { "type": "string", "example": "Testbank MFB" }, "mode": { "type": "string", "enum": ["live", "test"], "example": "live" }, "lifeCycle": { "type": "string", "example": "temporary" } } }, "TransferDetailsResponse": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "spotflowreference": { "type": "string", "format": "uuid", "example": "c1fba25a-a36b-479c-b17d-64dbaf3ba32c" }, "amount": { "type": "number", "format": "int32", "example": 0 }, "currency": { "type": "string", "example": "NGN" }, "transferMode": { "type": "string", "example": "7706438396" }, "destination": { "type": "object", "properties": { "accountNumber": { "type": "string", "example": "7706438396" }, "accountName": { "type": "string", "example": "Quantum Technologies" }, "bankCode": { "type": "string", "example": "NGN100" }, "branchCode": { "type": "string", "example": "NGN100" }, "bankName": { "type": "string", "example": "Testbank MFB" } } }, "narrations": { "type": "string", "example": "string" }, "status": { "type": "string", "example": "string" } } }, "PaymentResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "reference": { "type": "string", "example": "REF123456789" }, "spotflowReference": { "type": "string", "example": "SPF-REF-001" }, "amount": { "type": "number", "example": 100.0 }, "currency": { "type": "string", "example": "USD" }, "localAmount": { "type": "number", "example": 156000.0 }, "totalFees": { "type": "number", "example": 500.0 }, "localCurrency": { "type": "string", "example": "NGN" }, "channel": { "type": "string", "example": "card" }, "status": { "type": "string", "example": "SUCCESS" }, "mode": { "type": "string", "example": "TEST" }, "rate": { "type": "number", "example": 1560.0 }, "region": { "type": "string", "example": "Nigeria" }, "authorization": { "type": "object", "properties": { "mode": { "type": "string", "example": "Pin" } } }, "ussd": { "type": "object", "properties": { "code": { "type": "string", "example": "*737#" }, "paymentCode": { "type": "string", "example": "123456" } } }, "bankDetails": { "type": "object", "properties": { "accountName": { "type": "string", "example": "John Doe" }, "accountNumber": { "type": "string", "example": "0123456789" }, "bankName": { "type": "string", "example": "Access Bank" } } }, "card": { "type": "object", "properties": { "type": { "type": "string", "example": "VISA" }, "firstSix": { "type": "string", "example": "412345" }, "lastFour": { "type": "string", "example": "6789" } } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-10-17T15:21:11.287Z" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "orderId": "ORD-000123", "note": "First payment" } }, "totalTaxAmount": { "type": "number", "example": 50.0 }, "totalLocalAmount": { "type": "number", "example": 156050.0 }, "planId": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "mobileMoney": { "type": "object", "properties": { "otp": { "type": "string", "example": "1234" }, "code": { "type": "string", "example": "MTN" }, "name": { "type": "string", "example": "MTN Mobile Money" }, "phoneNumber": { "type": "string", "example": "+233540000000" } } } }, "required": ["id", "reference", "amount", "currency", "status"] }, "SubscriptionError401": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_ERROR" }, "message": { "type": "string", "example": "Authorization token is required." }, "statusCode": { "type": "integer", "format": "float", "example": 401 }, "requestMarker": { "type": "string", "format": "uuid" } }, "required": ["status", "statusCode", "message"] }, "Error401": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "invalid_credentials" }, "status": { "type": "integer", "format": "float", "example": 401 } } }, "Error400": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing Parameter" }, "message": { "type": "string", "example": "missing_parameter" }, "status": { "type": "integer", "format": "float", "example": 400 } } } } } }