This feature allows you to generate a virtual account for your customers. The account number generated is dedicated to a customer and every payment to that virtual account is associated with the customer for which the account was reserved.
These accounts are very useful for merchants whose;
Customers can only pay for a single service: This is common for electricity companies, internet service providers, etc. The account reserved for the customer in this scenario allows them to pay for a service by doing a simple transfer to their reserved account and the payment is confirmed.
Businesses that involves the use of a wallet: Here, an account number is reserved for each customer's wallet to enable them to top up by simply transferring to that account. Examples of this are Super Agents, Investment Applications, Betting Platforms, Logistics Applications, etc.
For virtual accounts generated in Sandbox, Use the Monnify Payment simulator to complete test payments. Real transactions are not supported in Sandbox mode.
You can generate a reserved account for your customers by making a POST request to the Reserve an Account API.
Once the account is created, the customer can then make payments to the reserved account at any time.
Once the transfer is made by the customer, the partner bank gets notified, Monnify is notified and the merchant is then notified of the transaction on the account
The transaction details along with the account reference for the transaction is made available to the merchant.
If you want to reserve accounts across all partner banks for your customers, you will need to pass “true” for the “getAllAvailableBanks” field. For now, Moniepoint bank accounts are the default virtual accounts.
1"Content-Type":"application/json",
2"Authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
1{
2 "accountReference": "abc123",
3 "accountName": "Test Reserved Account",
4 "currencyCode": "NGN",
5 "contractCode": "8389328412",
6 "customerEmail": "[email protected]",
7 "bvn": "21212121212",
8 "customerName": "John Doe",
9 "getAllAvailableBanks": true
10}
1{
2"requestSuccessful": true,
3"responseMessage": "success",
4"responseCode": "0",
5"responseBody": {
6 "contractCode": "8389328412",
7 "accountReference": "abc1234",
8 "accountName": "Tes",
9 "currencyCode": "NGN",
10 "customerEmail": "[email protected]",
11 "customerName": "John Doe",
12 "accounts": [
13 {
14 "bankCode": "50515",
15 "bankName": "Moniepoint Microfinance Bank",
16 "accountNumber": "6254727989",
17 "accountName": "Tes"
18 }
19 ],
20 "collectionChannel": "RESERVED_ACCOUNT",
21 "reservationReference": "NWA7DMJ0W2UDK1KN5SLF",
22 "reservedAccountType": "GENERAL",
23 "status": "ACTIVE",
24 "createdOn": "2023-04-14 12:04:39.034",
25 "incomeSplitConfig": [],
26 "bvn": "21212121212",
27 "restrictPaymentSource": false
28}
29}
Monnify invoice reserved account allows you to reserve an account for your
customers to whom you send invoices to regularly. This account can be attached
to invoices being generated for a customer so that the same account number is
received for every invoice peculiar to that customer.
These accounts are slightly different from regular customer reserved accounts as customers cannot pay into these accounts until they are attached to an invoice. Basically, the account number is inactive until when attached to an invoice and returns to it's inactive state when the invoice is paid.
See Invoice Reserved-Account API for details on how to implement one.
To create reserved account via the Monnify dashboard, kindly navigate to the reserved account section, click on the “create new” button and populate the fields shown in the image below;
The incomeSplitConfig field allows you to use split payments with your reserved accounts by specifying one or more sub-account(s) and a specific percentage of each payment to be credited into each sub-account. IncomeSplitConfig is an array of objects so you can split into multiple sub-accounts per transaction.
1{
2"accountReference": "abc123",
3"accountName": "Test Reserved Account",
4"currencyCode": "NGN",
5"contractCode": "8389328412",
6"customerEmail": "[email protected]",
7"customerName": "John Doe",
8"bvn": "21212121212",
9"nin": "12034875601",
10"getAllAvailableBanks": true
11"incomeSplitConfig": [
12 {
13 "subAccountCode": "MFY_SUB_319452883228",
14 "feePercentage": 10.5,
15 "splitPercentage": 20,
16 "feeBearer": true
17 }
18 ]
19}
You can establish a limit on a customer's account using the Transaction Limit APIs. This means that on a customer's account, you can specify the maximum amount per transaction, the maximum number of transactions per day, and the total amount per day.
To do so, you will need to create a Limit Profile and use the Limit Profile code to assign customers to the limit profile.
In managing Transaction Limits, you can do the following
Reserve Account with Limit: You can create a reserved account on Monnify and creating a limit profile on the account. It works similar to creating a reserve account, except that a limit profile code in included in the request to create the reserved account. See Reserve Account with limit API
Get Limit profiles: The Get Limit Profile API helps you get a list of all the limit profiles you have created.
Merchants are able to restrict source accounts that can fund a reserved account using either BVNs or Account Name or Account Number. This is mandatory if the restrictPaymentSource request parameter is set to true.
This feature is useful for merchants in a regulated business category, where only the authorized user(s) of a reserved account should fund the reserved account, to allow more payment sources, only BVNs will be used to allow more payment sources other than the default customerBvn already on a reserve account.
The rule application is as follows:
1{
2"accountReference": "abc123",
3"accountName": "Test Reserved Account",
4"currencyCode": "NGN",
5"contractCode": "8389328412",
6"customerEmail": "[email protected]",
7"customerName": "John Doe",
8"bvn": "21212121212",
9"restrictPaymentSource": true,
10"allowedPaymentSources": {
11 "bvns": ["21212121212", "20202020202"],
12 "bankAccounts": [
13 {
14 "accountNumber": "0068687503",
15 "bankCode": "232"
16 },
17 {
18 "accountNumber": "2048714015",
19 "bankCode": "057"
20 }
21 ],
22 "accountNames": ["SAMUEL DAMILARE OGUNNAIKE"]
23}
24}
1{
2"requestSuccessful": true,
3"responseMessage": "success",
4"responseCode": "0",
5"responseBody": {
6 "contractCode": "8389328412",
7 "accountReference": "abc123",
8 "accountName": "Tes",
9 "currencyCode": "NGN",
10 "customerEmail": "[email protected]",
11 "customerName": "John Doe",
12 "accounts": [
13 {
14 "bankCode": "50515",
15 "bankName": "Moniepoint Microfinance Bank",
16 "accountNumber": "6254727989",
17 "accountName": "Tes"
18 }
19 ],
20 "collectionChannel": "RESERVED_ACCOUNT",
21 "reservationReference": "NWA7DMJ0W2UDK1KN5SLF",
22 "reservedAccountType": "GENERAL",
23 "status": "ACTIVE",
24 "createdOn": "2023-04-14 12:04:39.034",
25 "incomeSplitConfig": [],
26 "bvn": "21212121212",
27 "restrictPaymentSource": true,
28 "allowedPaymentSources": {
29 "bvns": ["21212121212", "20202020202"],
30 "bankAccounts": [
31 {
32 "accountNumber": "0068687503",
33 "bankCode": "232"
34 },
35 {
36 "accountNumber": "2048714015",
37 "bankCode": "057"
38 }
39 ],
40 "accountNames": ["SAMUEL DAMILARE OGUNNAIKE"]
41 }
42}
43}
The Update Kyc Info API allows merchants to link a customer's BVN and/or NIN to their respective static reserved account.
The API accepts either the customer’s BVN or NIN or both, subject to the following merchant requirements:
For accounts that wish to enjoy the maximum transaction limit, both BVN and NIN must be linked to the reserved account.
For accounts with limited transaction amounts, one of NIN or BVN is required.
Error Message | Meaning | Action |
---|---|---|
You can not reserve two accounts with the same reference. | The accountReference parameter in the request payload has already been used by you. | Retry with a unique accountReference |
You cannot reserve more than 1 account(s) for a customer. Please contact support for assistance. | There is an exisiting active reserved account generated with this customerEmail. | Kindly share exsting account details with your customer. |
Invalid contract code supplied. | The contractCode in the request parameter is not correct or it doesn’t belong to the merchant. | Navigate to the "Settings > Contract Setup", section of your Monnify dashboard to get your contact code |
Is invalid. Must be 11 digits | This most times implies that the BVN provided is invalid | If BVN/NIN is supplied, confirm that it has the required length |
BVN or NIN is required. | BVN and NIN were not supplied in the request payload. | Retry with the BVN and/or NIN details of the customer. |
Unknown currency code supplied. | The currency code supplied is not valid or supported | Reconfirm the currency code supplied |
We do not support virtual accounts from banks with code XXX. | This implies that we do not create virtual account for some of the bank codes passed in the preferredBanks array | Retry with any of the supported bank codes |
Unknown sub account code XXXXXXX. | The happen when using the incomeSplitConfig and the sub account doesn’t belong to the merchant. | Kindly confirm from the SubAccount section of your Monnify dashboard if the subAccount being used exists there |
R42 | You cannot reserve more than 1 account(s) for a customer. Please contact support for assistance. | Kindly use unique customer email when generating reserved account |
How would you rate your experience?