{ "openapi": "3.0.1", "info": { "title": "Mavapay API", "description": "API documentation for Mavapay", "license": { "name": "MIT" }, "version": "1.0.0", "contact": { "name": "Mavapay", "url": "https://mavapay.co", "email": "info@mavapay.co" } }, "servers": [ { "url": "https://staging.api.mavapay.co/api/v1", "description": "Staging server" }, { "url": "https://api.mavapay.co/api/v1", "description": "Live server" } ], "security": [ { "ApiKeyAuth": [], "bearerAuth": [] } ], "paths": { "/price/ticker": { "get": { "security": [], "tags": ["Price"], "operationId": "getPriceTicker", "summary": "Get price ticker for currency pair", "description": "Returns the exchange rate for a given currency pair", "parameters": [ { "name": "pair", "in": "query", "description": "Currency pair to get the exchange rate for", "schema": { "type": "string", "enum": [ "usdngn", "btcusd", "usdkes", "usdzar", "zarngn", "kesngn" ] }, "required": true, "example": "usdngn" } ], "responses": { "200": { "description": "Price ticker response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceTicker" } } } }, "400": { "description": "Invalid currency pair", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bankaccount": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Bank Account"], "operationId": "getBankAccount", "summary": "Get bank account details", "description": "Returns all your saved bank accounts for a given currency. The bank account details used to make payouts to your customers.", "parameters": [ { "name": "walletId", "in": "query", "description": "The wallet ID to get the bank account for (optional)", "schema": { "type": "string", "format": "uuid" }, "required": false }, { "name": "currency", "in": "query", "description": "The currency to get the bank account for (optional). Only NGN is supported at the moment.", "schema": { "type": "string", "enum": ["NGN"] }, "required": false } ], "responses": { "200": { "description": "Bank account response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Bank Account"], "operationId": "createBankAccount", "summary": "Register a bank account", "description": "Register a bank account that can be used for withdrawal for a given currency. Only NGN is supported at the moment.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccount" } } }, "required": true }, "responses": { "200": { "description": "Bank account response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/BankAccount" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bank/bankcode": { "get": { "security": [], "tags": ["Bank Code"], "operationId": "getBankCode", "summary": "Get bank code", "description": "Returns all bank codes for a given country. This endpoint is currently limited to Nigeria(NGN) and South Africa(ZAR) only.", "parameters": [ { "name": "country", "in": "query", "description": "The country to get the bank codes for. Use 'NG' for Nigeria and 'ZA' for South Africa.", "schema": { "type": "string", "enum": ["NG", "ZA"] }, "required": true } ], "responses": { "200": { "description": "Bank code response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankCode" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bank/name-enquiry": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": ["Bank Account"], "operationId": "getBankNameEnquiry", "summary": "Verify bank account details if it is correct", "description": "Verify bank account details if it is correct. The response returned should match the account number and account name of the user. This endpoint is currently limited to Nigeria(NGN) only", "parameters": [ { "name": "accountNumber", "in": "query", "description": "The account number to verify", "schema": { "type": "string", "format": "string" }, "required": true }, { "name": "bankCode", "in": "query", "description": "The bank code to verify", "schema": { "type": "string", "format": "string" }, "required": true } ], "responses": { "200": { "description": "Bank name enquiry response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankNameEnquiry" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/order": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Order"], "operationId": "getOrder", "summary": "Get order details", "description": "Returns the order details for a given order ID", "parameters": [ { "name": "id", "in": "query", "description": "The order ID to get the details for", "schema": { "type": "string", "format": "string" }, "required": true } ], "responses": { "200": { "description": "Order response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/order/all": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Order"], "operationId": "getAllOrders", "summary": "Get all orders", "description": "Returns all orders", "responses": { "200": { "description": "Order response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AllOrders" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quote": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Quote"], "operationId": "createQuote", "summary": "Create a quote", "description": "Create a quote for a given currency", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuote" }, "examples": { "buyBtcWithNgnAmountInNaira": { "summary": "Buy Bitcoin with Naira (Amount in NGN)", "description": "Quote for buying Bitcoin where the amount is specified in Nigerian Naira. You want to spend exactly ₦5,000.", "value": { "amount": "500000", "sourceCurrency": "NGNKOBO", "targetCurrency": "BTCSAT", "paymentMethod": "BANKTRANSFER", "paymentCurrency": "NGNKOBO", "customerReference": "order-1234567890", "autopayout": false } }, "buyBtcWithNgnAmountInBtc": { "summary": "Buy Bitcoin with Naira (Amount in BTC)", "description": "Quote for buying Bitcoin where the amount is specified in satoshis. You want to receive exactly 5,000 sats.", "value": { "amount": "5000", "sourceCurrency": "NGNKOBO", "targetCurrency": "BTCSAT", "paymentMethod": "BANKTRANSFER", "paymentCurrency": "BTCSAT", "customerReference": "order-1234567890", "autopayout": false } }, "buyBtcWithAutopayout": { "summary": "Buy Bitcoin with Autopayout (Lightning)", "description": "Quote for buying Bitcoin with automatic payout to a Lightning invoice. The invoice amount must match the quote amount.", "value": { "amount": "208238", "sourceCurrency": "NGNKOBO", "targetCurrency": "BTCSAT", "paymentMethod": "BANKTRANSFER", "paymentCurrency": "BTCSAT", "customerReference": "order-1234567890", "autopayout": true, "beneficiary": { "lnInvoice": "lnbc2082380n1p5fhytmpp5ujnmhfhle6qpc22x0ghyh0w0geufk2qscpuegr0wu4yrpscexv8qdq8g36kuuccqzzsxqzfvsp5ely8sp5cgatch8e02uujamy39rwmjdd5pgmakptsq74u6redpnzq9qxpqysgq2lry5dgzu2g04s74tpvctwe37rkprs3k579jw6yt7ncrsg62p29yalw8gf5fawfvpydqv4jjve0nsysfhsxa35dtwug9e6gzxkq0h5gp636wc3" } } }, "btcToNgn": { "summary": "Sell Bitcoin for Naira", "description": "Quote for selling Bitcoin to receive Nigerian Naira in a bank account.", "value": { "amount": "1000000", "sourceCurrency": "BTCSAT", "targetCurrency": "NGNKOBO", "paymentMethod": "LIGHTNING", "paymentCurrency": "NGNKOBO", "autopayout": true, "customerReference": "order-1234567890", "beneficiary": { "bankAccountName": "olaolu olajide", "bankCode": "000013", "bankName": "GTBANK PLC", "bankAccountNumber": "0087241555" } } } } } }, "required": true }, "responses": { "200": { "description": "Quote response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Quote" } } }, "examples": { "buyBtcWithNgnResponse": { "summary": "Buy BTC with NGN Response", "description": "Response for buying Bitcoin with Nigerian Naira showing bank transfer details", "value": { "status": "ok", "data": { "id": "53a87b44-2ecc-4106-8297-f1fd15d010a9", "exchangeRate": 1, "usdToTargetCurrencyRate": 0.00000917325600278523, "sourceCurrency": "NGNKOBO", "targetCurrency": "BTCSAT", "transactionFeesInSourceCurrency": 4624, "transactionFeesInTargetCurrency": 25, "amountInSourceCurrency": 844540, "amountInTargetCurrency": 5000, "paymentMethod": "BANKTRANSFER", "expiry": "2025-09-01T12:52:08.215Z", "isValid": true, "invoice": "", "hash": "68b594a09a16ac0012ae3414", "totalAmountInSourceCurrency": 844540, "customerInternalFee": 0, "bankName": "GLOBUS BANK", "ngnBankAccountNumber": "3242273802", "ngnAccountName": "Mava Digital Solutions Limited", "ngnBankCode": "000027", "estimatedRoutingFee": 0, "orderId": "43477-4306" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quote/validate-kes-identifier": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Quote"], "operationId": "validateKesIdentifier", "summary": "Validate KES identifier", "description": "Validate a Kenyan M-Pesa PayBill or Till number and retrieve the associated business name. This endpoint is only available in production.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["identifier", "identifierType"], "properties": { "identifier": { "type": "string", "description": "The paybill or till number to validate", "example": "247247" }, "identifierType": { "type": "string", "enum": ["PayBill", "Till"], "description": "The type of identifier to validate", "example": "PayBill" } } }, "examples": { "validatePaybill": { "summary": "Validate Paybill", "description": "Validate a Kenyan M-Pesa paybill number", "value": { "identifier": "247247", "identifierType": "PayBill" } }, "validateTill": { "summary": "Validate Till", "description": "Validate a Kenyan M-Pesa till number", "value": { "identifier": "796980711", "identifierType": "Till" } } } } }, "required": true }, "responses": { "200": { "description": "Validation successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "organization_name": { "type": "string", "description": "The name of the business associated with the identifier" } } } } }, "examples": { "paybillResponse": { "summary": "Paybill Validation Response", "value": { "status": "ok", "data": { "organization_name": "Equity Paybill Account" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallet": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Wallet"], "operationId": "getWallet", "summary": "Get wallet details", "description": "Returns the wallet details for a given wallet ID or all wallets", "parameters": [ { "name": "walletId", "in": "query", "description": "The wallet ID to get the details for (optional)", "schema": { "type": "string", "format": "uuid" }, "required": false }, { "name": "currency", "in": "query", "description": "The currency to get the details for (optional)", "schema": { "type": "string", "enum": ["NGN", "KES", "BTC", "USD"] }, "required": false } ], "responses": { "200": { "description": "Wallet response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallet/payout/{quoteId}/accept": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Wallet"], "operationId": "acceptQuote", "summary": "Accept Swap Quote", "description": "Accept a quote to perform an internal currency swap", "parameters": [ { "name": "quoteId", "in": "path", "description": "The ID of the quote to accept", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceWallet": { "type": "string", "description": "The source wallet currency (e.g., 'NGN')", "example": "NGN" } }, "required": ["sourceWallet"] } } }, "required": true }, "responses": { "200": { "description": "Successful swap", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "quote is being processed" } } } } } }, "400": { "description": "Invalid request or expired quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/withdraw": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Withdraw"], "operationId": "withdraw", "summary": "Withdraw fiat", "description": "Withdraw funds to a bank account. The amount is specified in the lowest denomination of the currency (e.g., Kobo for NGN). You must first verify the bank account using the Name Enquiry endpoint before initiating a withdrawal.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["amount", "currency", "beneficiary"], "properties": { "amount": { "type": "string", "description": "The amount to withdraw in the lowest denomination (e.g., Kobo for NGN). For example, 100000 = 1,000.00 NGN", "example": "100000" }, "currency": { "type": "string", "description": "The currency to withdraw", "enum": ["NGN"] }, "beneficiary": { "type": "object", "description": "The beneficiary bank account details. Use the exact values returned from the Name Enquiry endpoint.", "required": [ "bankAccountNumber", "bankAccountName", "bankCode", "bankName" ], "properties": { "bankAccountNumber": { "type": "string", "description": "The recipient's bank account number", "example": "0123456789" }, "bankAccountName": { "type": "string", "description": "The account holder's name as returned by the Name Enquiry endpoint. Must match exactly.", "example": "JOHN DOE" }, "bankCode": { "type": "string", "description": "The NIP bank code (nipBankCode) from the bank list", "example": "000013" }, "bankName": { "type": "string", "description": "The bank name as returned from the bank list", "example": "GTBANK PLC" } } } } }, "examples": { "withdrawNgn": { "summary": "Withdraw NGN to Bank Account", "description": "Withdraw Nigerian Naira to a verified bank account", "value": { "amount": "100000", "currency": "NGN", "beneficiary": { "bankAccountNumber": "0123456789", "bankAccountName": "JOHN DOE", "bankCode": "000013", "bankName": "GTBANK PLC" } } } } } }, "required": true }, "responses": { "200": { "description": "Withdraw response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "object", "$ref": "#/components/schemas/Transaction" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/withdraw/btc": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Withdraw"], "operationId": "withdrawBtc", "summary": "Withdraw BTC", "description": "Withdraw BTC to a wallet", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "string", "format": "string", "example": "lntbs1234567890n1pjnruqtpp5xmrq39nwyhgde4a94wsnuacj4stacls05g4x5du2req9pvjpqz6sdz9296k7ar98gsxgdm9vvmx2v3s95ckyceh956xvd3595uxyetr95cnydrxxv6nvwrxv5mngcqzpuxqzfvsp578t78k4628snkkhc43eqrpn6sem28w4cwgzn7ceyyr320kwm4uss9qyyssqcwxw8wy2qenwgm7gagx9lwvcs9w9tw47ntuc823yclasjqczvvj545hr4d9nmg996l0cswudgeawclwytafmh66a2fafk4heksyae5sq3vzd28" }, "memo": { "type": "string", "format": "string", "example": "Withdrawal to wallet" } } } } }, "required": true }, "responses": { "200": { "description": "Withdraw response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "object", "$ref": "#/components/schemas/Transaction" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/register": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Webhook"], "operationId": "registerWebhook", "summary": "Register a webhook", "description": "Register a webhook to receive notifications for transaction events", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "string", "example": "https://webhook.site/12345678-1234-1234-1234-123456789012" }, "secret": { "type": "string", "format": "string", "example": "secret" } } } } }, "required": true }, "responses": { "200": { "description": "Webhook response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "object", "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook": { "put": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Webhook"], "operationId": "updateWebhook", "summary": "Update a webhook", "description": "Update a webhook to receive notifications for transaction events", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "string", "example": "https://webhook.site/12345678-1234-1234-1234-123456789012" }, "secret": { "type": "string", "format": "string", "example": "secret" } } } } }, "required": true }, "responses": { "200": { "description": "Webhook response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "type": "object", "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Transaction"], "operationId": "getTransaction", "summary": "Get transaction details", "description": "Returns the transaction details for a given transaction ID or transactions associated with an order", "parameters": [ { "name": "id", "in": "query", "description": "The transaction ID to get the details for", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "orderId", "in": "query", "description": "The order ID to get the transactions for", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "hash", "in": "query", "description": "The payment hash of the transaction to get the details for", "schema": { "type": "string", "format": "string" }, "required": false } ], "responses": { "200": { "description": "Transaction response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/TransactionResponse" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Transaction"], "operationId": "getTransactions", "summary": "Get all transactions", "description": "Returns all transactions with pagination and filtering options", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "name": "limit", "in": "query", "description": "Number of items per page", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100 }, "required": false }, { "name": "txId", "in": "query", "description": "Filter by transaction ID", "schema": { "type": "string", "format": "uuid" }, "required": false }, { "name": "accountName", "in": "query", "description": "Filter by account name (only applicable for NGN and ZAR transactions)", "schema": { "type": "string" }, "required": false }, { "name": "status", "in": "query", "description": "Filter by transaction status", "schema": { "type": "string", "enum": ["SUCCESS", "PENDING", "FAILED"] }, "required": false }, { "name": "type", "in": "query", "description": "Filter by transaction type", "schema": { "type": "string", "enum": ["WITHDRAWAL", "DEPOSIT"] }, "required": false }, { "name": "currency", "in": "query", "description": "The currency of the transaction", "schema": { "type": "string", "enum": ["NGN", "KES", "ZAR"] }, "required": false }, { "name": "minAmount", "in": "query", "description": "Filter by minimum amount (in lowest denomination of the currency)", "schema": { "type": "integer", "minimum": 0 }, "required": false }, { "name": "maxAmount", "in": "query", "description": "Filter by maximum amount (in lowest denomination of the currency)", "schema": { "type": "integer", "minimum": 0 }, "required": false }, { "name": "startDate", "in": "query", "description": "Filter transactions from this date (ISO 8601 format)", "schema": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "required": false }, { "name": "endDate", "in": "query", "description": "Filter transactions until this date (ISO 8601 format)", "schema": { "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z" }, "required": false } ], "responses": { "200": { "description": "Transaction response with pagination", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "all transaction" }, "count": { "type": "integer", "description": "Total number of transactions", "example": 1 }, "nextPage": { "type": "boolean", "description": "Whether there is a next page available", "example": false }, "currentPage": { "type": "integer", "description": "Current page number", "example": 1 }, "remainingPage": { "type": "integer", "description": "Number of remaining pages", "example": 0 }, "totalPages": { "type": "integer", "description": "Total number of pages", "example": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResponse" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["User"], "operationId": "getUser", "summary": "Get user profile", "description": "Returns an exhaustive user profile detail", "responses": { "200": { "description": "User response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/signup/business": { "post": { "security": [], "tags": ["Signup"], "operationId": "signupBusiness", "summary": "Create a business account", "description": "Create a new Mavapay business account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signup" } } }, "required": true }, "responses": { "201": { "description": "User response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "message": { "type": "string", "format": "string", "example": "business account created successfully" } } } } } }, "400": { "description": "Bad Credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "error" }, "message": { "type": "string", "format": "string", "example": "business account already exists" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "error" }, "message": { "type": "string", "format": "string", "example": "Internal Server Error" } } } } } } } } }, "/auth/signin": { "post": { "security": [], "tags": ["Signin"], "operationId": "signin", "summary": "Sign in to your account", "description": "Sign in to your Mavapay account", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "johndoe@email.com" }, "password": { "type": "string", "format": "string", "example": "password" } } } } }, "required": true }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "message": { "type": "string", "format": "string", "example": "Login successful" }, "data": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "error" }, "message": { "type": "string", "format": "string", "example": "Invalid username or password" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/change-password": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["User"], "operationId": "changePassword", "summary": "Change user password", "description": "Change the user's password", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oldPassword": { "type": "string", "format": "string", "example": "password" }, "newPassword": { "type": "string", "format": "string", "example": "password" } } } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "message": { "type": "string", "format": "string", "example": "Password changed successfully" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "error" }, "message": { "type": "string", "format": "string", "example": "Old password is incorrect" } } } } } } } } }, "/paymentlink": { "post": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Payment Link"], "operationId": "createPaymentLink", "summary": "Create a payment link", "description": "Create a hosted payment link for collecting payments. Payment links simplify the checkout process by creating a hosted payment page where users can complete payments.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" }, "examples": { "onChainPaymentLink": { "summary": "On-Chain Bitcoin Payment Link", "description": "Create a payment link for on-chain Bitcoin settlement", "value": { "name": "Bitcoin Purchase", "description": "On-chain Bitcoin payment", "type": "One_Time", "addFeeToTotalCost": false, "settlementCurrency": "BTC", "settlementMethod": "ONCHAIN", "speed": "medium", "paymentCurrency": "NGN", "paymentMethods": ["BANKTRANSFER"], "beneficiary": { "onChainAddress": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5" }, "amount": 800000, "callbackUrl": "https://your-app.com/callback" } }, "lightningPaymentLink": { "summary": "Lightning Bitcoin Payment Link", "description": "Create a payment link for Lightning Network settlement", "value": { "name": "Lightning Payment", "description": "Lightning Bitcoin payment", "type": "One_Time", "addFeeToTotalCost": false, "settlementCurrency": "BTC", "settlementMethod": "LIGHTNING", "paymentCurrency": "NGN", "paymentMethods": ["BANKTRANSFER"], "beneficiary": { "lnAddress": "user@getalby.com" }, "amount": 500000, "callbackUrl": "https://your-app.com/callback" } } } } }, "required": true }, "responses": { "200": { "description": "Payment link created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "payment link created successfully" }, "data": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/paymentlink/details": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Payment Link"], "operationId": "getPaymentLinkDetails", "summary": "Get payment link details", "description": "Retrieve details about a payment link for rendering a custom UI or checking payment status.", "parameters": [ { "name": "id", "in": "query", "description": "The payment link ID (paymentRef) to get details for", "schema": { "type": "string", "format": "uuid" }, "required": true, "example": "9f8bf7da-f1d8-4c78-8f93-28eebe17c35e" } ], "responses": { "200": { "description": "Payment link details", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "payment link details" }, "data": { "$ref": "#/components/schemas/PaymentLinkDetails" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Payment link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/paymentlink/orders": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Payment Link"], "operationId": "getPaymentLinkOrders", "summary": "Get payment link orders", "description": "Retrieve orders associated with a payment link. Useful for getting the order ID for payment simulation in staging.", "parameters": [ { "name": "id", "in": "query", "description": "The payment link ID (paymentRef) to get orders for", "schema": { "type": "string", "format": "uuid" }, "required": true, "example": "9f8bf7da-f1d8-4c78-8f93-28eebe17c35e" } ], "responses": { "200": { "description": "Payment link order details", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "paymentlink order details" }, "data": { "$ref": "#/components/schemas/PaymentLinkOrderDetails" } } }, "examples": { "paymentLinkOrdersResponse": { "summary": "Payment Link Orders Response", "value": { "status": "ok", "message": "paymentlink order details", "data": { "id": "7e644e02-e652-42d8-8857-e8ae46bccd59", "name": "Small payment for Solomon", "description": "Small Payment for Demo Purposes", "type": "ONE_TIME", "amount": "2000000", "fee": null, "addFeeToTotalCost": false, "settlementCurrency": "BTC", "settlementMethod": "ONCHAIN", "speed": "medium", "paymentCurrency": "NGN", "paymentMethods": ["BANKTRANSFER"], "callbackUrl": "https://mavapay.co/login", "channel": "API", "status": "ACTIVE", "accountId": "1a0f79fb-0f3e-4b5b-98f1-1e14324ca62e", "expiresAt": null, "invoice": null, "companyLogo": null, "beneficiaryId": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5", "createdAt": "2026-01-09T12:36:09.582Z", "updatedAt": "2026-01-09T12:36:09.582Z", "orders": [ { "id": "eb1377a8-5afd-4888-a702-d510d070466b", "status": "EXPIRED", "orderId": "49508-6205", "paymentLinkId": "7e644e02-e652-42d8-8857-e8ae46bccd59", "paymentMethod": "BANKTRANSFER", "createdAt": "2026-01-09T12:36:25.924Z", "updatedAt": "2026-01-09T12:47:10.254Z" }, { "id": "35a153c9-dff0-4cb5-a603-e494965ed6ad", "status": "PENDING", "orderId": "17454-1571", "paymentLinkId": "7e644e02-e652-42d8-8857-e8ae46bccd59", "paymentMethod": "BANKTRANSFER", "createdAt": "2026-01-09T13:09:59.212Z", "updatedAt": "2026-01-09T13:09:59.212Z" } ] } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "BankAccount": { "type": "object", "properties": { "bankName": { "type": "string", "format": "string", "example": "KUDA MICROFINANCE BANK" }, "bankCode": { "type": "string", "format": "string", "example": "090267" }, "bankAccountNumber": { "type": "string", "format": "string", "example": "0123456789" }, "bankAccountName": { "type": "string", "format": "string", "example": "Satoshi Nakamoto" }, "currency": { "type": "string", "format": "string", "enum": ["NGN"] }, "walletId": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b-123456789" } } }, "BankCode": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "message": { "type": "string", "format": "string", "example": "all bank codes retrieved successfully" }, "data": { "type": "array", "items": { "type": "object", "properties": { "bankName": { "type": "string", "format": "string", "example": "KUDA MICROFINANCE BANK" }, "nipBankCode": { "type": "string", "format": "string", "example": "090267" } } } } } }, "BankNameEnquiry": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "message": { "type": "string", "format": "string", "example": "Bank account name verified successfully" }, "data": { "type": "object", "properties": { "accountName": { "type": "string", "format": "string", "example": "Oladeji Olaolu" }, "accountNumber": { "type": "string", "format": "string", "example": "0123456789" }, "kycLevel": { "type": "string", "format": "string", "example": "3" }, "nameInquiryReference": { "type": "string", "format": "string", "example": "123456789" }, "channelCode": { "type": "string", "format": "string", "example": "123456789" } } } } }, "Order": { "type": "object", "properties": { "orderId": { "type": "string", "format": "string", "example": "99854-2345" }, "quoteId": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "status": { "type": "string", "format": "string", "enum": ["PAID", "PENDING", "EXPIRED", "FAILED"] }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES"] }, "paymentCollectionMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING", "ONCHAIN", "USDT"] }, "isValid": { "type": "boolean", "format": "boolean", "example": true }, "displayAmount": { "type": "string", "format": "string", "example": "1000.00 NGN" }, "paymentBtcDetail": { "type": "string", "format": "string", "example": "lntbs14912790n1pjnruqtpp5xmrq39nwyhgde4a94wsnuacj4stacls05g4x5du2req9pvjpqz6sdz9296k7ar98gsxgdm9vvmx2v3s95ckyceh956xvd3595uxyetr95cnydrxxv6nvwrxv5mngcqzpuxqzfvsp578t78k4628snkkhc43eqrpn6sem28w4cwgzn7ceyyr320kwm4uss9qyyssqcwxw8wy2qenwgm7gagx9lwvcs9w9tw47ntuc823yclasjqczvvj545hr4d9nmg996l0cswudgeawclwytafmh66a2fafk4heksyae5sq3vzd28" }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "AllOrders": { "type": "object", "properties": { "orderId": { "type": "string", "format": "string", "example": "99854-2345" }, "quoteId": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "status": { "type": "string", "format": "string", "enum": ["PAID", "PENDING", "EXPIRED", "FAILED"] }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES"] }, "paymentMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING", "ONCHAIN", "USDT"] }, "isValid": { "type": "boolean", "format": "boolean", "example": true }, "amount": { "type": "string", "format": "string", "example": "1000.00" }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "exchangeRate": { "type": "number", "format": "number", "example": 103830225.71866913, "description": "The exchange rate is the rate of 1 BTC to the targetCurrency. So if you generated a quote for NGN->BTC (targetCurrency is BTC), the rate will be 1 because the exchange rate of 1 BTC to BTC is 1. If it's a quote of BTC->NGN (targetCurrency is NGN), the rate will likely be 103830225.71866913 i.e., 1 BTC to NGN" }, "usdToTargetCurrencyRate": { "type": "number", "format": "number", "example": 1500.65, "description": "The USD to target currency rate for the quote" }, "sourceCurrency": { "type": "string", "format": "string", "enum": ["BTCSAT", "NGNKOBO"], "description": "The source currency for the quote" }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT", "GHSPESEWA"], "description": "The target currency for the quote" }, "transactionFeesInSourceCurrency": { "type": "number", "format": "number", "example": 13.23, "description": "The transaction fees in the source currency in its lowest denomination" }, "transactionFeesInTargetCurrency": { "type": "string", "format": "string", "example": "3750.00", "description": "The transaction fees in the target currency in its lowest denomination" }, "amountInSourceCurrency": { "type": "number", "format": "number", "example": 1499, "description": "The amount in the source currency in its lowest denomination" }, "amountInTargetCurrency": { "type": "string", "format": "string", "example": "50000.00", "description": "The amount in the target currency in its lowest denomination" }, "paymentMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING"] }, "expiry": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "isValid": { "type": "boolean", "format": "boolean", "example": true }, "invoice": { "type": "string", "format": "string", "example": "lntbs36020n1pnehfzcpp5zc8g9tfpwnmaevh62ak2vu6zjqyt5cpph3gjm4zfyqz9srjjdsaqdz5296k7ar98gsy6ctkvys9qcteyqmnyenr8yunswfdvyer2v3dx33kxe3dvymnsefdv5mnjcm9x5mrydm9vccqcqzpuxqzfvsp5utd7hdfmjp7vw3lc6hal8psqruwcnu89hxfukyzugxh40jhv8xcq9qxpqysgq2lry5dgzu2g04s74tpvctwe37rkprs3k579jw6yt7ncrsg62p29yalw8gf5fawfvpydqv4jjve0nsysfhsxa35dtwug9e6gzxkq0h5gp636wc3", "description": "The lightning invoice to pay for the quote" }, "hash": { "type": "string", "format": "string", "example": "189727ef2e0f35921af7858b96e27cbad960b0ec2bb2a4ab73b6a231f9ce8727", "description": "The payment hash for the lightning invoice attached to the quote" }, "customerReference": { "type": "string", "format": "string", "example": "order-1234567890", "description": "Your unique identifier for the quote" }, "totalAmountInSourceCurrency": { "type": "number", "format": "number", "example": 1499, "description": "The total amount in the source currency in its lowest denomination" }, "customerInternalFee": { "type": "number", "format": "number", "description": "An internal fee you can set to charge the customer. This fee is in the source currency in its lowest denomination", "example": 0 }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z", "description": "The date and time the quote was created" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z", "description": "The date and time the quote was last updated" }, "bankName": { "type": "string", "format": "string", "example": "WEMA BANK", "description": "Bank name for NGN bank transfer (when paymentMethod is BANKTRANSFER)" }, "ngnBankAccountNumber": { "type": "string", "format": "string", "example": "7824655568", "description": "Bank account number for NGN payment (when paymentMethod is BANKTRANSFER)" }, "ngnAccountName": { "type": "string", "format": "string", "example": "Mava Digital Solutions Limited", "description": "Account name for NGN payment (when paymentMethod is BANKTRANSFER)" }, "ngnBankCode": { "type": "string", "format": "string", "example": "000027", "description": "NIP bank code for NGN payment (when paymentMethod is BANKTRANSFER)" }, "orderId": { "type": "string", "format": "string", "example": "43477-4306", "description": "Unique order identifier for tracking" }, "estimatedRoutingFee": { "type": "number", "format": "number", "example": 0, "description": "Estimated routing fee for Lightning Network payments in satoshis" } } }, "CreateQuote": { "type": "object", "properties": { "amount": { "type": "number", "format": "number", "example": 1000, "description": "The amount in the target currency in its lowest denomination. e.g '500000' for 5000.00 NGN" }, "sourceCurrency": { "type": "string", "format": "string", "enum": ["BTCSAT", "NGNKOBO"], "default": "BTCSAT", "description": "The source currency for the quote" }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT", "GHSPESEWA", "BTCSAT"], "default": "NGNKOBO", "description": "The local currency to convert the source currency to" }, "paymentMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING", "BANKTRANSFER"], "default": "LIGHTNING", "description": "The payment method for the quote" }, "paymentCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "BTCSAT", "KESCENT", "ZARCENT", "GHSPESEWA"], "description": "Currency the amount is denominated in. Must be either sourceCurrency or targetCurrency. Determines what the 'amount' field represents. Example: if buying BTC with NGN and paymentCurrency is 'NGNKOBO', amount is in Naira; if 'BTCSAT', amount is in Bitcoin." }, "customerReference": { "type": "string", "format": "string", "example": "order-1234567890", "description": "Your unique identifier for the quote" }, "autopayout": { "type": "boolean", "format": "boolean", "example": false, "default": false }, "beneficiary": { "type": "object", "oneOf": [ { "title": "NGN Beneficiary", "type": "object", "properties": { "bankAccountNumber": { "type": "string", "example": "0149203789", "description": "The bank account number of the beneficiary" }, "bankAccountName": { "type": "string", "example": "olaolu olajide", "description": "The name of the beneficiary" }, "bankCode": { "type": "string", "example": "000013", "description": "The bank code of the beneficiary" }, "bankName": { "type": "string", "example": "GTBANK PLC", "description": "The name of the bank of the beneficiary" } }, "required": [ "bankAccountNumber", "bankAccountName", "bankCode", "bankName" ] }, { "title": "KES Beneficiary", "type": "object", "properties": { "identifierType": { "type": "string", "enum": ["paytophone", "paytobill", "paytotill"], "example": "paytophone", "description": "The type of identifier to use for the beneficiary" }, "identifiers": { "type": "object", "properties": { "phoneNumber": { "type": "string", "example": "+254796980788", "description": "The phone number of the beneficiary if the identifierType is paytophone" }, "network": { "type": "string", "enum": ["mpesa", "airtel"], "example": "mpesa", "description": "The target mobile money network. Required when identifierType is paytophone." }, "paybillNumber": { "type": "string", "example": "4141031", "description": "The paybill number of the beneficiary if the identifierType is paytobill" }, "accountNumber": { "type": "string", "example": "vlad", "description": "The account number of the beneficiary if the identifierType is paytobill" }, "tillNumber": { "type": "string", "example": "796980711", "description": "The till number of the beneficiary if the identifierType is paytotill" }, "accountName": { "type": "string", "example": "John Doe", "description": "The account name of the beneficiary if the identifierType is paytobill or paytotill" } } } }, "required": ["identifierType", "identifiers"] }, { "title": "GHS Beneficiary", "type": "object", "properties": { "identifierType": { "type": "string", "enum": ["MTN"], "example": "MTN", "description": "The type of mobile network to use for the beneficiary" }, "identifiers": { "type": "object", "properties": { "phoneNumber": { "type": "string", "example": "+233796980788", "description": "The phone number of the beneficiary if the identifierType is MTN" }, "accountName": { "type": "string", "example": "Mensah Kwame", "description": "The account name of the beneficiary if the identifierType is MTN" } } } }, "required": ["identifierType", "identifiers"] }, { "title": "ZAR Beneficiary", "type": "object", "properties": { "name": { "type": "string", "example": "Ricki Allardice", "description": "The name of the beneficiary" }, "bankName": { "type": "string", "example": "CAPITEC BANK", "description": "The name of the bank of the beneficiary" }, "bankAccountNumber": { "type": "string", "example": "1352906218", "description": "The bank account number of the beneficiary" } }, "required": ["name", "bankName", "bankAccountNumber"] }, { "title": "BTC Beneficiary", "type": "object", "properties": { "lnInvoice": { "type": "string", "example": "lnbc2082380n1p5fhytmpp5ujnmhfhle6qpc22x0ghyh0w0geufk2qscpuegr0wu4yrpscexv8qdq8g36kuuccqzzsxqzfvsp5ely8sp5cgatch8e02uujamy39rwmjdd5pgmakptsq74u6redpnzq9qxpqysgq2lry5dgzu2g04s74tpvctwe37rkprs3k579jw6yt7ncrsg62p29yalw8gf5fawfvpydqv4jjve0nsysfhsxa35dtwug9e6gzxkq0h5gp636wc3", "description": "Lightning Network invoice for Bitcoin payout (required when autopayout is true)" }, "lnAddress": { "type": "string", "example": "user@getalby.com", "description": "Lightning address for Bitcoin payout (alternative to lnInvoice)" }, "onChainAddress": { "type": "string", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "description": "Bitcoin on-chain address for payout (alternative to lnInvoice)" } } } ] } }, "required": [ "amount", "sourceCurrency", "targetCurrency", "paymentMethod", "paymentCurrency" ] }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b", "description": "The unique identifier for the wallet" }, "accountId": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b", "description": "The unique identifier for the account related to the wallet" }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES", "BTC", "ZAR", "GHS"] }, "balance": { "type": "number", "format": "number", "example": 1000, "description": "The balance of the wallet in its lowest denomination" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b", "description": "The unique identifier for the transaction" }, "walletId": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b", "description": "The unique identifier for the wallet" }, "ref": { "type": "string", "format": "string", "example": "99eeff854ffd345fffs67890", "description": "The reference for the transaction" }, "hash": { "type": "string", "format": "string", "example": "189727ef2e0f35921af7858b96e27cbad960b0ec2bb2a4ab73b6a231f9ce8727", "description": "The payment hash for the lightning invoice attached to the quote related to the transaction" }, "amount": { "type": "number", "format": "number", "example": 1000, "description": "The amount of the transaction in its lowest denomination" }, "fees": { "type": "number", "format": "number", "example": 0, "description": "The fees for the transaction in its lowest denomination" }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES", "BTC", "ZAR", "GHS"], "description": "The currency of the transaction" }, "type": { "type": "string", "format": "string", "enum": ["WITHDRAWAL", "DEPOSIT"], "description": "The type of the transaction" }, "status": { "type": "string", "format": "string", "enum": ["SUCCESS", "PENDING", "FAILED"], "description": "The status of the transaction" }, "autopayout": { "type": "boolean", "format": "boolean", "example": true, "description": "Whether the transaction is an instant payout" }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z", "description": "The date and time the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z", "description": "The date and time the transaction was last updated" }, "metadata": { "$ref": "#/components/schemas/TransactionMetadata" } } }, "TransactionMetadata": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "orderId": { "type": "string", "format": "string", "example": "99854-2345" }, "bankCode": { "type": "string", "format": "string", "example": "090267" }, "bankAccountName": { "type": "string", "format": "string", "example": "Satoshi Nakamoto" }, "bankAccountNumber": { "type": "string", "format": "string", "example": "0123456789" }, "customerInternalFee": { "type": "number", "format": "number", "example": 0 }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" } } }, "Webhook": { "type": "object", "properties": { "url": { "type": "string", "format": "string", "example": "https://webhook.site/12345678-1234-1234-1234-123456789012" }, "secret": { "type": "string", "format": "string", "example": "secret" }, "event": { "type": "object", "properties": { "event": { "type": "string", "format": "string", "example": "ping" }, "data": { "type": "object", "properties": { "message": { "type": "string", "format": "string", "example": "This is a test webhook event" }, "timestamp": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" } } } } } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "name": { "type": "string", "format": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "johndoe@email.com" }, "phone": { "type": "string", "format": "string", "example": "+2348123456789" }, "businessName": { "type": "string", "format": "string", "example": "John Doe Enterprises" }, "emailVerified": { "type": "boolean", "format": "boolean", "example": true }, "kycInfo": { "type": "object", "properties": { "address": { "type": "string", "format": "string", "example": "3 Opebi Road, Ikeja, Lagos" }, "phone": { "type": "string", "format": "string", "example": "+2348123456789" }, "nationality": { "type": "string", "format": "string", "example": "Nigeria" }, "businessName": { "type": "string", "format": "string", "example": "John Doe Enterprises" }, "status": { "type": "string", "format": "string", "enum": ["PENDING", "APPROVED", "REJECTED"] } } }, "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "type": { "type": "string", "format": "string", "enum": ["INDIVIDUAL", "BUSINESS", "ADMIN"] }, "status": { "type": "string", "format": "string", "enum": ["ACTIVE", "INACTIVE"] }, "walletDetails": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES", "BTC", "USD"] }, "balance": { "type": "number", "format": "number", "example": "10000000" }, "bankAccount": { "$ref": "#/components/schemas/BankAccount" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "ownerId": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "apiKey": { "type": "string", "format": "string", "example": "d1614a76411198a743199f307e5b" }, "totalSatsExchanged": { "type": "number", "format": "number", "example": 1000 }, "webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "url": { "type": "string", "format": "string", "example": "https://webhook.site/12345678-1234-1234-1234-123456789012" }, "secret": { "type": "string", "format": "string", "example": "secret" }, "isActive": { "type": "boolean", "format": "boolean", "example": true } } }, "settings": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "autopayout": { "type": "boolean", "format": "boolean", "example": true }, "language": { "type": "string", "format": "string", "enum": ["EN", "FR", "ES"] }, "notification": { "type": "object", "properties": { "email": { "type": "boolean", "format": "boolean", "example": true }, "sms": { "type": "boolean", "format": "boolean", "example": true } } } } } } } } }, "Error": { "required": ["error", "message"], "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "error" }, "message": { "type": "string" } } }, "CreatePaymentLink": { "type": "object", "required": [ "name", "settlementCurrency", "settlementMethod", "paymentCurrency", "paymentMethods", "beneficiary", "amount" ], "properties": { "name": { "type": "string", "description": "Name or title for the payment link", "example": "Bitcoin Purchase" }, "description": { "type": "string", "description": "Description of the payment", "example": "On-chain Bitcoin payment" }, "type": { "type": "string", "enum": ["One_Time"], "description": "Type of payment link", "example": "One_Time" }, "addFeeToTotalCost": { "type": "boolean", "description": "Whether to add transaction fees to the total cost", "example": false }, "settlementCurrency": { "type": "string", "enum": ["NGN, ZAR, BTC"], "description": "The currency to settle in", "example": "NGN, ZAR, BTC" }, "settlementMethod": { "type": "string", "enum": ["ONCHAIN", "LIGHTNING"], "description": "Settlement method for Bitcoin. ONCHAIN for on-chain transactions, LIGHTNING for Lightning Network", "example": "ONCHAIN" }, "speed": { "type": "string", "enum": ["slow", "medium", "fast"], "description": "Network fee priority for on-chain transactions. Required when settlementMethod is ONCHAIN", "example": "medium" }, "paymentCurrency": { "type": "string", "enum": ["NGN, ZAR, BTC"], "description": "The currency the user pays in", "example": "NGN, ZAR, BTC" }, "paymentMethods": { "type": "array", "items": { "type": "string", "enum": ["BANKTRANSFER, LIGHTNING"] }, "description": "Accepted payment methods. Currently only BANKTRANSFER and LIGHTNING are supported e.g for ZAR payment link, you can specify two payment methods [BANKTRANSFER, LIGHTNING]", "example": ["BANKTRANSFER, LIGHTNING"] }, "beneficiary": { "type": "object", "description": "Beneficiary details for settlement. Structure depends on settlement type: Bitcoin (on-chain or Lightning), NGN bank account, or ZAR bank account.", "oneOf": [ { "title": "Bitcoin Beneficiary", "type": "object", "description": "For BTC settlement via on-chain or Lightning", "properties": { "onChainAddress": { "type": "string", "description": "Bitcoin on-chain address for settlement (required for ONCHAIN settlementMethod)", "example": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5" }, "lnAddress": { "type": "string", "description": "Lightning address for settlement (for LIGHTNING settlementMethod)", "example": "user@getalby.com" }, "lnInvoice": { "type": "string", "description": "Lightning invoice for settlement (for LIGHTNING settlementMethod)", "example": "lnbc..." } } }, { "title": "NGN Bank Beneficiary", "type": "object", "description": "For NGN settlement to a Nigerian bank account", "properties": { "bankAccountNumber": { "type": "string", "description": "Nigerian bank account number", "example": "0149203789" }, "bankAccountName": { "type": "string", "description": "Account holder name", "example": "John Doe" }, "bankCode": { "type": "string", "description": "Nigerian bank code (NIP code)", "example": "000013" }, "bankName": { "type": "string", "description": "Name of the bank", "example": "GTBANK PLC" } }, "required": [ "bankAccountNumber", "bankAccountName", "bankCode", "bankName" ] }, { "title": "ZAR Bank Beneficiary", "type": "object", "description": "For ZAR settlement to a South African bank account", "properties": { "bankAccountNumber": { "type": "string", "description": "South African bank account number", "example": "12077363256" }, "bankName": { "type": "string", "description": "Name of the bank", "example": "FNB" }, "name": { "type": "string", "description": "Account holder name", "example": "John Doe" } }, "required": ["bankAccountNumber", "bankName", "name"] } ] }, "amount": { "type": "number", "description": "Amount in the lowest denomination of the payment currency (e.g., kobo for NGN)", "example": 800000 }, "callbackUrl": { "type": "string", "format": "uri", "description": "Redirect URL where users are sent after payment completion", "example": "https://your-app.com/payment-success" } } }, "PaymentLinkResponse": { "type": "object", "properties": { "paymentLink": { "type": "string", "format": "uri", "description": "The hosted payment page URL", "example": "https://checkout.staging.mavapay.co/9d1c20db-c46b-4a15-8233-1bb999e38195" }, "paymentRef": { "type": "string", "format": "uuid", "description": "Unique reference for the payment link", "example": "9d1c20db-c46b-4a15-8233-1bb999e38195" } } }, "PaymentLinkDetails": { "type": "object", "properties": { "paymentLinkDetails": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Payment link ID", "example": "9f8bf7da-f1d8-4c78-8f93-28eebe17c35e" }, "name": { "type": "string", "description": "Name of the payment link", "example": "Bitcoin Purchase" }, "description": { "type": "string", "description": "Description of the payment", "example": "On-chain Bitcoin payment" }, "callbackUrl": { "type": "string", "format": "uri", "description": "Redirect URL where users are sent after payment completion", "example": "https://your-app.com/payment-success" }, "settlementCurrency": { "type": "string", "description": "Settlement currency", "example": "BTC" }, "paymentLinkOrderId": { "type": "string", "format": "uuid", "description": "Associated order ID", "example": "99366bb2-788f-4556-86db-d5063232a50a" }, "paymentMethods": { "type": "array", "items": { "type": "string" }, "example": ["BANKTRANSFER"] }, "account": { "type": "object", "properties": { "name": { "type": "string", "description": "Business name", "example": "Your Business Name" }, "logo": { "type": "string", "description": "Business logo URL", "example": "" } } }, "BANKTRANSFER": { "type": "object", "description": "Bank transfer payment details", "properties": { "ngnAccountName": { "type": "string", "description": "Account name for bank transfer", "example": "Mava Digital Solutions Limited" }, "ngnBankName": { "type": "string", "description": "Bank name", "example": "GLOBUS BANK" }, "ngnBankAccountNumber": { "type": "string", "description": "Bank account number", "example": "3242569160" }, "amount": { "type": "number", "description": "Amount in lowest denomination", "example": 800000 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Expiration time for the payment", "example": "2025-11-20T20:47:41.528Z" }, "targetAmount": { "type": "number", "description": "Target amount in the settlement currency (lowest denomination)", "example": 6034 } } } } } } }, "PaymentLinkOrderDetails": { "type": "object", "description": "Complete payment link details including associated orders", "properties": { "id": { "type": "string", "format": "uuid", "description": "Payment link ID", "example": "7e644e02-e652-42d8-8857-e8ae46bccd59" }, "name": { "type": "string", "description": "Name of the payment link", "example": "Small payment for Solomon" }, "description": { "type": "string", "description": "Description of the payment", "example": "Small Payment for Demo Purposes" }, "type": { "type": "string", "enum": ["ONE_TIME", "RECURRING"], "description": "Type of payment link", "example": "ONE_TIME" }, "amount": { "type": "string", "description": "Amount in lowest denomination of the payment currency", "example": "2000000" }, "fee": { "type": "string", "nullable": true, "description": "Fee amount if applicable", "example": null }, "addFeeToTotalCost": { "type": "boolean", "description": "Whether fees are added to total cost", "example": false }, "settlementCurrency": { "type": "string", "description": "Currency for settlement", "example": "BTC" }, "settlementMethod": { "type": "string", "enum": ["ONCHAIN", "LIGHTNING"], "description": "Settlement method", "example": "ONCHAIN" }, "speed": { "type": "string", "enum": ["slow", "medium", "fast"], "description": "Network fee priority for on-chain transactions", "example": "medium" }, "paymentCurrency": { "type": "string", "description": "Currency the user pays in", "example": "NGN" }, "paymentMethods": { "type": "array", "items": { "type": "string" }, "description": "Accepted payment methods", "example": ["BANKTRANSFER"] }, "callbackUrl": { "type": "string", "format": "uri", "description": "Redirect URL where users are sent after payment completion", "example": "https://your-app.com/payment-success" }, "channel": { "type": "string", "description": "Channel through which payment link was created", "example": "API" }, "status": { "type": "string", "enum": ["ACTIVE", "INACTIVE", "EXPIRED"], "description": "Payment link status", "example": "ACTIVE" }, "accountId": { "type": "string", "format": "uuid", "description": "Account ID of the payment link owner", "example": "1a0f79fb-0f3e-4b5b-98f1-1e14324ca62e" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiration time of the payment link", "example": null }, "invoice": { "type": "string", "nullable": true, "description": "Lightning invoice if applicable", "example": null }, "companyLogo": { "type": "string", "nullable": true, "description": "Company logo URL", "example": null }, "beneficiaryId": { "type": "string", "description": "Beneficiary identifier (Bitcoin address or Lightning address)", "example": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5" }, "createdAt": { "type": "string", "format": "date-time", "description": "Payment link creation time", "example": "2026-01-09T12:36:09.582Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Payment link last update time", "example": "2026-01-09T12:36:09.582Z" }, "orders": { "type": "array", "description": "List of orders associated with this payment link. A new order is created when a previous order expires.", "items": { "$ref": "#/components/schemas/PaymentLinkOrder" } } } }, "PaymentLinkOrder": { "type": "object", "description": "An order associated with a payment link", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique order identifier", "example": "eb1377a8-5afd-4888-a702-d510d070466b" }, "status": { "type": "string", "enum": ["PENDING", "PAID", "EXPIRED", "FAILED"], "description": "Order status", "example": "PENDING" }, "orderId": { "type": "string", "description": "Order ID for tracking and simulation", "example": "49508-6205" }, "paymentLinkId": { "type": "string", "format": "uuid", "description": "Associated payment link ID", "example": "7e644e02-e652-42d8-8857-e8ae46bccd59" }, "paymentMethod": { "type": "string", "description": "Payment method used", "example": "BANKTRANSFER" }, "createdAt": { "type": "string", "format": "date-time", "description": "Order creation time", "example": "2026-01-09T12:36:25.924Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Order last update time", "example": "2026-01-09T12:47:10.254Z" } } }, "Signup": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "johndoe@email.com" }, "password": { "type": "string", "format": "string", "example": "password" }, "name": { "type": "string", "format": "string", "example": "John Doe" }, "businessName": { "type": "string", "format": "string", "example": "John Doe Enterprises" }, "phone": { "type": "string", "format": "string", "example": "+2348123456789" }, "isDeveloper": { "type": "boolean", "example": true }, "country": { "type": "string", "example": "Nigeria" }, "businessCategory": { "type": "string", "example": "Technology" }, "businessType": { "type": "string", "example": "Software" }, "acceptedTerms": { "type": "boolean", "example": true } } }, "TransactionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "10cda92f-db32-4f69-ae30-af32a0055caf" }, "ref": { "type": "string", "example": "142a39e0bb85c45b06a9657f56156" }, "hash": { "type": "string", "example": "89d7fd6571c8bdf4242091953553c26228dd5b7679729d20aaf2cc84f000d1bc" }, "amount": { "type": "number", "example": 10000 }, "fees": { "type": "number", "example": 0 }, "currency": { "type": "string", "enum": ["NGN", "KES", "BTC", "ZAR"] }, "type": { "type": "string", "enum": ["WITHDRAWAL", "DEPOSIT"] }, "status": { "type": "string", "enum": ["SUCCESS", "PENDING", "FAILED"] }, "autopayout": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-23T10:46:01.050Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-23T10:46:04.590Z" }, "metadata": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "f2bf7bf8-9fe9-4afd-9ebb-cf3abae8cb19" }, "merchantId": { "type": "string", "format": "uuid", "example": "f77986d6-75df-4979-85a9-8acedcfca392" }, "merchantName": { "type": "string", "example": "Ricki Allardice" }, "bankName": { "type": "string", "example": "CAPITEC BANK" }, "bankAccountNumber": { "type": "string", "example": "1352906218" }, "reference": { "type": "string", "example": "2bNkqVDLER7n65O7RrcV" }, "customerInternalFee": { "type": "number", "example": 0 }, "order": { "type": "object", "properties": { "id": { "type": "string", "example": "22723-5636" }, "settledQuoteId": { "type": "string", "format": "uuid", "example": "e3d3cb1c-3206-40bb-81a9-8dfd9d69a853" }, "amount": { "type": "number", "example": 10000 }, "currency": { "type": "string", "enum": ["NGN", "KES", "ZAR"] }, "paymentMethod": { "type": "string", "enum": ["LIGHTNING"] }, "status": { "type": "string", "enum": ["PAID", "PENDING", "EXPIRED", "FAILED"] }, "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "exchangeRate": { "type": "number", "example": 1874805.7499999998 }, "usdToTargetCurrencyRate": { "type": "number", "example": 18.4977 }, "paymentBtcDetail": { "type": "string" }, "paymentMethod": { "type": "string", "enum": ["LIGHTNING"] }, "totalAmount": { "type": "number", "example": 6474 }, "equivalentAmount": { "type": "number", "example": 10000 }, "expiry": { "type": "string", "format": "date-time" }, "sourceCurrency": { "type": "string", "enum": ["BTCSAT"] }, "targetCurrency": { "type": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT"] }, "paymentCurrency": { "type": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT"] }, "customerInternalFee": { "type": "number", "example": 0 } } } } } } } } }, "PriceTicker": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "ask": { "type": "number", "description": "Ask price (selling price)", "example": 1475.42 }, "bid": { "type": "number", "description": "Bid price (buying price)", "example": 1455.42 }, "timestamp": { "type": "number", "description": "Unix timestamp in milliseconds", "example": 1767896752409 }, "meta": { "type": "object", "properties": { "pair": { "type": "string", "description": "Currency pair in uppercase", "example": "USDNGN" }, "payoutMethods": { "type": "array", "items": { "type": "string" }, "example": ["BANKTRANSFER"] }, "collectionMethods": { "type": "array", "items": { "type": "string" }, "example": ["LIGHTNING"] }, "unitPricePerUsd": { "type": "object", "description": "Exchange rates per USD" }, "unitPricePerSat": { "type": "object", "description": "Exchange rates per satoshi" }, "fees": { "type": "object", "description": "Fee information for ask and bid" } } } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } }, "tags": [ { "name": "Price", "description": "Price related endpoints" }, { "name": "Payment Link", "description": "Payment Link endpoints for creating and managing hosted payment pages" } ] }