{ "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.mavapay.co/api", "description": "Staging server" }, { "url": "https://api.mavapay.co/api", "description": "Live server" } ], "security": [ { "ApiKeyAuth": [], "bearerAuth": [] } ], "paths": { "/price": { "get": { "security": [], "tags": ["Price"], "operationId": "getPrice", "summary": "Get current market price", "description": "Returns the market price per dollar for a given currency", "parameters": [ { "name": "currency", "in": "query", "description": "The currency to get the price for", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Price response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } }, "400": { "description": "Unexpected error", "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 the bank account details for a given currency", "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)", "schema": { "type": "string", "enum": ["NGN", "KES", "BTC", "USD"] }, "required": false } ], "responses": { "200": { "description": "Bank account response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "success" }, "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", "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": "success" }, "data": { "$ref": "#/components/schemas/BankAccount" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bank/bankcode": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Bank Account"], "operationId": "getBankCode", "summary": "Get bank code", "description": "Returns all bank codes for a given currency. This endpoint is currently limited to Nigeria(NGN) only", "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": "success" }, "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": "success" }, "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" } } }, "required": true }, "responses": { "200": { "description": "Quote response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/Quote" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quote/accept": { "get": { "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": ["Quote"], "operationId": "acceptQuote", "summary": "Accept a quote", "description": "Accept a quote by id", "parameters": [ { "name": "id", "in": "query", "description": "The quote ID to accept", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "autopayout", "in": "query", "description": "Whether to automatically pay out the customer's bank account once the quote has been paid", "schema": { "type": "boolean", "format": "boolean" }, "required": false }, { "name": "bankAccountNumber", "in": "query", "description": "If autopayout is true, the customer bank account number to pay out to", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "bankCode", "in": "query", "description": "If autopayout is true, the customer bank code to pay out to", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "bankAccountName", "in": "query", "description": "If autopayout is true, the customer bank account name to pay out to", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "memo", "in": "query", "description": "A memo or short note to attach to the quote and invoice", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "descriptionHash", "in": "query", "description": "A description hash to attach to the quote and invoice if using lnurl", "schema": { "type": "string", "format": "string" }, "required": false }, { "name": "customerInternalFee", "in": "query", "description": "An extra fee to charge the customer that is meant for the entity/business. This must be in SATS and not FIAT", "schema": { "type": "number", "format": "number" }, "required": false } ], "responses": { "200": { "description": "Quote response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/AcceptQuoteResponse" } } } } } }, "400": { "description": "Unexpected error", "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": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } } } }, "400": { "description": "Unexpected error", "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", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "number", "example": 1000 }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES", "BTC", "USD"] }, "bankAccountNumber": { "type": "string", "format": "string", "example": "0123456789" }, "walletId": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" } } } } }, "required": true }, "responses": { "200": { "description": "Withdraw response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "success" }, "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": "success" }, "data": { "type": "object", "$ref": "#/components/schemas/Transaction" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Price": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "success" }, "data": { "type": "object", "properties": { "currency": { "type": "string", "enum": ["NGN", "KES"] }, "timeStamp": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "btcPriceInUnitCurrency": { "type": "number", "format": "number", "example": 9000000.23 }, "unitPricePerSat": { "type": "object", "properties": { "amount": { "type": "number", "format": "number", "example": 0.334561234 }, "currencyUnit": { "type": "string", "enum": ["NGNSAT", "KESSAT"] } } }, "unitPricePerUsd": { "type": "object", "properties": { "amount": { "type": "number", "format": "number", "example": 1500.65 }, "currencyUnit": { "type": "string", "enum": ["NGNUSD", "KESUSD"] } } } } } } }, "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", "KES"] }, "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" }, "quote": { "$ref": "#/components/schemas/Quote" } } }, "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" }, "quote": { "$ref": "#/components/schemas/Quote" } } }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "exchangeRate": { "type": "number", "format": "number", "example": 5000000.23 }, "usdToTargetCurrencyRate": { "type": "number", "format": "number", "example": 1500.65 }, "sourceCurrency": { "type": "string", "format": "string", "enum": ["BTCSAT", "NGNKOBO", "KESCENT"] }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT"] }, "transactionFeesInSourceCurrency": { "type": "number", "format": "number", "example": 11163 }, "transactionFeesInTargetCurrency": { "type": "string", "format": "string", "example": "3750.00" }, "amountInSourceCurrency": { "type": "number", "format": "number", "example": 1499589 }, "amountInTargetCurrency": { "type": "string", "format": "string", "example": "50000.00" }, "paymentMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING", "ONCHAIN", "USDT"] }, "expiry": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "isValid": { "type": "boolean", "format": "boolean", "example": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" } } }, "CreateQuote": { "type": "object", "properties": { "amount": { "type": "number", "format": "number", "example": 1000 }, "sourceCurrency": { "type": "string", "format": "string", "enum": ["BTC", "NGN", "KES"] }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGN", "BTC", "KES"] }, "paymentMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING", "ONCHAIN", "USDT"] }, "paymentCurrency": { "type": "string", "format": "string", "enum": ["BTC", "NGN", "KES"] }, "implicitFees": { "type": "boolean", "format": "boolean", "example": false } } }, "AcceptQuoteResponse": { "type": "object", "properties": { "orderId": { "type": "string", "format": "string", "example": "99854-2345" }, "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" }, "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "btcToTargetCurrencyRate": { "type": "number", "format": "number", "example": 5000000.23 }, "usdToTargetCurrencyRate": { "type": "number", "format": "number", "example": 1500.65 }, "totalSatAmount": { "type": "number", "format": "number", "example": 1499589 }, "finalPayableAmountInTargetCurrency": { "type": "string", "format": "string", "example": "50000.00" }, "transactionFeesInSourceCurrency": { "type": "number", "format": "number", "example": 11163 }, "transactionFeesInTargetCurrency": { "type": "string", "format": "string", "example": "3750.00" }, "customerInternalFee": { "type": "number", "format": "number", "example": 1000 }, "sourceCurrency": { "type": "string", "format": "string", "enum": ["BTCSAT", "NGNKOBO", "KESCENT"] }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT"] }, "expiresAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" } } } } }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "string", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "accountId": { "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": 1000 } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "walletId": { "type": "string", "format": "uuid", "example": "d1614a76-9c7f-4111-98a7-43199f307e5b" }, "ref": { "type": "string", "format": "string", "example": "99eeff854ffd345fffs67890" }, "hash": { "type": "string", "format": "string", "example": "99eeff854ffd345fffs67890" }, "amount": { "type": "number", "format": "number", "example": 1000 }, "fees": { "type": "number", "format": "number", "example": 0 }, "currency": { "type": "string", "format": "string", "enum": ["NGN", "KES", "BTC", "USD"] }, "type": { "type": "string", "format": "string", "enum": ["WITHDRAWAL", "DEPOSIT", "TRANSFER"] }, "status": { "type": "string", "format": "string", "enum": ["SUCCESS", "PENDING", "FAILED"] }, "autopayout": { "type": "boolean", "format": "boolean", "example": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-07-01T12:00:00Z" }, "transactionMetadata": { "$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" }, "eProviderRef": { "type": "string", "format": "string", "example": "9985434567890" }, "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" } } }, "Error": { "required": ["error", "message"], "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "error" }, "message": { "type": "string" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } }, "tags": [ { "name": "Price", "description": "Price related endpoints" } ] }