# Mono Developer Documentation > Mono is an open banking and payments infrastructure platform for Africa. Mono provides APIs that let businesses access financial data, collect payments, verify identities, and disburse funds across Nigerian financial institutions. Mono's platform serves three core products: Financial Data (Connect), Payments (DirectPay, Direct Debit, Disburse, and Owo), and Identity Verification (Lookup and Prove). ## Getting Started All Mono integrations require: 1. A Mono dashboard account (https://app.mono.co/signup) 2. A dashboard App configured with appropriate product scopes 3. API keys: a public key (for widgets) and a secret key (for backend API calls, passed as `mono-sec-key` header) 4. A configured webhook URL for receiving event notifications Base API URL: https://api.withmono.com Authentication: All API requests use the `mono-sec-key` header with your secret key. Environments: Sandbox and Production share the same base URL; the key type (test vs live) determines the environment. - [Customer](https://docs.mono.co/docs/customers) - [Coverage](https://docs.mono.co/docs/coverage) - [Changelog](https://docs.mono.co/docs/changelog) ## Products ### Get Started - [Definitions](https://docs.mono.co/docs/definitions) - [Use Cases](https://docs.mono.co/docs/use-cases) - [Creating an app](https://docs.mono.co/docs/create-app) - [Environments](https://docs.mono.co/docs/environments) - [Sandbox](https://docs.mono.co/docs/sandbox) - [Webhooks](https://docs.mono.co/docs/webhooks) - [Go Live Checklist](https://docs.mono.co/docs/go-live) - [Quick Start](https://docs.mono.co/docs/quickstart) - [Errors](https://docs.mono.co/docs/errors) - [FAQs](https://docs.mono.co/docs/faqs) ### Developer tools - [Brand Assets](https://docs.mono.co/docs/brand-assets) - [Libraries](https://docs.mono.co/docs/libraries) - [SDKs](https://docs.mono.co/docs/sdks) - [Postman Collection](https://docs.mono.co/docs/postman) ### Integration Guide - [SDK Integration Guide](https://docs.mono.co/docs/financial-data/integration-guide) - [Connect Link Guide](https://docs.mono.co/docs/financial-data/connect-link) - [Reauth Link Guide](https://docs.mono.co/docs/financial-data/reauth-link) ### Financial Data - [SDK Config Guide](https://docs.mono.co/docs/financial-data/sdk) - [Real-time Data](https://docs.mono.co/docs/financial-data/realtime-data) ### Partners API Guide - [Partners API Guide](https://docs.mono.co/docs/financial-data/partners-api) - [Overview](https://docs.mono.co/docs/financial-data/partners-api-guide/overview) - [Integration Guide](https://docs.mono.co/docs/financial-data/partners-api-guide/integration-guide) - [Reauthorisation Guide](https://docs.mono.co/docs/financial-data/partners-api-guide/reauth-guide) - [Sandbox Guide](https://docs.mono.co/docs/financial-data/partners-api-guide/sandbox-guide) ### Data Enrichment - [Overview](https://docs.mono.co/docs/financial-data/enrichment/overview) - [Transaction Categorisation](https://docs.mono.co/docs/financial-data/enrichment/transaction-categorisation) - [Transaction Metadata](https://docs.mono.co/docs/financial-data/enrichment/transaction-metadata) - [Statement Insights](https://docs.mono.co/docs/financial-data/enrichment/statement-insights) ### Endpoints - [Authorization](https://docs.mono.co/docs/financial-data/authorization) - [Account Information](https://docs.mono.co/docs/financial-data/account-information) - [Transactions](https://docs.mono.co/docs/financial-data/transactions) - [Statements](https://docs.mono.co/docs/financial-data/statements) - [Identity](https://docs.mono.co/docs/financial-data/identity) - [Income](https://docs.mono.co/docs/financial-data/income) - [Assets](https://docs.mono.co/docs/financial-data/assets) - [Earnings](https://docs.mono.co/docs/financial-data/earnings) - [Credit Worthiness](https://docs.mono.co/docs/financial-data/credit-worthiness) ### Webhook Events - [Introduction](https://docs.mono.co/docs/financial-data/webhook-introduction) - [Auth (Connection)](https://docs.mono.co/docs/financial-data/auth-connection) - [Account Update (Balance)](https://docs.mono.co/docs/financial-data/account-update) - [Unlink (Disconnection)](https://docs.mono.co/docs/financial-data/unlink) ### Payments - [Payouts](https://docs.mono.co/docs/payments/payouts) - [Split Payments](https://docs.mono.co/docs/payments/split-payments) - [WhatsApp Payment](https://docs.mono.co/docs/whatsapp-payment/overview) - [Disburse](https://docs.mono.co/docs/disburse/overview) ### One-time Direct Pay - [Overview](https://docs.mono.co/docs/payments/onetime/overview) - [Integration Guide](https://docs.mono.co/docs/payments/onetime/integration-guide) - [SDK Guide](https://docs.mono.co/docs/payments/sdk-guide) - [Webhook events](https://docs.mono.co/docs/payments/onetime/webhook-events) - [Payment Status](https://docs.mono.co/docs/payments/onetime/payment-status) ### Recurring Direct Debit - [Overview](https://docs.mono.co/docs/payments/direct-debit/overview) - [Integration Guide](https://docs.mono.co/docs/payments/direct-debit/integration-guide) - [Step 1: Customers](https://docs.mono.co/docs/payments/direct-debit/integration-guide-create-customers) - [Step 2: Mandate Setup Explained](https://docs.mono.co/docs/payments/direct-debit/mandate-setup-explained) - [Step 2a: Mandate Setup (Variable)](https://docs.mono.co/docs/payments/direct-debit/mandate-setup-variable) - [Step 2b: Mandate Setup (Fixed) ](https://docs.mono.co/docs/payments/direct-debit/mandate-setup-fixed) - [Step 3: Debit Account](https://docs.mono.co/docs/payments/direct-debit/debit-an-account) - [Mono Sweep](https://docs.mono.co/docs/payments/direct-debit/mono-sweep) - [Mandate Biometrics Verification](https://docs.mono.co/docs/payments/direct-debit/mandate-biometric-verification) - [Webhook events](https://docs.mono.co/docs/payments/direct-debit/webhook-events) ### Integration Guides - [BVN iGree](https://docs.mono.co/docs/lookup/bvn-igree) - [CAC Lookup](https://docs.mono.co/docs/lookup/cac-lookup) - [Account Number](https://docs.mono.co/docs/lookup/account-number) - [House Address Verification](https://docs.mono.co/docs/lookup/house-address) - [Int'l Passport Lookup](https://docs.mono.co/docs/lookup/intl-passport) - [TIN Lookup](https://docs.mono.co/docs/lookup/tin-lookup) - [Driver's License Lookup](https://docs.mono.co/docs/lookup/drivers-license) - [NIN Lookup](https://docs.mono.co/docs/lookup/nin-lookup) - [Credit History Lookup](https://docs.mono.co/docs/lookup/credit-history-lookup) - [Mashup Lookup](https://docs.mono.co/docs/lookup/mashup) - [Overview](https://docs.mono.co/docs/lookup/watchlist-screening/overview) - [Integration Guide](https://docs.mono.co/docs/lookup/watchlist-screening/integration-guide) - [Webhook Events](https://docs.mono.co/docs/lookup/watchlist-screening/webhook-events) ### Prove - [Overview](https://docs.mono.co/docs/lookup/prove/overview) - [Integration Guide](https://docs.mono.co/docs/lookup/prove/integration-guide) ### Disburse - [Integration Guide](https://docs.mono.co/docs/disburse/integration-guide) - [Webhook Events](https://docs.mono.co/docs/disburse/webhook-events) ### WhatsApp Payment - [Integration Guide](https://docs.mono.co/docs/whatsapp-payment/integration-guide) - [Webhook Events](https://docs.mono.co/docs/whatsapp-payment/webhook-events) ## API Reference Base URL: `https://api.withmono.com` Authentication: `mono-sec-key` header with your secret key. ### Authorisation - `POST /v2/accounts/initiate` - [Account Linking](https://docs.mono.co/api/bank-data/authorisation/initiate-account-linking) Parameters: customer.email (body, required), customer.name (body, required), scope (body, required), redirect_url (body, required), customer.id (body), institution.id (body), institution.auth_method (body), ... 1 more optional Request: {"customer":{"name":"Samuel Olamide","email":"samuel@neem.com"},"meta":{"ref":"99008877TEST"},"scope":"auth","redirect_url":"https://mono.co"} Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-03-18T11:51:41.624Z","data":{"mono_url":"https://link.mono.co/ALGSTO222222WE","customer":"65f82acd00000003aa9028d","meta":"{...}","scope":"auth","institution":"{...}","redirect_url":"https://mono.co","is_multi":false,"created_at":"2024-03-18T11:51:41.605Z"}} - `POST /v2/accounts/auth` - [Exchange Token](https://docs.mono.co/api/bank-data/authorisation/exchange-token) Parameters: code (body, required) Request: {"code":"string"} Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-04-15T18:45:15.371Z","data":{"id":"661d759280dbf646242634cc"}} - `POST /v2/accounts/initiate` - [Re-authorisation](https://docs.mono.co/api/bank-data/authorisation/initiate-account-reauth) Parameters: account (body, required), scope (body, required), redirect_url (body, required), meta.ref (body) Request: {"meta":{"ref":"099777"},"scope":"reauth","account":"65c4c03aa66a95b572cb5a86","redirect_url":"https://mono.co"} Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2025-05-21T13:51:40.920Z","data":{"mono_url":"https://link.mono.co/ALH0IX10JO89","customer":"682fd53a74682beb490a0ed4","account":"682dw53b74682beb490a0ed6","meta":"{...}","scope":"reauth","institution":"{...}","redirect_url":"https://mono.co","is_multi":false,"created_at":"2025-05-21T13:51:40.912Z"}} ### Partners API - `POST /v2/connect/session` - [Create Session](https://docs.mono.co/api/bank-data/partners-api/create-session) Parameters: customer.email (body, required), customer.name (body, required), scope (body, required), redirect_url (body, required), customer.id (body), institution (body), auth_method (body) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-02T11:53:46.781Z","data":{"session":"{...}","ui":"{...}"}} - `POST /v2/connect/login` - [Login](https://docs.mono.co/api/bank-data/partners-api/login) Parameters: username (body, required), password (body, required) Request: {"username":"2000123456","password":"******"} Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-02T11:53:46.781Z","data":{"login":"{...}","ui":"{...}"}} - `POST /v2/connect/commit` - [Commit Session](https://docs.mono.co/api/bank-data/partners-api/commit-session) Parameters: accountNumber (body, required), otp (body), answer (body) - `POST /v2/connect/reauth/session` - [Reauth Session](https://docs.mono.co/api/bank-data/partners-api/reauth-session) Parameters: account (body, required) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-05-13T12:26:36.853Z","data":{"responseCode":99,"code":"code_q90t4ar2uriet5ey4rs22v0x"}} - `POST /v2/connect/reauth/login` - [Reauth Login](https://docs.mono.co/api/bank-data/partners-api/reauth-login) Parameters: username (body, required), password (body, required) Request: {"username":"2000123456","password":"******"} - `POST /v2/connect/sandbox` - [Retrieve Sandbox Credentials](https://docs.mono.co/api/bank-data/partners-api/sandbox-credentials) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-05-13T11:13:15.842Z","data":{"credentials":["..."],"inputs":[]}} ### Account - `GET /v2/accounts/{id}` - [Details](https://docs.mono.co/api/bank-data/accounts/details) Parameters: id (path, required) Response: {"status":"successful","message":"Request was succesfully completed","timestamp":"2026-01-27T12:30:22.399Z","data":{"account":"{...}","customer":"{...}","meta":"{...}"}} - `GET /v2/accounts/{id}/identity` - [Identity](https://docs.mono.co/api/bank-data/accounts/identity) Parameters: id (path, required) Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-05-22T06:38:27.799Z","data":{"full_name":"SAMUEL OLAMIDE NOMO","bvn":"22000000012","phone":"08012345678","gender":"Male","dob":"1997-08-07","address_line1":"Ikeja","state_of_origin":"Ogun State","lga_of_origin":"Abeokuta South","marital_status":"Single","verified":true,"created_at":"2024-05-16T17:05:07.357Z","updated_at":"2024-05-16T17:05:07.357Z"}} - `GET /v2/accounts/{id}/balance` - [Balance](https://docs.mono.co/api/bank-data/accounts/account-balance) Parameters: id (path, required) Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-05-22T06:44:42.884Z","data":{"id":"61e54d400000007510073257","name":"SAMUEL OLAMIDE NOMO","account_number":"01000005899","balance":35232,"currency":"NGN"}} - `GET /v2/accounts/{id}/income` - [Income](https://docs.mono.co/api/bank-data/accounts/income) Parameters: id (path, required), period (query) Response: {"status":"successful","message":"The income of ${account.name} is currently being processed, and the data will be sent to you through your webhook","timestamp":"2024-05-21T10:38:02.376Z","data":null} - `GET /v2/accounts/{id}/income-records` - [Income Records](https://docs.mono.co/api/bank-data/accounts/income-records) Parameters: id (path, required), page (query) Response: {"status":"successful","message":"Data retrieved successfully","timestamp":"2025-05-27T13:52:05.804Z","data":["{...}","..."],"meta":{"total":2,"pages":1,"previous":null,"next":null}} - `GET /v2/accounts` - [Get Accounts](https://docs.mono.co/api/bank-data/accounts/get-accounts) Response: {"status":"successful","message":"Data retrieved successfully","timestamp":"2024-04-12T09:55:07.980Z","data":["{...}","..."],"meta":{"total":1571,"pages":158,"previous":null,"next":"https://api.withmono.com/v2/accounts/?page=2"}} - `POST /v2/accounts/{id}/creditworthiness` - [Creditworthiness](https://docs.mono.co/api/bank-data/accounts/credit-worthiness) Parameters: id (path, required), bvn (body, required), principal (body, required), interest_rate (body, required), term (body, required), run_credit_check (body, required), existing_loans (body) Response: {"status":"successful","message":"The creditworthiness of SAMUEL, OLAMIDE NOMO is currently being processed. Once completed, the data will be sent to your webhook.","timestamp":"2024-03-15T15:14:28.679Z","data":null} - `POST /v2/accounts/{id}/unlink` - [Unlink](https://docs.mono.co/api/bank-data/accounts/unlink) Parameters: id (path, required) Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-03-15T15:20:27.732Z"} - `GET /v2/accounts/{id}` - [Details](https://docs.mono.co/api/telco-data/details) Parameters: id (path, required) Response: {"meta":{"data_status":"AVAILABLE","auth_method":"mobile_banking"},"account":{"_id":"630484cdca8f9f1a91234567","institution":"{...}","name":"KING KUNTA","accountNumber":"+2347012345678","type":"telecom_account","balance":7659,"currency":"NGN","bvn":null}} - `GET /v2/accounts/{id}/balances` - [Balances](https://docs.mono.co/api/telco-data/balances) Parameters: id (path, required) - `GET /v2/accounts/{id}/transactions` - [Transactions](https://docs.mono.co/api/telco-data/transactions) Parameters: id (path, required), start (query), end (query), narration (query), ... 2 more optional Response: {"paging":{"total":25,"page":1,"previous":null,"next":"https://api.withmono.com/v2/accounts/62f15763982abb0d25e1fefd/transactions?page=2"},"data":["{...}","..."]} - `GET /v2/accounts/{id}/identity` - [Identity](https://docs.mono.co/api/telco-data/identity) Parameters: id (path, required) Response: {"fullName":"SAMUEL OLAMIDE NOMO","phone":"+2347033445599","gender":"male","bvn":null,"dob":"1997-08-07T00:00:00.000Z","created_at":"2024-07-17T11:16:49.632Z","updated_at":"2024-07-17T11:16:49.632Z"} - `GET /v3/payments/mandates/{id}/balance-inquiry` - [Balance Inquiry](https://docs.mono.co/api/direct-debit/account/balance-inquiry) Parameters: id (path, required), amount (query) Response: {"status":"successful","message":"Sufficient balance available","data":{"id":"mmc_6836182ac511bb531611daf9","has_sufficient_balance":true,"account_details":"{...}"}} - `POST /v3/payments/mandates/{id}/debit` - [Debit Account](https://docs.mono.co/api/direct-debit/account/debit-account) Parameters: id (path, required), amount (body, required), reference (body, required), narration (body, required), beneficiary (body), beneficiary.nuban (body), beneficiary.nip_code (body), ... 9 more optional Response: {"status":"successful","message":"Account debited successfully.","response_code":"00","data":{"success":true,"status":"successful","event":"successful","amount":20000,"mandate":"mmc_6836182ac511bb531611daf9","reference_number":"btD03191D118","date":"2025-05-29T22:16:25.547Z","live_mode":true,"fee":5500,"fee_bearer":"business","narration":"Subscription","session_id":"999999250919103136775149584552","...":"3 more keys"}} - `GET /v3/payments/mandates/{id}/debit/{reference}` - [Retrieve a Debit](https://docs.mono.co/api/direct-debit/account/retrieve-a-debit) Parameters: id (path, required), reference (path, required) Response: {"status":"successful","message":"request completed successfully","data":{"amount":20000,"currency":"NGN","type":"variable-debit","status":"successful","channel":"mandate","mandate":"mmc_6836182ac511bb531611daf9","reference":"btD03191D118","narration":"Subscription","live_mode":true,"app":"67aa07d46d999626f9472b42","refunded":false,"date":"2025-05-29T22:16:25.547Z","...":"1 more keys"}} - `GET /v3/payments/mandates/{id}/debits` - [Retrieve all Debits](https://docs.mono.co/api/direct-debit/account/retrieve-all-debits) Parameters: id (path, required) ### Statements - `GET /v2/accounts/{id}/statement` - [Statements](https://docs.mono.co/api/bank-data/bank-statement) Parameters: id (path, required), period (query, required), output (query), format (query) - `GET /v2/accounts/{id}/statement/jobs/{jobId}` - [Poll PDF Status](https://docs.mono.co/api/bank-data/poll-pdf-status) Parameters: id (path, required), jobId (path, required) Response: {"status":"successful","message":"Request was successfully completed","data":{"id":"2ojHeRva4Bfk9vvIuCuO","status":"BUILT","path":"https://api.withmono.com/statements/0XmnvkiJZ8dWOYQOF6tM.pdf"}} ### Transactions - `GET /v2/accounts/{id}/transactions` - [Transactions](https://docs.mono.co/api/bank-data/transactions) Parameters: id (path, required), start (query), end (query), narration (query), ... 2 more optional ### Investment - `GET /v2/accounts/{id}/assets` - [Assets](https://docs.mono.co/api/bank-data/investment/assets) Parameters: id (path, required) Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-03-15T15:10:57.842Z","data":{"id":"65d76676c4977cf","balances":"{...}","assets":["..."]}} - `GET /v2/accounts/{id}/earnings` - [Earnings](https://docs.mono.co/api/bank-data/investment/earnings) Parameters: id (path, required) Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-03-15T15:09:13.581Z","data":["{...}","..."]} ### Data Enrichment - `POST /v2/accounts/{id}/transactions/categorise` - [Categorisation](https://docs.mono.co/api/bank-data/enrichment/transaction-categorisation) Parameters: id (path, required) Response: {"status":"processing","message":"Categorisation is currently being processed, you will receive a webhook when all transactions have been categorised","timestamp":"2024-11-15T13:28:33.665Z","data":{"jobId":"67374c81bc5d5f97f526bbc6","jobStatus":"processing"}} - `POST /v2/enrichments/transaction-categorisation` - [Categorisation (CSV)](https://docs.mono.co/api/bank-data/enrichment/transaction-categorisation-upload) Response: {"status":"processing","message":"Categorisation is currently being processed, you will receive a webhook when all transactions have been categorised","timestamp":"2024-11-19T07:51:44.641Z","data":{"jobId":"673c439098d8df63d99335b9","jobStatus":"processing"}} - `POST /v2/accounts/{id}/transactions/metadata` - [Metadata](https://docs.mono.co/api/bank-data/enrichment/transaction-metadata) Parameters: id (path, required) Response: {"status":"processing","message":"Transaction metadata is currently being processed, you will receive a webhook when all transactions have been categorised","timestamp":"2024-11-19T09:01:46.727Z","data":{"jobId":"673c53fa98d8df63d993361f","jobStatus":"processing"}} - `POST /v2/enrichments/transaction-metadata` - [Metadata (CSV)](https://docs.mono.co/api/bank-data/enrichment/transaction-metadata-upload) Response: {"status":"processing","message":"Transaction metadata is currently being processed, you will receive a webhook when all transactions are ready","timestamp":"2024-11-19T09:21:19.750Z","data":{"jobId":"673c588f98d8df63d99341cf","jobStatus":"processing"}} - `GET /v2/accounts/{id}/statement/insights` - [Statement Insights](https://docs.mono.co/api/bank-data/enrichment/statement-insights) Parameters: id (path, required) Response: {"status":"processing","message":"Statement insights is currently being processed, you will receive a webhook when insight is ready","timestamp":"2024-11-19T10:34:37.535Z","data":{"jobId":"673c69bd98d8df63d9934de8","jobStatus":"processing"}} - `GET /v2/enrichments/record/{jobId}` - [Enrichment Records](https://docs.mono.co/api/bank-data/enrichment/enrichment-records) - `GET /v2/accounts/jobs/{id}` - [Job Tracker](https://docs.mono.co/api/bank-data/enrichment/job-tracker) Parameters: id (path, required) Response: {"status":"successful","message":"Job is still processing","timestamp":"2024-11-25T09:17:28.347Z","data":{"id":"6744409ff821e2afdea4c749","job_status":"processing","name":"jobs.enrichment.statement_insights","type":"statement_insights","account":"67405d074b87be75af8f8358"}} ### Inflow/Outflow - `GET /v2/accounts/{id}/credits` - [Credits](https://docs.mono.co/api/bank-data/credits) Parameters: id (path, required) - `GET /v2/accounts/{id}/debits` - [Debits](https://docs.mono.co/api/bank-data/debits) Parameters: id (path, required) ### Authenticate - `POST /v2/telecom/auth` - [Login](https://docs.mono.co/api/telco-data/login) Parameters: phone (body, required), provider (body, required) Request: {"provider":"airtel","phone":"08012345678"} Response: {"status":"successful","data":{"session_id":"4YM7TXtvU1viUWFH","result":"{...}"}} - `POST /v2/telecom/verify` - [OTP verification](https://docs.mono.co/api/telco-data/otp-verification) Parameters: otp (body, required) Request: {"otp":"string"} Response: {"status":"successful","data":{"code":"code_AwEo6hTHJtUiKE99r1ca"}} - `POST /v2/accounts/auth` - [Token exchange](https://docs.mono.co/api/telco-data/token-exchange) Parameters: code (body, required) Request: {"code":"string"} Response: {"id":"5f171a530295e231abca1153"} ### One-time payments - `POST /v2/payments/initiate` - [Initiate a payment](https://docs.mono.co/api/directpay/initiate) Parameters: amount (body, required), type (body, required), description (body, required), reference (body, required), method (body), account (body), customer.email (body), ... 17 more optional Response: {"status":"successful","message":"Payment Initiated Successfully","timestamp":"2025-05-21T21:58:21.087Z","data":{"id":"ODW2QV0WLIDG","mono_url":"https://checkout.mono.co/ODW2QV0WLIDG","type":"onetime-debit","method":"transfer","amount":21000,"description":"Ticket","reference":"ref03098","customer":"67aa0961271cb661d8cbae3b","institution":"5f2d08bf60b92e2888287704","auth_method":"internet_banking","redirect_url":"https://mono.co","created_at":"2025-05-21T21:58:21.078Z","...":"3 more keys"}} - `GET /v2/payments/verify/{reference}` - [Verify Payment Status](https://docs.mono.co/api/directpay/verify) Parameters: reference (path, required) Response: {"status":"successful","message":"Payment retrieved successfully","timestamp":"2025-06-11T12:50:08.866Z","data":{"id":"6836e6addc85c314cfbb400a","meta":null,"instruments":["..."],"channel":"mandate","fee":5500,"feeBearer":"business","type":"variable-debit","status":"successful","amount":20000,"currency":"NGN","description":"Ticket","reference":"iupr81gt9jksgn812odtcc6u","...":"11 more keys"}} - `GET /v2/payments/transactions` - [Fetch all Payments](https://docs.mono.co/api/directpay/fetch-payments) Parameters: limit (query), page (query), start (query), ... 4 more optional ### Mandates - `GET /v3/banks/list` - [Get Banks](https://docs.mono.co/api/direct-debit/mandate/get-banks) - `POST /v2/payments/initiate` - [Initiate a mandate](https://docs.mono.co/api/direct-debit/mandate/initiate-mandate-authorisation) Parameters: amount (body, required), type (body, required), method (body, required), mandate_type (body, required), debit_type (body, required), description (body, required), reference (body, required), customer.id (body, required), customer.phone (body, required), customer.address (body, required), start_date (body, required), end_date (body, required), frequency (body, required), retrial_frequency (body, required), initial_debit_date (body, required), grace_period (body, required), minimum_due (body, required), redirect_url (body), meta (body), interval (body), ... 1 more optional Response: {"status":"successful","message":"Payment Initiated Successfully","data":{"mono_url":"https://authorise.mono.co/RD3044259","mandate_id":"mmc_682b977203c0b7360787b460","type":"recurring-debit","method":"mandate","mandate_type":"emandate","amount":9190030,"description":"Repayment for samuel@neem.com","reference":"test-O2b9O9EF903-949493432","customer":"65eb623b0000900009e5c1f21cd","redirect_url":"https://mono.co","created_at":"2024-03-12T14:17:31.548Z","updated_at":"2024-03-12T14:17:31.548Z","...":"2 more keys"}} - `POST /v3/payments/mandates` - [Create a mandate](https://docs.mono.co/api/direct-debit/mandate/create-a-mandate) Parameters: customer (body, required), mandate_type (body, required), debit_type (body, required), amount (body, required), reference (body, required), account_number (body, required), bank_code (body, required), description (body, required), start_date (body, required), end_date (body, required), frequency (body, required), retrial_frequency (body, required), grace_period (body, required), minimum_due (body, required), fee_bearer (body), signature (body), meta (body), ... 5 more optional Request: {"debit_type":"variable","customer":"string","mandate_type":"string","amount":"integer","reference":"string","account_number":"string","bank_code":"string","fee_bearer":"string","description":"string","start_date":"string","end_date":"string","verification_method":"string","...":"1 more keys"} - `GET /v3/payments/mandates/{id}` - [Retrieve a Mandate](https://docs.mono.co/api/direct-debit/mandate/retrieve-a-mandate) Parameters: id (path, required) Response: {"status":"successful","message":"request completed successfully","data":{"id":"mmc_682b9c5803c0b736078889a3","status":"approved","reference":"refO2b9O9E03m","amount":80030,"balance":80030,"mandate_type":"emandate","debit_type":"variable","account_name":"SAMUEL OLAMIDE","account_number":"0123456789","live_mode":true,"approved":true,"ready_to_debit":false,"...":"8 more keys"}} - `GET /v3/payments/mandates` - [Get all Mandates](https://docs.mono.co/api/direct-debit/mandate/get-all-mandates) Parameters: limit (query, required), page (query, required) - `PATCH /v3/payments/mandates/{id}/cancel` - [Cancel Mandate](https://docs.mono.co/api/direct-debit/mandate/cancel-mandate) Parameters: id (path, required) Response: {"status":"success","response_code":"200","message":"This mandate is now cancelled and deleted, and can't be used again","timestamp":"2025-05-19T22:15:56.343Z","documentation":"https://mono.co/docs/error-codes/200","data":null} - `PATCH /v3/payments/mandates/{id}/pause` - [Pause Mandate](https://docs.mono.co/api/direct-debit/mandate/pause-mandate) Parameters: id (path, required) Response: {"status":"success","response_code":"200","message":"This mandate is now paused and can't be used for debit or balance inquiry, but you can reinstate it back.","timestamps":"2023-12-13T20:23:07.074Z","documentation":"https://mono.co/docs/error-codes/400","data":null} - `PATCH /v3/payments/mandates/{id}/reinstate` - [Reinstate Mandate](https://docs.mono.co/api/direct-debit/mandate/reinstate-mandate) Parameters: id (path, required) Response: {"status":"success","response_code":"200","message":"The mandate has been reinstated successfully and is now active for debit and balance inquiry","timestamp":"2025-05-19T21:37:50.430Z","documentation":"https://mono.co/docs/error-codes/200","data":null} ### Money Operations - `GET /v2/payments/payouts` - [Payout](https://docs.mono.co/api/money-operations/payout) Parameters: status (query, required) - `GET /v2/payments/payout/{payout}/transactions` - [Payout Transactions](https://docs.mono.co/api/money-operations/payout-transactions) Parameters: account (query, required), status (path, required) Response: {"status":"successful","message":"Data retrieved successfully","data":{"payments":["..."]},"meta":{"paging":"{...}"}} - `POST /v2/payments/refund` - [Refund Payment](https://docs.mono.co/api/money-operations/refund) Parameters: reference (body, required), source (body) Request: {"reference":"ref-123-456","source":"wallet"} Response: {"status":"successful","message":"Refunded payment successfully","timestamp":"2024-04-11T17:25:52.535Z","data":{"id":"6615f0baaaa34e17e8d01234","reference":"demo_ref_mxy0mb1234","refunded":true,"refunded_amount":20000,"beneficiary":"{...}"}} - `POST /v2/payments/payout/sub-account` - [Create a Sub-Account](https://docs.mono.co/api/money-operations/create-a-subaccount) Parameters: nip_code (body, required), account_number (body) Request: {"nip_code":"000000","account_number":"1234567890"} Response: {"status":"successful","message":"Request completed successfully","data":{"id":"6126aef671612f6126aef671612f","name":"Sub Account Name","account_number":"1234567890","nip_code":"000000","bank_code":"058"}} - `GET /v2/payments/payout/sub-accounts` - [Fetch all Sub-Accounts](https://docs.mono.co/api/money-operations/fetch-subaccounts) Parameters: nip_code (body, required), account_number (body) Response: {"status":"successful","message":"Subaccounts retrieved successfully","timestamp":"2024-11-29T16:45:00.581Z","data":["{...}","..."],"meta":{"paging":"{...}"}} ### User - `GET /owo/v1/users/status` - [Check User Status](https://docs.mono.co/api/whatsapp-payment/user) Parameters: phone (query) Response: {"status":"successful","message":"User is active and ready to perform transactions.","timestamp":"2025-07-26T14:13:10.465Z","data":{"exists":true,"status":"active"}} ### Beneficiary - `POST /owo/v1/beneficiaries/link` - [Link Beneficiary](https://docs.mono.co/api/whatsapp-payment/beneficiary/link) Parameters: phone (body, required), fund_beneficiary (body, required), fund_beneficiary.name (body, required), fund_beneficiary.nip_code (body, required), fund_beneficiary.account_number (body, required), bvn (body), fund_request (body) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-26T14:13:09.401Z","data":{"redirect_url":"https://wa.me/2348022381023?text=Hi+Owo%2C+I+want+to+complete+my+account+linking."}} - `POST /owo/v1/beneficiaries/unlink` - [Unlink Beneficiary](https://docs.mono.co/api/whatsapp-payment/beneficiary/unlink) Parameters: id (body, required) Request: {"id":"ben_b0TSrl7gucHg"} Response: {"status":"processing","message":"Beneficiary unlinking initiated successfully. You will be notified once it is completed.","timestamp":"2025-07-26T14:13:07.262Z"} - `GET /owo/v1/beneficiaries/:id` - [Get Beneficiary](https://docs.mono.co/api/whatsapp-payment/beneficiary/get-beneficiary) Parameters: id (path) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-26T14:13:01.319Z","data":{"id":"ben_TYxCAKx5U6sR","nickname":"Deon","phone":"2348087426765","name":"Elyn Gob","account_number":"6792515375","nip_code":"305322","type":"transfer"}} - `GET /owo/v1/beneficiaries` - [Get All Beneficiaries](https://docs.mono.co/api/whatsapp-payment/beneficiary/get-all-beneficiaries) Parameters: phone (query), limit (query) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-26T14:13:08.480Z","data":["{...}"],"pagination":{"offset":0,"limit":15,"has_more":false}} ### Fund request - `POST /owo/v1/fund-requests` - [Fund request](https://docs.mono.co/api/whatsapp-payment/fund-request/one-time) Parameters: phone (body, required), reference (body, required), type (body, required), amount (body, required), currency (body, required) Request: {"phone":"2349136923755","reference":"ghcxtrrgxcji","description":"Single Fund Request","amount":20000,"currency":"NGN","type":"onetime"} Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-20T14:01:04.442Z","data":{"redirect_url":"https://wa.me/2349018277910?text=Hi+Owo%2C+I+want+to+complete+my+fund+request."}} - `POST /owo/v1/fund-requests` - [Recurring](https://docs.mono.co/api/whatsapp-payment/fund-request/recurring) Parameters: phone (body, required), reference (body, required), type (body, required), amount (body, required), currency (body, required), schedule (body, required), schedule.period (body, required), schedule.interval (body, required), schedule.start_date (body, required), schedule.end_date (body) Request: {"phone":"2349136923755","reference":"nlEhET3XhI9A","type":"recurring","description":"Weekly savings top-up","amount":67877,"currency":"NGN","schedule":{"period":"day","interval":11,"start_date":"2025-07-27T14:13:08.014Z","end_date":"2025-08-25T14:13:08.014Z"}} Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-26T14:13:07.971Z","data":{"redirect_url":"https://wa.me/2348072255993?text=Hi+Owo%2C+I+want+to+complete+my+fund+request."}} - `GET /owo/v1/fund-requests` - [All Fund Requests](https://docs.mono.co/api/whatsapp-payment/fund-request/get-all) Parameters: limit (query), phone (query) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-08-14T00:38:54.608Z","data":["{...}","..."],"pagination":{"offset":0,"limit":3,"has_more":true}} - `GET /owo/v1/fund-requests/:id` - [Fund Request By Id](https://docs.mono.co/api/whatsapp-payment/fund-request/get-request) Parameters: id (query) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-20T13:30:35.672Z","data":{"id":"frq_VJq1KstpUSUC","phone":"9136923755","beneficiary":"ben_QZcZWQGH9j4Q","status":"pending","reference":"frpartnerref12345","type":"recurring","description":"Weekly savings top-up","amount":1000000,"currency":"NGN","schedule":"{...}"}} ### Payments - `GET /owo/v1/fund-requests/{fund_request_id}/payments` - [Payments](https://docs.mono.co/api/whatsapp-payment/fund-request-payments/get-all-payments) Parameters: fund_request_id (path) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-26T14:13:05.818Z","data":["{...}"],"pagination":{"offset":0,"limit":15,"has_more":false}} - `GET /owo/v1/fund-requests/{fund_request_id}/payments/{payment_id}` - [Single Payment Details](https://docs.mono.co/api/whatsapp-payment/fund-request-payments/get-payment) Parameters: fund_request_id (path), payment_id (path) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-07-26T14:13:06.729Z","data":{"id":"tx_nXSbkwOXixNp","reference":"ZBFZXaZwPXSOVhO","fund_request":"frq_SlX61VRsrLP9","status":"successful","message":"IsmVILDJkBWeeak","amount":84249,"currency":"NGN","processed_at":"2025-07-26T14:13:06.717Z","session_id":"999999202507261029012345678901"}} ### Disburse - `POST /v3/payments/disburse/source-accounts` - [Create a Source Account](https://docs.mono.co/api/disburse/create-source-account) Parameters: app (body, required), account_number (body, required), bank_code (body, required), email (body, required) Request: {"app":"62229d670c34e0c3b9139f44","account_number":"1122334455","bank_code":"044","email":"support@merchant.co"} Response: {"status":"successful","message":"Source account created successfully","timestamp":"2026-02-04T10:55:56.434Z","data":{"id":"6980b77bba344a0c29b447d8","mandate_activation_url":"https://authorise.mono.co/RD0021933111"}} - `PUT /v3/payments/disburse/source-accounts/{account_id}/status` - [Update a Source Account](https://docs.mono.co/api/disburse/update-source-account) Parameters: account_id (path, required), action (body, required) Request: {"action":"disable"} Response: {"status":"successful","message":"Account status updated successfully","timestamp":"2026-02-10T10:22:48.340Z","data":{"id":"69ab05c4ba345b0d29c448e9","account_number":"2028765432","bank_code":"033","app":"62229d670c34e0c3b9139f44","status":"enabled","created_at":"2026-02-02T15:19:30.487Z","updated_at":"2026-02-10T10:22:48.300Z"}} - `GET /v3/payments/disburse/source-accounts` - [Fetch All Source Accounts](https://docs.mono.co/api/disburse/fetch-all-source-accounts) Response: {"status":"successful","message":"Source accounts fetched successfully","timestamp":"2026-02-10T11:15:32.850Z","data":{"accounts":["..."],"pagination":"{...}"}} - `GET /v3/payments/disburse/source-accounts/{account_id}` - [Fetch a Source Account](https://docs.mono.co/api/disburse/fetch-source-account) Parameters: account_id (path, required) Response: {"status":"successful","message":"Source account retrieved successfully","timestamp":"2025-08-14T15:32:29.600Z","data":{"id":"686e4d8eaca31c1b8204b4db","app":"63249e670b34d0c3a9139b98","account_name":"JOHN DOE","account_number":"0069871234","bank_code":"044","ready_to_debit":true,"status":"enabled","created_at":"2025-07-09T11:07:58.217Z","updated_at":"2025-08-14T15:30:11.497Z"}} - `POST /v3/payments/disburse/disbursements` - [Create Instant Disbursement](https://docs.mono.co/api/disburse/create-instant-disbursement) Parameters: reference (body, required), source (body, required), account (body, required), type (body, required), total_amount (body, required), distribution (body, required), distribution[].reference (body, required), distribution[].account (body, required), distribution[].account.account_number (body, required), distribution[].account.bank_code (body, required), distribution[].amount (body, required), description (body), distribution[].recipient_email (body), distribution[].narration (body) Request: {"reference":"disburse_ref_12345","source":"mandate","account":"688a0b672f88771f77d05cf5","type":"instant","total_amount":500000,"description":"instant disbursement payment","distribution":["{...}","..."]} Response: {"status":"successful","message":"Disbursement request received","timestamp":"2025-08-01T09:42:59.668Z","data":{"id":"688c8c23b947fac1455fa48f","reference":"disburse_ref_12345","status":"pending"}} - `POST /v3/payments/disburse/disbursements` - [Create Scheduled Disbursement](https://docs.mono.co/api/disburse/create-scheduled-disbursement) Parameters: reference (body, required), source (body, required), account (body, required), type (body, required), total_amount (body, required), distribution[].reference (body, required), distribution[].account (body, required), distribution[].account.account_number (body, required), distribution[].account.bank_code (body, required), distribution[].amount (body, required), description (body), distribution (body), distribution[].recipient_email (body), ... 1 more optional Request: {"reference":"disburse_ref_67890","source":"mandate","account":"688a0b672f88771f77d05cf5","type":"scheduled","total_amount":1000000,"description":"monthly payroll disbursement","distribution":["{...}"]} Response: {"status":"successful","message":"Scheduled disbursement created","timestamp":"2025-08-01T09:48:39.131Z","data":{"id":"688c8d77b947fac1455fa4c4","reference":"disburse_ref_67890","status":"created"}} - `POST /v3/payments/disburse/disbursements/{batch_id}/transition` - [Transition Disbursement](https://docs.mono.co/api/disburse/transition-disbursement) Parameters: batch_id (path, required), action (body, required) Request: {"action":"trigger"} Response: {"status":"successful","message":"Disbursement updated successfully","timestamp":"2026-02-10T15:45:22.150Z","data":{"status":"processing","id":"69ab25d1f9caff82e46a8567"}} - `POST /v3/payments/disburse/disbursements/{batch_id}/distributions` - [Add Distributions to Batch](https://docs.mono.co/api/disburse/add-distributions-to-batch) Parameters: batch_id (path, required), distribution (body, required), distribution[].bank_code (body, required), distribution[].account_number (body, required), distribution[].amount (body, required), distribution[].recipient_email (body), distribution[].narration (body), distribution[].reference (body) Request: {"distribution":["{...}"]} Response: {"status":"successful","message":"Distribution added successfully","timestamp":"2026-02-04T21:28:36.286Z","data":{"status":"successful","summary":"{...}","valid_accounts":[],"invalid_accounts":["..."]}} - `PATCH /v3/payments/disburse/disbursements/{batch_id}/distributions/{distribution_id}` - [Update Distribution in Batch](https://docs.mono.co/api/disburse/update-distribution-in-batch) Parameters: batch_id (path, required), distribution_id (path, required), distribution (body, required), distribution[].recipient_email (body), distribution[].bank_code (body), distribution[].narration (body), ... 3 more optional Request: {"distribution":["{...}"]} Response: {"status":"successful","message":"Distribution added successfully","timestamp":"2026-02-10T13:55:22.480Z","data":{"status":"successful","summary":"{...}","valid_accounts":["..."],"invalid_accounts":[]}} - `DELETE /v3/payments/disburse/disbursements/{batch_id}/distributions/{distribution_id}` - [Delete Distribution in Batch](https://docs.mono.co/api/disburse/delete-distribution-in-batch) Parameters: batch_id (path, required), distribution_id (path, required) Response: {"status":"successful","message":"Distribution deleted successfully","timestamp":"2026-02-10T13:55:22.480Z","data":null} - `GET /v3/payments/disburse/disbursements` - [Fetch All Disbursements](https://docs.mono.co/api/disburse/fetch-all-disbursements) Response: {"status":"successful","message":"Disbursements retrieved successfully","timestamp":"2026-02-10T14:30:15.200Z","data":{"disbursements":["..."],"pagination":"{...}"}} - `GET /v3/payments/disburse/disbursements/{batch_id}` - [Fetch a Disbursement](https://docs.mono.co/api/disburse/fetch-a-disbursement) Parameters: batch_id (path, required) Response: {"status":"successful","message":"Disbursement fetched successfully","timestamp":"2026-02-10T08:22:15.340Z","data":{"id":"69ab1e7c89a9fk5g3d2h8ijl","reference":"payroll_q1_batch_001","status":"initiated","description":"Q1 employee compensation","type":"scheduled","total_amount":500000,"distributions_count":5,"approved_by":"Finance Manager","approval_date":"2026-02-09T11:30:45.200Z","total_records_count":5,"total_successful_amount":"500000","successful_transactions_count":5,"...":"4 more keys"}} - `GET /v3/payments/disburse/disbursements/{batch_id}/distributions` - [Fetch All Distributions in Batch](https://docs.mono.co/api/disburse/fetch-all-distributions-in-batch) Parameters: batch_id (path, required) Response: {"status":"successful","message":"Transactions retrieved successfully","timestamp":"2026-02-10T12:35:44.220Z","data":{"batch_id":"69ab12f4f9caff82e46a80ab","distributions":["..."],"pagination":"{...}"}} - `GET /v3/payments/disburse/disbursements/{batch_id}/distributions/{distribution_id}` - [Fetch a Single Distribution](https://docs.mono.co/api/disburse/fetch-a-single-distribution) Parameters: batch_id (path, required), distribution_id (path, required) Response: {"status":"successful","message":"Transaction retrieved successfully","timestamp":"2026-02-10T12:40:15.560Z","data":{"id":"69ab12f5f9caff82e46a80ad","batch_id":"69ab12f4f9caff82e46a80ab","reference":"dist_salary_emp_002","account_number":"2028765432","bank_code":"058","amount":250000,"narration":"monthly salary","status":"completed","recipient_email":"employee2@company.com"}} ### BVN - `POST /v2/lookup/bvn/initiate` - [Initiate BVN lookup](https://docs.mono.co/api/bvn/initiate) Parameters: bvn (body, required), scope (body) Request: {"bvn":"string","scope":"string"} Response: {"status":"successful","message":"BVN Lookup successfully initiated.","timestamp":"2024-05-13T07:27:02.235Z","data":{"session_id":"74c8fe70-ea2c-458e-a99f-3f7a6061632c","bvn":"01234567891","methods":["..."]}} - `POST /v2/lookup/bvn/verify` - [Verify BVN OTP](https://docs.mono.co/api/bvn/verify-otp) Parameters: method (body, required), phone_number (body, required) Request: {"method":"phone","phone_number":"string"} Response: {"status":"successful","message":"Please enter the OTP that was sent to 0708***1234","timestamp":"2024-05-14T02:44:16.588Z","data":null} - `POST /v2/lookup/bvn/details` - [Fetch BVN Details](https://docs.mono.co/api/bvn/fetch-bvn) Parameters: otp (body, required) Request: {"otp":"string"} Response: {"status":"successful","message":"BVN details successfully fetched.","timestamp":"2024-04-24T16:26:04.392Z","data":{"first_name":"Samuel","last_name":"Olamide","middle_name":"Nomo","dob":"2020-01-06","phone_number":"08012345616","phone_number_2":null,"email":"nomo@test.com","gender":"Male","state_of_origin":"Lagos State","bvn":"12345678901","nin":"000000000","nationality":"Nigeria","...":"7 more keys"}} ### CAC - `GET /v3/lookup/cac` - [Lookup a Business](https://docs.mono.co/api/cac/business) Parameters: search (query, required), exact (query) - `GET /v3/lookup/cac/company/{id}` - [Shareholder Details](https://docs.mono.co/api/cac/shareholder) Parameters: id (path, required) Response: {"status":"successful","message":"CAC lookup successful","timestamp":"2024-02-14T13:42:07.629Z","data":["{...}"]} - `GET /v3/lookup/cac/company/{id}/psc` - [Persons with Significant Control](https://docs.mono.co/api/cac/psc) Parameters: id (path, required) - `GET /v3/lookup/cac/company/{id}/secretary` - [Secretary](https://docs.mono.co/api/cac/secretary) Parameters: id (path, required) Response: {"status":"successful","message":"CAC lookup successful","timestamp":"2024-02-16T07:45:34.130Z","data":["{...}"]} - `GET /v3/lookup/cac/company/{id}/directors` - [Directors](https://docs.mono.co/api/cac/directors) Parameters: id (path, required) Response: {"status":"successful","message":"CAC lookup successful","timestamp":"2024-02-14T13:42:07.629Z","data":["{...}"]} - `GET /v3/lookup/cac/profile/{rcnumber}` - [Profile](https://docs.mono.co/api/cac/profile) Parameters: rcnumber (path, required) Response: {"status":"successful","message":"CAC lookup successful","timestamp":"2025-09-18T08:49:00.542Z","data":{"approved_name":"ELITE SYNERGY VENTURES","nature_of_business_name":null,"registration_date":"2021-10-26T07:13:37.772Z","rc_number":"3333333","id":7648693,"classification":"BUSINESS_NAME","classification_id":1,"active":true,"registration_approved":null,"delisting_status":null,"company_type_name":null,"branch_address":null,"...":"12 more keys"}} - `GET /v3/lookup/cac/company/{id}/status-report` - [Status Report](https://docs.mono.co/api/cac/status-report) Parameters: id (path, required) ### Prove - `POST /v1/prove/initiate` - [Initiate Prove](https://docs.mono.co/api/prove/initiate) Parameters: customer.name (body, required), customer.phone (body, required), reference (body, required), kyc_level (body, required), bank_accounts (body, required), customer.email (body), customer.address (body), customer.identity.type (body), ... 2 more optional Request: {"customer":{"name":"Samuel Olamide","phone":"08100110000","address":"Lagos State","email":"samuel@neem.co","identity":"{...}"},"reference":"refId001","redirect_url":"http://mono.co","kyc_level":"tier_1","bank_accounts":false} Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-03-11T17:02:03.578Z","data":{"id":"ABCD123456","customer":"67d06c3870caa1576e35b218","mono_url":"https://prove.mono.co/ABCD123456","reference":"ref-100","redirect_url":"http://mono.co","bank_accounts":false,"kyc_level":"tier_1","is_blacklisted":false,"blacklist_count":0,"live_mode":true}} - `GET /v1/prove/customers/:reference` - [Fetch Customer Details](https://docs.mono.co/api/prove/fetch-customer-details) Parameters: reference (path, required) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-03-04T13:06:45.214Z","data":{"id":"PRVJM0POABY04","status":"active","reference":"ref-9","data_access":"{...}","personal_info":"{...}","identities":["..."],"accounts":["..."],"is_blacklisted":false,"blacklist_count":0}} - `GET /v1/prove/customers` - [Fetch All Details](https://docs.mono.co/api/prove/fetch-all-customer-details) Parameters: page (query) Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-03-11T17:36:34.408Z","data":["{...}"],"meta":{"total":8,"page":1,"previous":null,"next":null}} - `POST /v1/prove/customers/blacklist` - [Blacklist Customer](https://docs.mono.co/api/prove/blacklist-customer) Parameters: reference (body, required), reason (body, required), code (body, required) Request: {"reference":"customer_reference","reason":"blacklist_reason","code":"blacklist_code"} Response: {"status":"successful","message":"Customer already blacklisted","timestamp":"2025-03-11T17:44:47.841Z","data":{"message":"Customer already blacklisted"}} - `POST /v1/prove/customers/whitelist` - [Whitelist Customer](https://docs.mono.co/api/prove/whitelist-customer) Parameters: reference (body, required) Request: {"reference":"customer_reference"} Response: {"status":"successful","message":"Request completed successfully","timestamp":"2025-03-11T17:45:22.247Z","data":{"message":"Request completed successfully"}} - `DELETE /v1/prove/customers/:reference` - [Revoke Data Access](https://docs.mono.co/api/prove/revoke-data-access) Parameters: reference (path, required) Response: {"status":"successful","message":"Access to customer details revoked successfully","timestamp":"2025-03-14T12:36:52.909Z","data":{"message":"Access to customer details revoked successfully"}} ### Miscellaneous - `GET /v3/institutions` - [Bank Coverage](https://docs.mono.co/api/miscellaneous/bank-coverage) Parameters: type (query), country (query), scope (query), ... 1 more optional Response: {"status":"successful","message":"Request was successfully completed","timestamp":"2024-04-15T16:25:10.620Z","data":["{...}"]} ### Customer - `POST /v2/customers` - [Individual Customer](https://docs.mono.co/api/customer/create-a-customer) Parameters: email (body, required), first_name (body, required), last_name (body, required), address (body, required), phone (body, required), identity (body, required), identity.type (body, required), identity.number (body, required), type (body) Request: {"identity":{"type":"string","number":"string"},"email":"string","type":"string","last_name":"string","first_name":"string","address":"string","phone":"string"} - `POST /v2/customers` - [Business Customer](https://docs.mono.co/api/customer/create-a-business-customer) Parameters: email (body, required), type (body, required), business_name (body, required), address (body, required), phone (body, required), identity (body, required), identity.type (body, required), identity.number (body, required) Request: {"identity":{"type":"string","number":"string"},"email":"string","type":"string","business_name":"string","address":"string","phone":"string"} - `GET /v2/customers/{id}` - [Retrieve customer](https://docs.mono.co/api/customer/retrieve-a-customer) Parameters: id (path, required) Response: {"status":"successful","message":"Customer Data retrieved successfully","data":{"id":"6641af2a7c9ff1663be1d59b","name":"Samuel Olamide","first_name":"Samuel","last_name":"Olamide","email":"samuel@neem.co","phone":"08012345609","address":"23 shittu animashaun street","identification_no":"01234567801","identification_type":"bvn","bvn":"01234567801"}} - `GET /v2/customers` - [All customers](https://docs.mono.co/api/customer/list-all-customers) Parameters: page (query), phone (query), identity (query), ... 1 more optional Response: {"status":"successful","message":"Data retrieved successfully","data":["{...}"],"meta":{"total":187,"pages":38,"previous":null,"next":"https://api.withmono.com/v2/customers?page=2"}} - `GET /v2/customers/{id}/transactions` - [Customer transactions](https://docs.mono.co/api/customer/get-all-customer-transactions) Parameters: id (path, required), period (query, required), page (query, required), account (query) Response: {"status":"successful","message":"Data retrieved successfully","data":["{...}"]} - `GET /v2/accounts` - [All linked accounts](https://docs.mono.co/api/customer/fetch-all-linked-accounts) Parameters: account_number (query), page (query), name (query), ... 1 more optional Response: {"status":"successful","message":"Data retrieved successfully","timestamp":"2024-04-16T07:23:43.813Z","data":["{...}"],"meta":{"total":40,"pages":4,"previous":null,"next":"https://api.withmono.com/v2/accounts/?page=2"}} - `PATCH /v2/customers/{id}` - [Update customer](https://docs.mono.co/api/customer/update-a-customer) Parameters: id (path, required), address (body), phone (body), type (body), ... 6 more optional Response: {"status":"successful","message":"Customer updated successfully","data":null} - `DELETE /v2/customers/{id}` - [Delete customer](https://docs.mono.co/api/customer/delete-a-customer) Parameters: id (path, required) Response: {"status":"successful","message":"Deleted customer successfully","data":null} ### Lookup - `POST /v3/lookup/watchlist` - [Watchlist Screening](https://docs.mono.co/api/watchlist/submit-screening) Parameters: type (body, required), name (body, required), country (body, required), date_of_birth (body), gender (body), bvn (body), ... 1 more optional Response: {"status":"successful","message":"Request completed successfully","timestamp":"2026-03-24T10:43:39.831Z","data":{"id":"aml_scr_16934a4a4ea2bba9a7855b7f3f74714b","status":"processing"}} - `GET /v3/lookup/banks` - [Bank Listing (NIP)](https://docs.mono.co/api/lookup/bank-listing-nip) - `POST /v3/lookup/address` - [Address](https://docs.mono.co/api/lookup/address) Parameters: meter_number (body, required), address (body, required), disco_code (body, required) - `POST /v3/lookup/passport` - [Int'l Passport](https://docs.mono.co/api/lookup/intl-passport) Parameters: passport_number (body, required), last_name (body, required), date_of_birth (body, required) - `POST /v3/lookup/tin` - [TIN](https://docs.mono.co/api/lookup/tin) Parameters: number (body, required), channel (body, required) Request: {"number":"string","channel":"TIN"} Response: {"status":"successful","message":"Lookup Successful","timestamp":"2024-05-10T11:04:03.540Z","data":{"taxpayer_name":"NOMO NIGERIA LIMITED","cac_reg_number":"RC1234567","firstin":"12345075-0001","jittin":"123450756","nrs_tin":"2622431609295","tax_office":"LAGOS LAGOS","phone_number":"08180416589","email":"hi@nomo.com","address":"PLOT 1230, AHMADU BELLO WAY, VICTORIA ISLAND, LAGOS, NIGERIA","tin_type":"CORPORATE"}} - `POST /v3/lookup/nin` - [NIN](https://docs.mono.co/api/lookup/nin) Parameters: nin (body, required), output (query) Request: {"nin":"string"} Response: {"status":"successful","message":"NIN Lookup Successfull","timestamp":"2024-02-28T15:00:20.917Z","data":{"birthcountry":"nigeria","birthdate":"01-01-1990","birthlga":"Lagos Mainland","birthstate":"Lagos","educationallevel":"tertiary","email":"","employmentstatus":"employed","firstname":"WIGO","gender":"m","heigth":"150","maritalstatus":"single","middlename":"SAMUEL","...":"34 more keys"}} - `GET /v3/lookup/nin/{jobId}/job` - [Poll NIN Job](https://docs.mono.co/api/lookup/nin/job) Parameters: jobId (path, required) Response: {"status":"successful","message":"Job status fetched successfully","timestamp":"2025-12-10T12:42:44.264Z","data":{"id":"4","status":"completed","url":"https://api.withmono.com/v3/lookup/nin/f614.pdf"}} - `POST /v3/lookup/driver_license` - [Driver's License](https://docs.mono.co/api/lookup/drivers-license) Parameters: license_number (body, required), date_of_birth (body, required), first_name (body, required), last_name (body, required) Request: {"license_number":"string","date_of_birth":"string","first_name":"string","last_name":"string"} Response: {"status":"successful","message":"Lookup Successful","timestamp":"2024-02-28T15:00:20.917Z","data":{"gender":"Male","photo":"/9j+5tAFgcMefpRTuI/9k=","license_no":"AAD23208212298","first_name":"Samuel","last_name":"Olamide","middle_name":null,"issued_date":"2020-06-01","expiry_date":"2030-06-01","state_ofIssue":"LAGOS","birth_date":"2020-06-01"}} - `POST /v3/lookup/account-number` - [Account Number](https://docs.mono.co/api/lookup/account-number) Parameters: nip_code (body, required), account_number (body, required) Request: {"nip_code":"string","account_number":"string"} - `POST /v3/lookup/credit-history/{provider}` - [Credit History](https://docs.mono.co/api/lookup/credit-history) Parameters: provider (path, required), bvn (body, required) Request: {"bvn":"224*****012"} Response: {"status":"successful","message":"Report Fetched Successfully","timestamp":"2024-02-28T15:00:20.917Z","data":{"providers":["..."],"profile":"{...}","credit_history":["..."]}} - `POST /v3/lookup/mashup` - [Mashup](https://docs.mono.co/api/lookup/mashup) Parameters: nin (body, required), bvn (body, required), date_of_birth (body, required) Request: {"nin":"string","bvn":"string","date_of_birth":"string"} ## Common Use Cases - Lending: Use Connect (Financial Data) to retrieve bank statements, assess income, and evaluate creditworthiness before issuing loans - Banking / Neobanking: Use Lookup for KYC onboarding, Connect for account aggregation - Payments / Collections: Use DirectPay for one-time charges, Direct Debit for subscriptions and recurring billing - Wealth Management: Use Connect to analyze users' financial behaviour for personalized services - Accounting: Use Connect to pull real-time transactions for invoicing and bookkeeping - Payroll / Vendor Settlements: Use Disburse for bulk salary payments, vendor payouts, or cashback distribution ## Key Integration Patterns 1. Authentication: All server-side API calls require the `mono-sec-key` header. Widget initialization uses the public key. 2. Webhooks: Most operations are asynchronous. After initiating an action, listen for webhook events to get results. Always verify webhooks using the `mono-webhook-secret` header. 3. Customer Object: For Payments and Connect (Financial Data) products, create a Customer first using `POST /v2/customers` with BVN identity verification. 4. Account Linking Flow: For Financial Data, use the initiate endpoint to get a `mono_url`, then wait for `mono.events.account_connected` and `mono.events.account_updated` webhooks before calling data endpoints. 5. Mandate Flow: For Direct Debit, create a mandate -> share authorization link -> wait for `events.mandates.approved` -> wait for `events.mandates.ready` (24h after approval) -> automatic debits begin. 6. Sandbox Testing: Use test secret keys (prefixed `test_sk_`) and sandbox credentials listed in the sandbox documentation to test without real transactions.