Changelog

We're excited to announce the release of Split Payments, a feature that allows businesses to seamlessly allocate transaction amounts across multiple accounts during payment processing.

With this update, the split object has been introduced as an optional body parameter for both the Initiate Payment API and the Direct Debit API. This ensures a uniform implementation for handling split payments across one-time and recurring transactions.

Key Features of Split Payments

• Distribute payments based on percentage or fixed values.
• Support for multiple recipients via a distribution array.
• Define the fee bearer as either the business or the sub-accounts, enabling control over payout-related fees.
• A standardized split object structure is now supported across both one-time payments and direct debit transactions, making it easier to integrate and manage.

How to Use

Firstly, create one or multiple sub-account via here for which payouts'splits will be made into.

Next, proceed to simply include the split object in your API request body with the desired distribution details. This feature is entirely optional; if omitted, transactions proceed as usual without splits. When processed, a settlement webhook (direct_debit.split_settlement_successful) will be sent.

For more details, please refer to this updated API documentation here

We updated the Income webhook (mono.events.account_income) with 3 new fields in the summary response payload.

• Total Income (total_income): The total monthly average from all streams

• Annual Income (annual_income): The total monthly average from all streams from the last 12 months.

• Monthly Income (monthly_income): The total monthly average from all streams from the last 12 months/ total number of streams.

For more details, please refer here

Enhanced the Real-Time Data feature for better performance and efficiency

Key Features: Response headers now include:

• x-job-id : Unique job identifier.
• x-job-status: Provide job progress (FINISHED, PROCESSING, FAILED).

Webhooks:

• mono.accounts.jobs.update: Sends job status i.e. SUCCESSFUL, FAILED, REAUTHORISATION_REQUIRED.

New Endpoint:
You can now check job status using the real-time job status endpoint

We’ve added extra fields for DirectPay successful webook transactions, to indicate suspicious transactions and held settlements.

• flagged: indicates if a transaction has been flagged as suspicious

• flag_reasons: displays the reason why this transaction is considered suspicious

• held_settlement: indicates if the settlement for this transaction has been withheld pending review. This is explained below

1. We’ve added custom debit frequency on our mandate creation endpoint to allow partners to customize how far apart debits can happen on a fixed mandate. Beyond the standard daily, weekly, bi-weekly, monthly, and yearly options, we have introduced custom-frequency types such as 'days', 'weeks', 'months'. This update comes with a newly introduced request field 'interval' which expects any whole number (e.g., 1, 5) that accompanies custom-frequecies above. You can read here for details on this update.

2. We have also added a new 'processing' status for DirectDebit transactions . The processing status is to allow for confirmation of pending transactions with NIBSS after the Debit Account API has been called.

The processing webhook (events.mandates.debit.processing) is now sent to indicate a debit transaction is in a pending state. When the transaction is finally confirmed as successful or failed, the respective webhook is sent and the status will be updated.

The Creditworthiness API [/credit-worthiness] provides summary information about the affordability status calculated against the loan amount requested by a borrower. This is based on preset variables, such as the principal amount, interest rate, tenor and existing credit history, included in the API request and compared against the user's financial transactions.

This enables your lending or financing business to tailor loans or credit to the repayment capability of your customers and minimize the risk of non-repayment.

The response received includes the account ID of the user's linked financial account, months assessed, summary information confirming the affordability status and expected monthly payment and also the user's total outstanding debt retrieved from the credit bureau.

We are pleased to announce an update to our Direct Debit API that improves the mandate authorization process for users with an existing approved mandate in the Mono Network. This update introduces the following enhancements:

• Mandate OTP Verification: For users who already have an approved mandate in the Mono Network, the process for authorizing new mandates now includes OTP verification. After initiating a mandate, the otp_destinations field will be included in the response, indicating the available methods (e.g., phone or email) for receiving the OTP.

• Consistent Request Body: The request body for creating mandates remains the same. The new addition is the otp_destinations field in the response to allow users to choose their OTP delivery method.

• New OTP Verification Endpoint: A new endpoint, Verify Mandate OTP API, has been introduced. This endpoint manages the OTP verification process. Users must verify the OTP received through their chosen method to finalize and approve the mandate setup.

Updated the /NIN-Lookup endpoint to perform validation on individual using Registered Phone Number.

We have implemented an additional international passport layer that requires a date of birth field and provides validation information exclusively on the Int'l Passport API. Partners can utilize this feature if they encounter an error during the initial passport verification attempt.

Added the customer creation endpoint for creating a business customer. You can now pass business_name and type amongst other details in the customer endpoint when creating a customer that is a business.

We've made a significant improvement to our Direct Debit API product, specifically targeting the e-mandate processing time. The ready-to-debit time for e-mandates has been reduced from the previous 8-10 hours to less than 1 hour. This enhancement means that once a mandate is created and approved, it will be ready for debiting much more quickly, ensuring faster processing times for your transactions. A ready-to-debit webhook event is sent to confirm account debit readiness.

For example, if a mandate is created and approved at 4:00 PM, it will now be ready for debiting by 5:00 PM. This improvement is designed to streamline your operations and enhance the efficiency of the mandate process.

A) Data Enrichment APIs

New Releases

We're excited to announce the release of our Data Enrichment APIs, designed to provide deeper financial insights into your customers' financial accounts. Through functionalities such as transaction categorization, metadata addition, and statement insights generation, these APIs offer valuable tools to improve financial decision-making and streamline transaction analysisprocesses.The Data Enrichment APIs include:

Transaction Categorisation

This API helps categorize user transactions into predefined categories, making it easier to analyze and understand spending habits. It allows you to categorize transactions linked to an already connected bank account marked as null or upload your transactions for categorization. The endpoints released in this category are:

• Initiate Transactions Categorising Endpoint 🔗: Starts the process of categorizing transactions for a connected account.
• Categorisation Upload Batch Endpoint 🔗: Allows uploading a file of transactions to be categorized.
• Retrieve Categorised Transactions Endpoint 🔗: Fetches the categorized transaction records for a specified account.

Transaction Metadata

The Transaction Metadata API allows you to enrich transaction data with additional metadata, providing more context and details about each transaction. This can help in more accurate analysis and reporting. The key endpoints in this API are:

• Initiate Transactions Metadata Endpoint 🔗: Begins the metadata enrichment process for transactions of a connected account.
• Metadata Upload Batch Endpoint 🔗: Allows uploading a file for batch updating transaction metadata.
• Retrieve Metadata Records Endpoint 🔗: Retrieves metadata-enriched transaction records for a specified account.

Statement Insights

The Statement Insights API analyzes all transactions linked to a provided account ID, returning detailed insights based on the transaction data. This helps in understanding spending patterns, financial health, and unusual activities. The endpoints released in this category are:

• Initiate Statement Insights Endpoint 🔗: Initiates the process of generating statement insights for a connected account.
• Retrieve Statement Insights Records Endpoint 🔗: Retrieves all statement insights records linked to a particular account.

B) Income API

New Releases

In addition to our Data Enrichment APIs, we have also launched our Income API. This API provides a comprehensive view of income streams and patterns for users, enabling better financial management and insights. The endpoints released under this API are:

• Initiate Income Request Endpoint 🔗: Fetches detailed income information for a user, including income summary, income streams, and historical income data.
• Retrieve Income Details Endpoint 🔗: Retrieves a list of all income streams associated with a user's account.

Updated the /TIN-Lookup endpoint to perform verification for both individuals and businesses.

Released Business Accounts E-mandates which allows you to authorise mandates on business accounts using the e-mandate authorisation type when creating or initiating mandate authorisation.

Released Fixed Recurring Mandate which allows you to set a fixed amount for both signed and e-mandates when creating or initiating mandate authorisation.

Updated all the response data field for /BVN-Lookup from camelcase to snake_case to maintain consistency and data integrity across our APIs. Also released sandbox environment for when scope is bank_accounts.

Added an optional institution object to the body request of our /Initiate-Account-Linking and /Payment-Initiation APIs. This enhancement enables you to direct your users to the login page of any financial institution upon opening the generated URL. The institution object contains the id, auth_method, and account_number fields.

For implementation details with Mono Connect, refer to this link and for DirectPay, visit here.

Released /Mashup-Lookup-API API which enables you to verify both the NIN, BVN and date of birth of the user in one single API call for seamless KYC verification, for mono lookup.

The request requires bvn, nin, and date_of_birth fields, all mandatory for successful lookup

Released Retrieve mandate via Reference API, which allows you to retrieve details of both signed and e-mandates using the unique reference that you passed on mandate creation.

We have upgraded our Mono Connect and DirectPay APIs to a new version and introduced new endpoints that complement version 2 (/v2) of the Mono Connect and DirectPay widgets. This update also includes the addition of the Customers APIs, expanding the customer management capabilities within Mono's ecosystem.

N.B: Please be informed that the version 1 (/v1) APIs will remain accessible until the end of May 2024.

A) Customer Resource

New Releases

We've launched our Customers’ endpoints, enabling businesses and developers to create and manage customer entities within the Mono ecosystem efficiently.

These Customer Resource endpoints support smooth onboarding procedures and optimize Know Your Customer (KYC) verifications. At the heart of the Customer resource lies our Create a Customer Endpoint, which requires user details including name, email, residential address, phone number, and BVN number.

Upon successful creation of the customer entity on your platform, Mono can aggregate accounts associated with the same customer based on the account name and BVN or email, as well as payments processed by them.

The customer resource also enables you to fetch all Customer's Endpoint, Get Customer Transactions Endpoint etc. The endpoints released in this resource are:

• Create a Customer Endpoint [🔗]: This endpoint allows businesses to create a customer profile, providing a customer object/ID essential for Connect and DirectPay v2 endpoints, ensuring seamless integration in the Mono-product ecosystem.

• Retrieve a Customer Endpoint [🔗]: Fetch details of a specific customer using their ID, including personal details, and transaction history.

• List all Customers Endpoint [🔗]: Retrieve a comprehensive list of all registered customers, facilitating efficient management and analysis of your customer base.

• Get Customer Transactions Endpoint [🔗]: Access transaction details of a specific customer by specifying their ID, including amounts, dates, and descriptions.

• Fetch all Linked Accounts Endpoint [🔗]: Retrieve a list of all linked accounts associated with a customer, offering visibility into their financial profile for enhanced management and analysis.

• Update a Customer Endpoint [🔗]: This endpoint is to update the profile of your customer via the Customer ID. It's particularly useful when you need to update the address, phone or BVN information.

• Delete a Customer Endpoint [🔗]: This endpoint deletes a custoemr entity that has been created by your business. Once deleted, such customer entity cannot be recovered.

B) General Changes on Upgraded APIs

• URL Endpoint Version Update: Mono Connect and DirectPay URLs have been upgraded to /v2/ for improved performance, including faster responses and reduced latency, and to accommodate new features and enhancements; https://api.withmono.com/v2.

• Data Format Changes: The new upgrades introduce changes in data formats and structures to enhance compatibility, better organize information, and present data in a more developer-friendly manner. In addition, each response now includes a timestamp field, which is beneficial for debugging and troubleshooting. Developers can associate data with specific timestamps, thereby improving their ability to pinpoint root causes. This precise error timing also facilitates effective resolution when issues arise.

• Endpoints Impacted by Recent Updates

• The following endpoints under Mono Connect have been impacted by the recent upgrades (i.e URL Endpoint Version Update and Data Format Changes) shared above:

• Exchange Token endpoint, Account Information endpoint,Transactions endpoint, Identity endpoint, Unlink endpoint, Statements endpoint, Poll PDF Status endpoint, Assets endpoint and Earnings endpoint

• Mono Directpay endpoints have been impacted by the recent upgrades:

• Initiate Payments Link endpoint, Verify Payment API and Fetch all Payments API

C) Mono Connect API

New Releases

• Initiate Account Linking/Reauth Endpoint: This generates a URL that enables your users to complete the account linking or reauthorization process without having to set up an SDK. Key advantages of this service is that the generated URL can be opened either in a browser or via a webview for mobile, regardless of the platform. Also, it eliminates the need for the Mono Connect SDK setup and simplifies the integration process for you. [🔗]

• Account Balance Endpoint: This endpoint provides only the account balance of a user’s connected account for Mono Connect. [🔗]

D) Mono DirectPay API

New Releases

• Payout Endpoint: Retrieve all payout details based on the status that could be either pending, under_limit, processing, settled, or failed. [🔗]

• Payout Transactions Endpoint: This service allows you to use the accountId and PayoutId to retrieve the status of all payout transactions. [🔗]

• Refund Payment Endpoint: This endpoint allows you to initiate refunds for payments to customers. [🔗]

New updates

Initiate a Payment Endpoint: The "Initiate a Payment" endpoint now necessitates a customer object (customer) in the payload request. This object either requires the Customer ID id field or the customer's name (name) and email address (email) fields. [🔗]

Updated the endpoint URL for our Account number Lookup. It was changed from /v3/lookup/account_number to the new /v3/lookup/account-number.

We released a new patch version for our Mono Connect.js SDK. This update introduces fixes for OPay Facial Recognition and copying virtual account numbers from the widget. The patch is also backwards compatible with our v1 widget.

N.B: This is a minor change and doesn't require updates to the core integration code.

This patch is released in two versions:

• SDK Version 0.2.5 [backward compatibility with v1]
• SDK Version 2.0.2

Changes in This Release

General Changes

• Browser not triggering Camera for Opay Facial recognition [RESOLVED]: We have significantly improved how the SDK handles triggering camera access. This ensures a smoother experience for end-users during the facial recognition process.

• Copy account number icon wasn’t working [RESOLVED]: We also pushed a fix which addresses the copy icon not copying the generated account number for payments via transfer.

SDK Version 0.2.5

• Widget Version Switching: Developers who wish to retain the ability to switch between the v1 and v2 widgets must update to SDK version 0.2.5. This version maintains compatibility with both widget versions, allowing you to choose the most suitable option for their needs.

SDK Version 2.0.2

• Permanent v2 Widget Loading: For developers looking to fully transition to the newer version of the widget, updating to SDK version 2.0.2 is recommended. This update permanently loads the v2 widget, leveraging its enhanced features and improved performance.

Updating Your SDK

• If you are currently using older versions of the SDK, you are encouraged to update to either version 0.2.5 or 2.0.2 based on your requirements. To update, follow the commands below:

• SDK Version 0.2.5
  npm install @mono.co/connect.js@0.2.5

• SDK Version 2.0.2
  npm install @mono.co/connect.js@2.0.2

Major upgrade to the Mono widget; version 2 of the Mono Connect and DirectPay widget are now live. New features include:

• Key consent updates for end-users
• Faster account linking and payment experience
• Widget testing in sandbox for various flows, without sandbox login details
• Improved institution search and new institution request Read the announcement for more details.

Upgrading to the new widget:

• Introducing 'customer object' field: This introduces identification capabilities and is required to be passed with each connection request. Details such as user's name and email should be passed in the customer object field.
• This applies to both API and SDK integrations.

Please read the Financial data integration guide and the SDK integration guide for more details. The Mono widget v1 will remain available for use until May 2024

Deprecated our Partners API, which previously facilitated the creation of custom or white-labeled solutions using our Mono Connect and Directpay APIs.

Updated our CAC Lookup API, enhancing it to provide additional information such as Previous Address, Change of Name, Lookup a Secretary, and Lookup a Director. The Lookup a business and Shareholder details endpoints have also been upgraded to version V3, enriching the returned CAC details with more robust data.

• Deprecated our 360 API, which previously previously returned all the bank accounts linked to the BVN or phone number been specified.

• Updated our BVN Lookup API to now return all available bank accounts connected to a valid Bank Verification Number (BVN) with user's consent.

Released our Credit History Lookup API for retrieving credit history information of users with Mono Lookup.

1.) Upgraded our Account Number Lookup API for account number verification, for Mono Lookup.

2.) Released the NIP Bank Listing API to provide NIP bank coverage which contains the bank name, bank code and nip code for each individual bank object, for Mono lookup.

Released the Delete a Customer API for recurring payments, which allows you to delete a single customer, for Mono Directpay.

Released Mono Direct Debit (MDD) APIs, which empowers you as a business to seamlessly collect variable payments from your customers, on an ongoing basis from all major Nigerian banks through a unified API integration, for Mono Directpay.

Upgraded the /bank-account-details, /transactions and /statements API in Mono Connect to a new version (/v1), which allows businesses and developers to retrieve real-time financial data from your customer's linked account. This upgrade introduces a new truthy parameter in the request headers as x-realtimeas well as x-reauth-required (indicates if reauthorization by the end-user is required) and x-has-new-data (indicates if new data was fetched) in the response headers. You can learn more on this real-time data feature here. Note that the API previous versions are still backward compatible.

Released /lookup-drivers_license API, which enables you to look up and verify the driver's license information and identity of your users.

Released /lookup-passport, /lookup-house-address, /lookup-nin and the /lookup-tin APIs which enable you to verify international passports, perform house address verification checks and verify NIN identification and also verify tax identification number of your users and business, for mono lookup.

Added a new feature to the "Verify BVN OTP" API endpoint, enabling users to provide an alternative phone number that is not on their BVN record. To utilize this feature, you can include the alternate_phone parameter in the method field, along with the new phone_number field we've introduced, for mono lookup.

Released Transaction Metadata V2, introducing an expanded range of categories for transaction classification and improved accuracy and precision of the Transaction Classifier model. This enhancement empowers developers to build powerful financial applications with reliable transaction classification results.

Upgraded the 360view endpoint in our Lookup product suite for businesses in Nigeria. This upgrade allows businesses and developers to access a comprehensive view of all the bank accounts registered with their customers using their phone number or Bank Verification Number (BVN). The endpoint now returns all the users' bank accounts, supports multiple modes (phone or BVN), and provides bank meta information such as logos.

Deprecated the BVN lookup API (Legacy) which allows for the verification and access of your customer's BVN identity information, for mono lookup.

Released /initiate-bvn-consent, /verify-bvn-otp and the /fetch-bvn-details API for our BVN Lookup (Consent) which provides access to an individual's Bank Verification Number (BVN) information, with their explicit consent, for mono lookup.

Added an optional meta object field on the request body of the /create a virtual card API to include additional card creation information, for mono issuing.

Added the virtual account liquidation successful webhook event (issuing.virtual_account_liquidated) which gets sent a virtual account has been liquidated successfully, the virtual account liquidation failed webhook event (issuing.virtual_account_liquidation_failed) which gets sent when a virtual account fails to get liquidated and the card liquidation failed webhook event (issuing.virtual_card_liquidation_failed) which is sent when a virtual card fails to get liquidated, for issuing.

Updated the status of the liquidate card balance API response to processing pending a successful liquidation. To check if the status is successful, you can set up webhooks to monitor this. Alternatively, you can use the transaction_id from the API response to a query the transaction status via the /fetch a transaction API for mono issuing.

Deprecated the /credit a virtual account API which transfers from your issuing wallet to a virtual account, for mono issuing. Wednesday, 19th

Added the transaction_id field to the /transfer to issuing wallet, /fund a virtual card and the /liquidate card balance API responses, to later query the transaction status via the /fetch a transaction API for mono issuing.

Added the transaction field to the card liquidation webhook event payload (issuing.virtual_card_liquidated) for mono issuing, so as to retrieve the transaction id when a virtual card gets liquidated.

Released the /fetch interchange payouts API to fetch interchange revenue that is either pending or settled to your business, for mono issuing. It is only available for USD cards.

Added the interchange_revenue field to the /fetch a transaction, /fetch all transactions and the /fetch card transactions API responses, to fetch interchange revenue amount on a USD card transaction for mono issuing.

Added the card transaction failed webhook event (issuing.card_transaction_failed) for issuing, which gets sent when a USD or NGN card could not be charged or card funding fails.

Added the fee field to the /fetch all transactions API, /fetch a transaction API and /fetch card transactions API for issuing.

Added the country field to the /create account holder API to support the creation of international account holders in Ghana, Kenya, South Africa, Uganda, and Rwanda for issuing.

Released the /transfer to issuing wallet API on our virtual accounts to move the balance entirely or partially to Issuing wallet, for mono issuing.

Updated the response field in the /fetch USD exchange rate API to return the liquidation rate, for mono issuing.

You can now retrieve telco data from your customers via the newly released Telco Data API. The Telco data API is the easiest way to retrieve data from any active phone number in Nigeria. Click here to learn more.

Released the /freeze, /unfreeze, /delete, and /liquidate card balance API functionalities on our NGN virtual cards, for mono issuing.

Updated the narration response field in the issuing.card_transaction webhook event to include the merchant name, when a card transaction is made for a NGN virtual card, for mono issuing.

Updated the billing address object in the response field of the Fetch card details API event to include the city field, for mono issuing.

Released the /liquidate card balance API on our USD virtual cards to move balance completely or partially, for mono issuing.

Released the /set wallet threshold API functionality to set wallet thresholds for issuing wallets (USD and NGN) so as to get email notifications when your wallet is running low (below-set thresholds) and deficient (zero balance) and [/fetch wallet transactions](Get Wallet Transactions) to get wallet related transactions, for mono issuing.

Updated the body params on the Create and Update Account Holder APIs, for the business details object to include three optional fields which are director_first_name, director_last_name, rc_number. Also, cac_id is now optional as we are using both rc_number and cac_id for backward compatibility depending on which is available from a business, for mono issuing.

Released new issuing bank account endpoints to issue bank accounts to your customers. The API endpoints released are /Create a Bank account, /Fetch a Bank Account, /Fetch a Account Balance, /Fetch Transactions, /Fetch Bank Accounts, /Transfer between Accounts, /Transfer to other Accounts and /Mock Transaction, for mono issuing.

Released the /Sub Account API functionality to for the deposit virtual accounts, for mono issuing.

Updated the /credits and /debits API to return a transaction count for each returned month to enable lenders and partners to filter the average amount per transaction easily and also a simpler alternative to the inflow endpoint for mono connect.

Updated the /sync API to return a new INCOMPLETE_STATEMENT_ERROR error, whenever a financial institution inefficiently returns transaction data that is less than the usually recorded transactions, when Data sync is initiated manually.

Updated the /statement API to return a meta object which contains both a requested_length (in days) and available_length (in days) for mono connect.

Updated payment initiation method via the widget to receive a payment id from the payment initiation API in the data object callback for mono directpay.

Released /v1/payments/transactions API to fetch all payments that have been initiated, with query lookup params such as page, start, end, status, account and customer.

Added the payment authorised webhook event (direct_debit.payment_authorised) for directpay, which gets sent as soon as payment is completed or a standing order has been set up.