{ "openapi": "3.0.3", "info": { "title": "Partner API", "version": "1.0.0", "description": "OpenAPI spec for Partner Terminal and Transaction API" }, "servers": [ { "url": "https://staging-api.yourflexpay.com/v2", "description": "Staging" }, { "url": "https://sandbox-api.yourflexpay.com/v2", "description": "Sandbox" }, { "url": "https://api.yourflexpay.com/v2", "description": "Live" } ], "tags": [ { "name": "Partner Terminal" }, { "name": "Partner Transactions" } ], "paths": { "/terminal": { "get": { "tags": [ "Partner Terminal" ], "summary": "Get terminal profile", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" } ], "responses": { "200": { "description": "Terminal info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPartnerTerminal" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/transaction": { "post": { "tags": [ "Partner Terminal" ], "summary": "Initiate terminal transaction", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateTransactionDto" } } } }, "responses": { "200": { "description": "Transaction reference or payload token", "content": { "application/json": { "schema": { "type": "string" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/transactions": { "get": { "tags": [ "Partner Terminal" ], "summary": "List terminal transactions", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "name": "startDate", "in": "query", "schema": { "type": "string", "description": "Date filter in YYYYMMDD format" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "description": "Date filter in YYYYMMDD format" } } ], "responses": { "200": { "description": "Paginated transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPartnerTransactionResponse" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/transaction/{reference}": { "get": { "tags": [ "Partner Terminal" ], "summary": "Get transaction by reference", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" }, { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPartnerTransaction" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/split": { "post": { "tags": [ "Partner Terminal" ], "summary": "Create split", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSplitDto" } } } }, "responses": { "200": { "description": "Split created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Split" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/splits": { "get": { "tags": [ "Partner Terminal" ], "summary": "List splits", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated splits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSplitResponse" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/split/{split}": { "get": { "tags": [ "Partner Terminal" ], "summary": "Get split by reference", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" }, { "name": "split", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Split details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Split" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/terminal/split/{split}/qr": { "get": { "tags": [ "Partner Terminal" ], "summary": "Generate split payment QR payload", "parameters": [ { "$ref": "#/components/parameters/TerminalHeaderParam" }, { "name": "split", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "number", "format": "float" } } ], "responses": { "200": { "description": "QR transaction payload", "content": { "application/json": { "schema": { "type": "string" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/partner/transaction/initiate": { "post": { "tags": [ "Partner Transactions" ], "summary": "Initiate partner transaction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateTransactionDto" } } } }, "responses": { "200": { "description": "Transaction reference or ID", "content": { "application/json": { "schema": { "type": "string" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/partner/transactions": { "get": { "tags": [ "Partner Transactions" ], "summary": "Get partner transactions", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "name": "terminal", "in": "query", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "schema": { "type": "string", "description": "Date filter in YYYY-MM-DD format" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "description": "Date filter in YYYY-MM-DD format" } } ], "responses": { "200": { "description": "Paginated transaction list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPartnerTransactionResponse" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } }, "/partner/transaction/{reference}": { "get": { "tags": [ "Partner Transactions" ], "summary": "Get partner transaction by reference", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPartnerTransaction" } } } } }, "security": [ { "ClientIdHeader": [], "ApiKeyHeader": [] } ] } } }, "components": { "securitySchemes": { "ClientIdHeader": { "type": "apiKey", "in": "header", "name": "x-client-id" }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "TerminalHeader": { "type": "apiKey", "in": "header", "name": "x-terminal", "description": "Terminal serial number" } }, "parameters": { "TerminalHeaderParam": { "name": "x-terminal", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Terminal serial number" } }, "schemas": { "IPartnerTerminal": { "type": "object", "required": [ "SerialNumber", "TerminalID", "Merchant", "Email", "PhoneNumber", "Status", "CreatedAt", "Metadata", "PayTag", "Balance" ], "properties": { "SerialNumber": { "type": "string" }, "TerminalID": { "type": "string" }, "Merchant": { "type": "string" }, "Email": { "type": "string" }, "PhoneNumber": { "type": "string" }, "Status": { "type": "string" }, "CreatedAt": { "type": "string", "format": "date-time" }, "Metadata": { "type": "object", "additionalProperties": true }, "PayTag": { "type": "string" }, "Balance": { "type": "number" }, "Qr": { "type": "string" } } }, "InitiateTransactionDto": { "type": "object", "required": [ "amount", "reference" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "amount": { "type": "number", "minimum": 100 }, "reference": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "description": { "type": "string", "maxLength": 255 }, "metadata": { "type": "object", "additionalProperties": true } } }, "CreateSplitDto": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number" }, "title": { "type": "string", "maxLength": 50 }, "description": { "type": "string", "maxLength": 255 }, "reference": { "type": "string" } } }, "Split": { "type": "object", "required": [ "Amount", "Reference", "TotalPaid", "Remaining", "Status" ], "properties": { "Amount": { "type": "number" }, "Reference": { "type": "string" }, "Title": { "type": "string" }, "Description": { "type": "string" }, "TotalPaid": { "type": "number" }, "Remaining": { "type": "number" }, "Status": { "$ref": "#/components/schemas/SplitStatus" } } }, "IPartnerTransaction": { "type": "object", "required": [ "Amount", "Fee", "Commission", "Net", "Reference", "Sender", "SenderDetails", "Recipient", "Status", "Comment", "Date", "Metadata" ], "properties": { "Amount": { "type": "number" }, "Fee": { "type": "number" }, "Commission": { "type": "number" }, "Net": { "type": "number" }, "Reference": { "type": "string" }, "Sender": { "type": "string" }, "SenderDetails": { "$ref": "#/components/schemas/TransactionPartyDetail" }, "Recipient": { "type": "string" }, "Status": { "$ref": "#/components/schemas/TransactionStatus" }, "CompletedAt": { "type": "string", "format": "date-time" }, "Comment": { "type": "string" }, "Date": { "type": "string", "format": "date-time" }, "Metadata": { "type": "object", "additionalProperties": true }, "Terminal": { "$ref": "#/components/schemas/IPartnerTerminal" } } }, "TransactionPartyDetail": { "type": "object", "required": [ "Name", "Amount", "Fee", "Currency" ], "properties": { "Name": { "type": "string" }, "Paytag": { "type": "string" }, "ProfileImage": { "type": "string" }, "Type": { "$ref": "#/components/schemas/AccountType" }, "External": { "type": "boolean" }, "Amount": { "type": "number" }, "Fee": { "type": "number" }, "Currency": { "$ref": "#/components/schemas/WalletCurrency" } } }, "PaginatedPartnerTransactionResponse": { "type": "object", "required": [ "items", "count", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IPartnerTransaction" } }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "PaginatedSplitResponse": { "type": "object", "required": [ "items", "count", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Split" } }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "AccountType": { "type": "string", "enum": [ "AdminAuth", "Customer", "Merchant", "MerchantUser", "Partner" ] }, "WalletCurrency": { "type": "string", "enum": [ "NGN", "FP" ] }, "TransactionStatus": { "type": "string", "enum": [ "Pending", "Failed", "Successful", "Cancelled", "Expired", "Pending Review", "Waiting on Provider" ] }, "SplitStatus": { "type": "string", "enum": [ "Pending", "Completed" ] } } } }