Customer Reserved Account

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;


  1. 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.
  2. 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.

How does Customer Reserved Account work?

  1. You can generate a reserved account for your customers by making a POST request to the Reserve an Account API.
  2. Once the account is created, the customer can then make payments to the reserved account at any time.
  3. 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
  4. The transaction details along with the account reference for the transaction is made available to the merchant.

Request Headers

json
Copy button
"Content-Type":"application/json",
"Authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Request Body

json
Copy button
{
"accountReference": "abc123",
"accountName": "Test Reserved Account",
"currencyCode": "NGN",
"contractCode": "8389328412",
"customerEmail": "[email protected]",
"bvn": "21212121212",
"customerName": "John Doe",
"getAllAvailableBanks": true
}

Reserve Account Response Body

json
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "8389328412",
"accountReference": "abc1234",
"accountName": "Tes",
"currencyCode": "NGN",
"customerEmail": "[email protected]",
"customerName": "John Doe",
"accounts": [
{
"bankCode": "232",
"bankName": "Sterling bank",
"accountNumber": "8952095784",
"accountName": "Tes"
},
{
"bankCode": "035",
"bankName": "Wema bank",
"accountNumber": "7206930470",
"accountName": "Tes"
},
{
"bankCode": "50515",
"bankName": "Moniepoint Microfinance Bank",
"accountNumber": "6254727989",
"accountName": "Tes"
},
{
"bankCode": "058",
"bankName": "GTBank",
"accountNumber": "0784829227",
"accountName": "Tes"
}
],
"collectionChannel": "RESERVED_ACCOUNT",
"reservationReference": "NWA7DMJ0W2UDK1KN5SLF",
"reservedAccountType": "GENERAL",
"status": "ACTIVE",
"createdOn": "2023-04-14 12:04:39.034",
"incomeSplitConfig": [],
"bvn": "21212121212",
"restrictPaymentSource": false
}
}


Invoice Reserved Account

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.

See Reserve an Account API for details on how to implement one.



Reserved Account Creation on Monnify Dashboard

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;


Transaction Limits

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

  1. Create Limit profiles: The Create Limit API, allows you to set a limit on a customers account. Once the POST request has been made to this endpoint, a limit profile code is returned. This code becomes the unique identifier for the limit profile created, and will be used to reference the limit profile in reserve account requests.
  2. Update Limit profile: To make updates to any limit profile you have created, you are required to make a PUT request to the Update Limit Profile API, providing updates such as, the single transaction value, daily transaction volume and daily transaction value.
  3. 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
  4. Get Limit profiles: The Get Limit Profile API helps you get a list of all the limit profiles you have created.
  5. Update Reserve Account Limit: The Update Reserve Account Limit API helps you update the information on an existing limit profile created for a reserved account.

BVN Restrictions

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. If only account numbers are specified, funding of account will be restricted to specified account numbers.
  2. If only account names are specified, funding of account will be restricted to specified account names.
  3. If both account numbers and account names are specified, funding will be permitted when either of the two rules match, i.e. source account number matches specified account numbers or source account name matches specified account name.

Sample Request

json
Copy button
{
"restrictPaymentSource": true,
"allowedPaymentSources": {
"bvns": [
"21212121212",
"20202020202"
]
}

Sample Response

json
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"restrictPaymentSource": true,
"allowedPaymentSources": {
"bvns": [
"21212121212",
"20202020202"
],
"bankAccounts": [
{
"accountNumber": "0068687503",
"bankCode": "232"
},
{
"accountNumber": "2048714015",
"bankCode": "057"
}
],
"accountNames": [
"DAMILARE OGUNNAIKE SAMUEL"
]
}
}
}

The API below provides an entry point for merchants to link customers 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:

  1. For accounts that wish to enjoy the maximum transaction limit, both BVN and NIN must be linked to the reserved account.
  2. For accounts with limited transaction amounts, one of NIN or BVN is required.

API Sample

json
Copy button
{{monnify_live_url}} = https://api.monnify.com

API Endpoint

json
Copy button
{{monnify_live_url}}/api/v1/bank-transfer/reserved-accounts/{accountReference}/kyc-info

API Method: PUT

Request Payload

json
Copy button
{
"bvn":"22222222226",
"nin":"1047495939309"
}

Success Response

json
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
{
"accountReference":"ab3ed-ashdg-s23bdj",
"accountName": "OMEH CHIZITEREM",
"customerEmail": "[email protected]",
"customerName": "OMEH CHIZITEREM",
"bvn":"22222222226",
"nin":"1047495939309"
}
}

Failed Response

json
Copy button
{
"requestSuccessful": false,
"responseMessage": "Invalid NIN",
"responseCode": "99"
}

json
Copy button
{
"requestSuccessful": false,
"responseMessage": "Invalid BVN",
"responseCode": "99"
}


Sample Error Messages

Error MessageMeaningAction
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
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 digitsThis most times implies that the BVN provided is invalidIf BVN/NIN is supplied, confirm that it has the required length
Unknown currency code supplied.The currency code supplied is not valid or supportedReconfirm 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 arrayRetry 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

Was this page helpful? Tell us what you think..
Copyright © 2024 Monnify