Page Comparison

To reserve an account on Monnify, you’ll need to call the reserve account endpoint providing the information in the table below (remember to also add the authentication header)

title

Info
This endpoint is protected with OAuth 2.0 Bearer token

Endpoint

...

URL:{{base_url}}/api/v1/bank-transfer/reserved-accounts/limit

...

_{This endpoint is protected with OAuth 2.0 (Bearer Tokens)}

Info
For the version 2 Reserved Account the v1 in the above url changes to v2

HTTP Method: POST

Info
The {{base_url}} for test is `https://sandbox.monnify.com` but when you go live, it changes to the live url

Once an account number has been reserved for a customer, the customer can make payment by initiating a transfer to that account number at any time. Once the transfer hits the partner bank, we will notify you with the transfer details along with the accountReference you specified when reserving the account.

...

Sample Request

Request

Code Block

language	js
theme	Midnight
title	Reserve Account with Limit Request

json

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


Request Body
{
    "contractCode":"915483727511",
    "accountName":"Kan Yo' Reserved with Limit ",
    "currencyCode":"NGN",
    "accountReference": "ref-007",
    "customerEmail": "KanYo@monnify.com",
    "customerName": "Kan Yo",
    "limitProfileCode": "2XKTQ3LE9NH2",
	"incomeSplitConfig": [
    	{
    		"subAccountCode": "MFY_SUB_319452883228",
    		"feePercentage": 10.5,
    		"splitPercentage": 20,
    		"feeBearer": true
    	}
    ]
}

Info

...

Limits on Reserved Accounts

The limit profile code is mandatory for accounts with a limit associated with the limit profile

incomeSplitConfig 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 Response

Code Block

language	js
theme	Midnight
title	Reserve Account with Limit Response
json

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "contractCode": "797854529434915483727511",
        "accountReference": "abc123ref-007",
        "accountName": "TestKan Yo' Reserved with Limit Account",
        "currencyCode": "NGN",
        "customerEmail": "test@testerKanYo@monnify.com",
        "customerName": "Kan Yo",
        "accountNumber": "99009105659907335053",
        "bankName": "Providus Bank",
        "bankCode": "101",
        "reservationReference": "E9Y49CFNYAVHFGSCKJ6NQSD79W83J766XMFYM58L",
        "status": "ACTIVE",
        "createdOn": "2019-0810-1129 2313:0059:4337.816983",
        "incomeSplitConfig": [
            {
                "subAccountCode": "MFY_SUB_319452883228",
                "feePercentage": 10.5,
                "feeBearer": true,
                "splitPercentage": 20
            }
        ],
        "limitProfileConfig": 
            {
            "limitProfileCode": "2XKTQ3LE9NH2",
            "singleTransactionValue": 70000.00,
            "dailyTransactionVolume": 4000,
            "dailyTransactionValue": 100000000.00
             }
    }
}


    }
}

...

Field Reference

^(M) indicates fields that are mandatory in the request body. ^(m) Indicates fields that are mandatory only if the parent object is not empty.

Field	Description
accountReference ^(M)	Your unique reference used to identify this reserved account
accountName ^(M)	The name you want to be attached to the reserved account. This will be displayed during name inquiry
limitProfileCode^(M)	The unique identifier that references the limit profile to associate with the reserved accounts.
currencyCode ^(M)	Currency for transactions to this reserved account. Should be “NGN”
contractCode ^(M)	Contract Code (See your Monnify dashboard)
customerEmail ^(M)	The email address of the customer who the account is being reserved for. This is a unique identifier for each customer.
customerName	Full name of the customer who the account is being reserved for
customerBvn	BVN of the customer the account is being reserved for. Please note that if BVN is not supplied there will be low limits on the reserved account.
incomeSplitConfig	The object containing specifications on how payments to this reserve account should be split.
subAccountCode ^(m)	The unique reference for the sub-account that should receive the split.
feeBearer	Boolean to determine if the sub-account should bear transaction fees or not
feePercentage	The percentage of the transaction fee to be borne by the sub-account
splitPercentage	The percentage of the amount paid to be split into the sub-account.
bankName	Name of the bank where the virtual account was created
bankCode	Bank code of the bank where the virtual account was created
accountNumber	virtual account number generated for the accountReference (Reserved account number)
status	Status of the reserved account number ("ACTIVE" means the account can be used)
createdOn	Date reserved account was created

...

Versions Compared

Old Version 1

New Version Current

Key

Sample Request

Limits on Reserved Accounts

Sample Response

Field Reference

Related Articles