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

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

Request Body

json

{
  "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

{
  "requestSuccessful": true,
  "responseMessage": "success",
  "responseCode": "0",
  "responseBody": {
    "contractCode": "8389328412",
    "accountReference": "abc1234",
    "accountName": "Tes",
    "currencyCode": "NGN",
    "customerEmail": "[email protected]",
    "customerName": "John Doe",
    "accounts": [
      {
        "bankCode": "50515",
        "bankName": "Moniepoint Microfinance Bank",
        "accountNumber": "6254727989",
        "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. 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.

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;

Split payments on Reserved Accounts

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.

Sample Request

json

{
    "accountReference": "abc123",
    "accountName": "Test Reserved Account",
    "currencyCode": "NGN",
    "contractCode": "8389328412",
    "customerEmail": "[email protected]",
    "customerName": "John Doe",
    "bvn": "21212121212",
    "nin": "12034875601",
    "getAllAvailableBanks": true
    "incomeSplitConfig": [
        {
            "subAccountCode": "MFY_SUB_319452883228",
            "feePercentage": 10.5,
            "splitPercentage": 20,
            "feeBearer": true
        }
    ]
}

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.

Restriction of Payment Sources on Reserved Accounts

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

{
  "accountReference": "abc123",
  "accountName": "Test Reserved Account",
  "currencyCode": "NGN",
  "contractCode": "8389328412",
  "customerEmail": "[email protected]",
  "customerName": "John Doe",
  "bvn": "21212121212",
  "restrictPaymentSource": true,
  "allowedPaymentSources": {
    "bvns": ["21212121212", "20202020202"],
    "bankAccounts": [
      {
        "accountNumber": "0068687503",
        "bankCode": "232"
      },
      {
        "accountNumber": "2048714015",
        "bankCode": "057"
      }
    ],
    "accountNames": ["SAMUEL DAMILARE OGUNNAIKE"]
  }
}

Sample Response

json

{
  "requestSuccessful": true,
  "responseMessage": "success",
  "responseCode": "0",
  "responseBody": {
    "contractCode": "8389328412",
    "accountReference": "abc123",
    "accountName": "Tes",
    "currencyCode": "NGN",
    "customerEmail": "[email protected]",
    "customerName": "John Doe",
    "accounts": [
      {
        "bankCode": "50515",
        "bankName": "Moniepoint Microfinance Bank",
        "accountNumber": "6254727989",
        "accountName": "Tes"
      }
    ],
    "collectionChannel": "RESERVED_ACCOUNT",
    "reservationReference": "NWA7DMJ0W2UDK1KN5SLF",
    "reservedAccountType": "GENERAL",
    "status": "ACTIVE",
    "createdOn": "2023-04-14 12:04:39.034",
    "incomeSplitConfig": [],
    "bvn": "21212121212",
    "restrictPaymentSource": true,
    "allowedPaymentSources": {
      "bvns": ["21212121212", "20202020202"],
      "bankAccounts": [
        {
          "accountNumber": "0068687503",
          "bankCode": "232"
        },
        {
          "accountNumber": "2048714015",
          "bankCode": "057"
        }
      ],
      "accountNames": ["SAMUEL DAMILARE OGUNNAIKE"]
    }
  }
}

Update Reserved Account KYC Info

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:

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.

Sample Error Messages