{ "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": { "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 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": "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. 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": "success" }, "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": "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" } } } } } } }, "/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" } } } } } } }, "/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": "success" }, "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": "success" }, "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": "success" }, "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", "responses": { "200": { "description": "Transaction response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "success" }, "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": "success" }, "data": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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": "success" }, "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" } } } } } } }, "/user/apikey": { "get": { "security": [ { "bearerAuth": [] } ], "tags": ["User"], "operationId": "getUserApiKey", "summary": "Get user API key", "description": "Returns the user's API key. This generates a new API key even if the user already has one", "responses": { "200": { "description": "API key response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "format": "string", "example": "success" }, "data": { "type": "object", "properties": { "apiKey": { "type": "string", "example": "addedednefendfdcd" } } } } } } } } } } } }, "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"] }, "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": 5000000.23, "description": "The exchange rate of source currency to target currency for the quote. e.g 1 BTC = 5000000.23 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", "KESCENT", "ZARCENT"], "description": "The source currency for the quote" }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT"], "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" }, "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" } } }, "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"], "default": "BTCSAT", "description": "The source currency for the quote" }, "targetCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT"], "default": "NGNKOBO", "description": "The local currency to convert the source currency to" }, "paymentMethod": { "type": "string", "format": "string", "enum": ["LIGHTNING"], "default": "LIGHTNING", "description": "The payment method for the quote" }, "paymentCurrency": { "type": "string", "format": "string", "enum": ["NGNKOBO", "KESCENT", "ZARCENT"] }, "autopayout": { "type": "boolean", "format": "boolean", "example": true, "default": true }, "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"], "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" }, "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" } } } }, "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"] } ] } }, "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"] }, "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"], "description": "The currency of the transaction" }, "type": { "type": "string", "format": "string", "enum": ["WITHDRAWAL", "DEPOSIT", "TRANSFER"], "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" } } }, "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" } } }, "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", "TRANSFER"] }, "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 } } } } } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } }, "tags": [ { "name": "Price", "description": "Price related endpoints" } ] }