{ "openapi": "3.0.0", "info": { "title": "NextPayday Borrower API", "description": "API documentation for the NextPayday Borrower Portal redesign. This API handles loan applications, repayments, settlement, and identity verification.", "contact": { "email": "admin@nextpayday.co" }, "version": "1.0.0" }, "servers": [ { "url": "/", "description": "Main API Server" } ], "paths": { "/api/v1/auth/admin/login": { "post": { "tags": [ "Authentication" ], "summary": "Admin Login", "operationId": "c505468b67b380270ff78263cec6a379", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "admin@nextpayday.co" }, "password": { "type": "string", "format": "password", "example": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful" }, "422": { "description": "Validation failed" } } } }, "/api/v1/auth/user/login": { "post": { "tags": [ "Authentication" ], "summary": "User Login", "operationId": "a7af956f4f58d68f08076c28e83453c7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@test.com" }, "password": { "type": "string", "format": "password", "example": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful" }, "422": { "description": "Validation failed" } } } }, "/api/v1/auth/initiate-signup": { "post": { "tags": [ "Authentication - Signup Funnel" ], "summary": "Step 1: Initiate Signup with Email and Phone", "description": "Sends email OTP to the provided email address.", "operationId": "2127c96beaaa0c248c627d3d41762201", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "phoneNumber" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phoneNumber": { "type": "string", "example": "08100000000" }, "referralCode": { "type": "string", "example": "NPD-4492" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email OTP sent; returns referenceId" } } } }, "/api/v1/auth/verify-otp": { "post": { "tags": [ "Authentication - Signup Funnel" ], "summary": "Step 2: Verify Signup Email OTP", "operationId": "e444b2fb8d3b729e4dae1f100fda00ea", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "otp", "referenceId" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" }, "otp": { "type": "string", "example": "123456" }, "referenceId": { "type": "string", "example": "req_xyz" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email OTP verified; returns signupToken" } } } }, "/api/v1/auth/update-profile": { "post": { "tags": [ "Authentication - Signup Funnel" ], "summary": "Step 3: Update Profile Details", "description": "Saves personal details. Email is already verified from step 2.", "operationId": "97a11ee196bf110a1b78515af534fadc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "signupToken", "firstName", "lastName", "dob", "stateOfOrigin", "lga", "address", "occupation" ], "properties": { "signupToken": { "type": "string" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "dob": { "type": "string", "format": "date", "example": "1995-01-01" }, "stateOfOrigin": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "address": { "type": "string", "example": "12 Example Street" }, "occupation": { "type": "string", "example": "Engineer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile saved" } } } }, "/api/v1/auth/verify-email-otp": { "post": { "tags": [ "Authentication - Signup Funnel" ], "summary": "Verify Email OTP (legacy)", "description": "Deprecated for signup funnel. Email OTP is verified via verify-otp at step 2.", "operationId": "93d9de1e0f1f7e01eaaf08067faa205a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "signupToken", "emailOtp" ], "properties": { "signupToken": { "type": "string" }, "emailOtp": { "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email verified" } } } }, "/api/v1/auth/create-password": { "post": { "tags": [ "Authentication - Signup Funnel" ], "summary": "Step 4: Create Password & Finalize", "description": "Creates the user account and returns an access token.", "operationId": "bb083a2b28aa98b1c434ded319a38e5a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "signupToken", "password" ], "properties": { "signupToken": { "type": "string" }, "password": { "type": "string", "format": "password" }, "fcm_token": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Signup complete; returns accessToken" } } } }, "/api/v1/auth/forgot-password": { "post": { "tags": [ "Authentication - Password Reset" ], "summary": "Forgot password — send email OTP", "description": "Sends a 6-digit OTP to the user email for password reset. OTP valid for 10 minutes.", "operationId": "660fb0d13f6e08ce7566dd67d5d46ec3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent to email" }, "422": { "description": "Validation failed (email not registered)" } } } }, "/api/v1/auth/reset-password": { "post": { "tags": [ "Authentication - Password Reset" ], "summary": "Reset password with email OTP", "description": "Verifies the OTP from forgot-password and sets a new password. Revokes all existing API tokens.", "operationId": "65cbf14b14b06024e247b4ef0e731848", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "otp", "newPassword" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" }, "otp": { "type": "string", "example": "123456" }, "newPassword": { "type": "string", "format": "password", "example": "newsecret123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successfully" }, "400": { "description": "Invalid or expired OTP" }, "404": { "description": "User not found" } } } }, "/api/v1/borrowers/transactions": { "get": { "tags": [ "Dashboard" ], "summary": "Get Wallet Transactions", "operationId": "a2a95d1b46d792fb65c404fbd8a78c73", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/requests": { "post": { "tags": [ "Loans" ], "summary": "Book a New Loan", "description": "Enforces verification steps before allowing a loan booking.", "operationId": "b9c0cf63cfc6dd2a88c1317a8adf602b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "duration_months", "loan_type", "employer_id", "loan_mandate_activation_id" ], "properties": { "amount": { "type": "number", "example": 100000 }, "duration_months": { "type": "integer", "example": 6 }, "loan_type": { "type": "string", "enum": [ "setoff", "capitalize" ] }, "employer_id": { "type": "integer" }, "loan_mandate_activation_id": { "type": "integer" }, "purpose": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Loan application successful" }, "403": { "description": "Verification steps incomplete" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/offer": { "get": { "tags": [ "Loans" ], "summary": "Get Available Loan Options", "description": "Returns a list of employers to determine available rates.", "operationId": "5e66ef7d79343ce7d701da776753c2a6", "responses": { "200": { "description": "List of employers" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/offer/details": { "post": { "tags": [ "Loans" ], "summary": "Calculate Loan Offer Details", "operationId": "87a5700511d6eaee47f097275dfd6fbd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "duration_months", "loan_type", "employer_id" ], "properties": { "amount": { "type": "number", "example": 100000 }, "duration_months": { "type": "integer", "example": 6 }, "loan_type": { "type": "string", "enum": [ "setoff", "capitalize" ] }, "employer_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Loan calculation details" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/mandate/activate": { "post": { "tags": [ "Loans" ], "summary": "Activate Repayment Mandate", "description": "Activates a Mono mandate for a loan.", "operationId": "52cfb8bd3bf17f157d3f5ceba3573da9", "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/pending": { "get": { "tags": [ "Loans" ], "summary": "Get User Pending Loans", "operationId": "658692be7aba28797920747bcae81534", "responses": { "200": { "description": "List of pending loans" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/archived": { "get": { "tags": [ "Loans" ], "summary": "Get User Archived (Paid) Loans", "operationId": "194802b0268556e6abcd15d8a9b19b3c", "responses": { "200": { "description": "List of paid loans" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/taken": { "get": { "tags": [ "Loans" ], "summary": "Get All User Loans (History)", "operationId": "1980cb2ddf7f66e907de59f1f6f097f6", "responses": { "200": { "description": "History of all loans taken by user" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/active-check": { "get": { "tags": [ "Loans" ], "summary": "Check if User has an Active Loan", "operationId": "83c8c63e12119a1ac9e9dd7e6a8a0b5f", "responses": { "200": { "description": "Active loan status and details" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/{reference}": { "get": { "tags": [ "Loans" ], "summary": "Get Specific Loan Details (Snapshot)", "description": "Returns a single loan by its reference, including the full repayment schedule. Ideal for the Loan Snapshot screen on mobile.", "operationId": "67af94cc0ddc348a26e10c28650be846", "parameters": [ { "name": "reference", "in": "path", "description": "The loan reference (e.g., LN-ABC123XYZ)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Loan details and repayment schedule" }, "404": { "description": "Loan not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/public/loans/{reference}/settlement": { "get": { "tags": [ "Public Loan Settlement" ], "summary": "Get a Public Settlement Quote", "description": "Retrieves the total amount payable to fully settle a loan, including penalties and interest.", "operationId": "1f0b9ac00a571d326d8d3ccf4aada24d", "parameters": [ { "name": "reference", "in": "path", "description": "Loan Reference (e.g. LN-123456)", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Optional user ID for security validation", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Settlement quote details" }, "404": { "description": "Loan not found" } } } }, "/api/v1/public/loans/settle": { "post": { "tags": [ "Public Loan Settlement" ], "summary": "Initialize Settlement Payment", "description": "Generates a Paystack authorization URL to pay for the loan settlement.", "operationId": "a8e3daed9b7bf0825a17a3e46a38d224", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "loan_reference" ], "properties": { "loan_reference": { "type": "string", "example": "LN-123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Paystack authorization URL and reference" }, "500": { "description": "Failed to initialize payment" } } } }, "/api/v1/loans/settle-with-wallet": { "post": { "tags": [ "Public Loan Settlement" ], "summary": "Settle a Loan Using Wallet Balance", "description": "manual settlement for all months through Virtual Account, or otherwise", "operationId": "8b3670c3d3b9854e3a77190c74a745c4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "loan_id" ], "properties": { "loan_id": { "description": "The ID of the loan to settle", "type": "integer", "example": 42 } }, "type": "object" } } } }, "responses": { "200": { "description": "Loan settled successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Loan settled successfully from wallet." }, "loan_reference": { "type": "string", "example": "LN-123456" }, "amount_paid": { "type": "number", "example": 50400 } }, "type": "object" } } } }, "422": { "description": "Insufficient wallet balance", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Insufficient wallet balance to settle this loan." }, "wallet_balance": { "type": "number", "example": 10000 }, "amount_required": { "type": "number", "example": 50400 } }, "type": "object" } } } }, "404": { "description": "Loan not found or already settled" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/loans/pay-installment-with-wallet": { "post": { "tags": [ "Public Loan Settlement" ], "summary": "Pay a Single Loan Installment Using Wallet Balance", "description": "Deducts one installment amount from the borrower's wallet and marks it as paid. Defaults to the next unpaid installment. If it is the last installment, the loan is automatically closed.", "operationId": "1b52200a0de31d24d3297cb41255c1b4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "loan_id" ], "properties": { "loan_id": { "description": "The ID of the loan", "type": "integer", "example": 42 } }, "type": "object" } } } }, "responses": { "200": { "description": "Installment paid successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Installment #2 paid successfully from wallet." }, "installment_number": { "type": "integer", "example": 2 }, "amount_paid": { "type": "number", "example": 25000 }, "loan_closed": { "type": "boolean", "example": false } }, "type": "object" } } } }, "422": { "description": "Insufficient wallet balance", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Insufficient wallet balance to pay this installment." }, "wallet_balance": { "type": "number", "example": 5000 }, "amount_required": { "type": "number", "example": 25000 } }, "type": "object" } } } }, "404": { "description": "Loan not found or no unpaid installments remaining" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/banks": { "get": { "tags": [ "Banks" ], "summary": "Get User Bank Accounts", "operationId": "0297d81f4bc942dde441f8164b8a60e9", "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Banks" ], "summary": "Add New Bank Account", "operationId": "10c303562a543db33d1e070243bc7984", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "bank_name": { "type": "string" }, "bank_code": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/banks/primary": { "put": { "tags": [ "Banks" ], "summary": "Set Primary Bank Account for Receptions", "operationId": "f25c44842535cfb11800bfeaa2332388", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "bank_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/banks/list": { "get": { "tags": [ "Banks" ], "summary": "Get List of Supported Banks", "description": "Fetches the list of commercial banks from Paystack.", "operationId": "b5dabdbe037a1ada46b19aa4e829239c", "responses": { "200": { "description": "List of banks" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/eligibility-check": { "get": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "Get Eligibility Check Progress (7 Steps)", "operationId": "21780e68a5b3b39098f80009b09d5128", "responses": { "200": { "description": "Steps with completed status" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/bank-statements/analyze-upload": { "post": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "Analyze a bank statement PDF (no MBS / no debit) — same AI step as after ticket PDF", "operationId": "286b2bc31a9895da992cfe9a33762735", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "PDF bank statement", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Analysis + credit persistence (same as complete flow)" }, "400": { "description": "AI returned non-success shape" }, "422": { "description": "Validation" }, "500": { "description": "AI service unreachable or error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/bank-statements/requests": { "get": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "List your bank statement requests (recover request_id)", "operationId": "5320229ec4fff43f0395fec354e59946", "parameters": [ { "name": "status", "in": "query", "description": "Optional filter: pending, completed, expired", "required": false, "schema": { "type": "string", "example": "pending" } } ], "responses": { "200": { "description": "List of requests" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "Initiate bank statement retrieval (SMS ticket flow)", "operationId": "bd3825d68499fd7c0cd55c3295c17c36", "requestBody": { "description": "No body. Statement period is the last 6 months (server-side). Callback URL from MY_BANKSTATEMENT_CALLBACK_URL.", "required": false, "content": { "application/json": { "schema": {} } } }, "responses": { "201": { "description": "Request created" }, "409": { "description": "Cooldown or duplicate pending request" }, "422": { "description": "Validation or bank not linked" }, "503": { "description": "Provider not configured" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/bank-statements/requests/{request_id}": { "get": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "Get one bank statement request by id", "operationId": "34ade552d89afa5bb2fc54079180705a", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request detail" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/bank-statements/requests/{request_id}/complete": { "post": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "Submit ticket and fetch bank statement PDF", "operationId": "16a4cf37e5dba75cdd727452b1f5486b", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ticket_number": { "type": "string", "example": "TCK-123456" }, "ticket_password": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Completed with optional analysis" }, "404": { "description": "Unknown request_id" }, "409": { "description": "Already completed" }, "410": { "description": "Expired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/dashboard": { "get": { "tags": [ "Dashboard" ], "summary": "Get Borrower Dashboard Summary", "description": "Returns the user's wallet balance, active loan, outstanding loan balance, and loan offer limits in a single call.", "operationId": "0000339e50f76ebc3966fd70137801f8", "responses": { "200": { "description": "Dashboard summary details" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/notifications": { "get": { "tags": [ "Profile" ], "summary": "Get User Notifications", "operationId": "fac557d2e9737e08e5715c890dcdb7d7", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/verify/stage-two": { "post": { "tags": [ "Verification - Step 2 - Identity" ], "summary": "Stage 2 — BVN / virtual account / Direct Debit (single endpoint)", "description": "Pass booleans: false = run that substage, true = skip. Use camelCase or snake_case keys. When bvnVerified is false, BVN fields are required and the server chains virtual account + DD URL. FE primary field: redirect_url.", "operationId": "6a7e06aa63a60dfa3d2cb3d339358bf1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "bvnVerified", "virtualAccountVerified", "accountLinkingVerified" ], "properties": { "bvnVerified": { "description": "true = skip BVN; false = run BVN (+ VA + DD in one call). Alias: bvn_verified.", "type": "boolean" }, "virtualAccountVerified": { "description": "true = skip VA; false = run VA only (requires BVN done). Alias: virtual_account_verified.", "type": "boolean" }, "accountLinkingVerified": { "description": "true = skip DD init; false = return redirect_url only (requires VA ready). Alias: account_linking_verified.", "type": "boolean" }, "bvn": { "type": "string", "example": "12345678901" }, "account_number": { "type": "string", "example": "0123456789" }, "bank_code": { "type": "string", "example": "058" }, "bank_name": { "type": "string", "example": "GT Bank" } }, "type": "object" } } } }, "responses": { "200": { "description": "redirect_url when DD step runs; verificationSteps merged in body" }, "422": { "description": "Prerequisite not met" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/verify/employment": { "post": { "tags": [ "Verification - Step 3 - Employment" ], "summary": "Verify User Employment Details", "operationId": "975cf2bd0a57cff9141912be023dd138", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payroll_number", "state_of_employment", "employer_id" ], "properties": { "payroll_number": { "description": "IPPIS / Computer Number", "type": "string" }, "state_of_employment": { "description": "State of employment selected from options", "type": "string" }, "employer_id": { "description": "ID of the employer selected from options", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Employment saved; employer_setup step marked" }, "422": { "description": "Validation failed (rules match VerifyEmploymentAction)" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/virtual-account": { "get": { "tags": [ "Verification - Step 2 - Identity" ], "summary": "Get user virtual account (Paystack dedicated account)", "operationId": "2c819bd968117071c52e25bcfb989ade", "responses": { "200": { "description": "Virtual account details or null if not yet created" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/employment-options": { "get": { "tags": [ "Verification - Step 3 - Employment" ], "summary": "Get standard options for states and employers", "operationId": "c05b70fe8f06d702ccd1ed9bdf5ce2ed", "responses": { "200": { "description": "Success" } } } }, "/api/v1/profile/verification-steps": { "get": { "tags": [ "Verification - Step 2 - Identity" ], "summary": "Get Onboarding Verification Steps (6 Steps)", "description": "personal_details, bvn_verified, virtual_account_verified, account_linked, employer_setup, eligibility_check_complete.", "operationId": "ed0e1c3428097c8b78ac2117f5712b9d", "responses": { "200": { "description": "Steps with completed status" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/identity": { "get": { "tags": [ "Verification - Step 2 - Identity" ], "summary": "Get User Identity Details", "operationId": "c4cd1cc543459554ef3970a5b29dcde1", "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/identity-progress": { "get": { "tags": [ "Verification - Step 2 - Identity" ], "summary": "Get granular Stage 2 sub-step flags (BVN, Virtual Account, Account Linking)", "description": "Returns the three individual boolean flags from user_verification_steps that make up identity_verified. Useful for UI progress bars and skip-logic in Stage 2 calls.", "operationId": "9ac17b1a7c6ab45276b579ebd56b2eee", "responses": { "200": { "description": "bvn_verified, virtual_account_verified, account_linked booleans" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/verify/eligibility": { "post": { "tags": [ "Verification - Step 4 - Bank statement" ], "summary": "Mark Eligibility Check as Complete", "operationId": "6adeda435d6cbb36089bbe52b76a7037", "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/verify-step": { "post": { "tags": [ "Verification" ], "summary": "Mark a Specific Verification Step as Complete", "operationId": "8c5147b462098c592b169848a70a91bc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "step" ], "properties": { "step": { "type": "string", "example": "personal_details" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile": { "put": { "tags": [ "Profile" ], "summary": "Update User Profile", "description": "Updates the authenticated user's basic profile information.", "operationId": "0546b5874b507309d4b984e0547413b4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "John Doe" }, "phone": { "type": "string", "example": "08012345678" }, "dob": { "type": "string", "format": "date", "example": "1990-01-01" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "address": { "type": "string", "example": "123 Main Street" }, "occupation": { "type": "string", "example": "Software Engineer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile updated successfully" }, "user": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/profile/image": { "post": { "tags": [ "Profile" ], "summary": "Upload Profile Image", "description": "Uploads an image file and sets it as the user's profile image.", "operationId": "37b500b7c96b02ab62807fde9421a30a", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "image" ], "properties": { "image": { "description": "The image file to upload (jpeg, png, jpg, gif). Max size: 2MB.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile image uploaded successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile image uploaded successfully" }, "profile_image_url": { "type": "string", "example": "/storage/profile_images/abcdef123456.jpg" }, "user": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/wallet": { "get": { "tags": [ "Wallet" ], "summary": "Get Wallet Balance and Transactions", "description": "Get wallet balance and recent transactions", "operationId": "ccb51126ed08b5769aafac09bca5ee6a", "responses": { "200": { "description": "Wallet details" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/wallet/withdraw": { "post": { "tags": [ "Wallet" ], "summary": "Withdraw Funds from Wallet", "description": "Initiate a withdrawal from wallet to bank account", "operationId": "d59c7c5ee249f3e6b8299435d9ab5429", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "bank_code", "account_number", "account_name" ], "properties": { "amount": { "type": "number", "example": 5000 }, "bank_code": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Withdrawal successful" }, "400": { "description": "Insufficient funds or error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/legals/menu": { "get": { "tags": [ "Legals" ], "summary": "Get Static Legal Menu Options", "description": "Returns the static list of legal documents for the mobile app menu (Terms, Privacy, FAQs). These are hardcoded and not editable by admin.", "operationId": "0446efe99d16ff0bf4ccdfd1a86d5af2", "responses": { "200": { "description": "Static legal menu list", "content": { "application/json": { "schema": { "properties": { "legals": { "type": "array", "items": { "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Enter your token here", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Authentication", "description": "Authentication" }, { "name": "Authentication - Signup Funnel", "description": "Authentication - Signup Funnel" }, { "name": "Authentication - Password Reset", "description": "Authentication - Password Reset" }, { "name": "Dashboard", "description": "Dashboard" }, { "name": "Loans", "description": "Loans" }, { "name": "Public Loan Settlement", "description": "Public Loan Settlement" }, { "name": "Banks", "description": "Banks" }, { "name": "Verification - Step 4 - Bank statement", "description": "Verification - Step 4 - Bank statement" }, { "name": "Profile", "description": "Profile" }, { "name": "Verification - Step 2 - Identity", "description": "Verification - Step 2 - Identity" }, { "name": "Verification - Step 3 - Employment", "description": "Verification - Step 3 - Employment" }, { "name": "Verification", "description": "Verification" }, { "name": "Wallet", "description": "Wallet" }, { "name": "Legals", "description": "Legals" } ] }