Page Comparison

To reserve an account on Monnify, you’ll need to call the reserve account endpoint, see specifications below(remember to also add the authentication header).

...

Code Block

language	json

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


Request Body
{
	"accountReference": "abc123",
	"accountName": "Test Reserved Account",
	"currencyCode": "NGN",
	"contractCode": "8389328412",
	"customerEmail": "test@tester.com",
	"bvnnin": "2121212121212034875601",
	"customerName": "John Doe", 
    "getAllAvailableBanks": false,
    "preferredBanks": ["035","232","50515","058"]
}

...

Info

Split payments on Reserved Accounts

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.

Reserve Account Request with SubAccount

Code Block

language	json

Request Headers
Content-Type:"application/json"
Authorization:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
Request Body
{
	"accountReference": "abc123",
	"accountName": "Test Reserved Account",
	"currencyCode": "NGN",
	"contractCode": "8389328412",
	"customerEmail": "test@tester.com",
	"customerName": "John Doe",
	"bvn": "21212121212", 
	"nin": "12034875601",
	"getAllAvailableBanks": true
	"incomeSplitConfig": [
    	{
    		"subAccountCode": "MFY_SUB_319452883228",
    		"feePercentage": 10.5,
    		"splitPercentage": 20,
    		"feeBearer": true
    	}
    ]
}

...

Code Block

language	json

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


Request Body
{
	"accountReference": "abc123",
	"accountName": "Test Reserved Account",
	"currencyCode": "NGN",
	"contractCode": "8389328412",
	"customerEmail": "test@tester.com",
	"customerName": "John Doe",     
    "bvn": "21212121212",
	"incomeSplitConfig": [
    	{
    		"subAccountCode": "MFY_SUB_319452883228",
    		"feePercentage": 10.5,
    		"splitPercentage": 20,
    		"feeBearer": true
    	}
    ],
	"restrictPaymentSource": true,
    "allowedPaymentSources": {                                         
               "bvns": [
                 "21212121212",
                  "20202020202"
                ],    	
                "bankAccounts": [
    			{
    				"accountNumber": "0068687503",
    				"bankCode": "232"
    			}
    		],
    	   "accountNames": [
    			"SAMUEL DAMILARE OGUNNAIKE"
    			]
    }
}

...

Code Block

language	json

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "contractCode": "222001311614",
        "accountReference": "abc1234",
        "accountName": "Tes",
        "currencyCode": "NGN",
        "customerEmail": "test@tester.com",
        "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",
        "nin": "12034875601",
        "restrictPaymentSource": false
    }
}

...

^(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 enquiry
currencyCode ^(M)	Currency for transactions to this reserved account. Should be “NGN”
contractCode ^(M)	Contract Code (See your Monnify dashboard)
customerEmail ^(M)	Email address of the customer who the account is being reserved for. This is the unique identifier for each customer.
customerName	Full name of the customer

who

linked to its BVN or NIN
bvn	BVN of the customer the account is being reserved for

bvn

BVN

. This field is not mandated when NIN is supplied, merchants are expected to provide either BVN or NIN or both depending on the account tier.
nin	NIN of the customer the account is being reserved for.

Although this

This field is not mandated

, merchant's in the regulated business categories are required to provide BVN for a reserved account before those accounts can accept payments.

when BVN is supplied, merchants are expected to provide either BVN or NIN or both depending on the account tier.
getAllAvailableBanks	Set to true if you want to reserve accounts with all partner banks. Set to false if you want to specify preferred banks to reserve accounts with.
	Object containing specifications on how payments to this reserve account should be split.
restrictPaymentSource	A boolean value to activate or de-activate restricting payment sources for a reserved account. If set to true, at least one of bvns or accountNames or bankAccounts in allowedPaymentSources object must be supplied. Click here to learn more about source account restriction.
allowedPaymentSources	Object capturing bvns or account numbers or account names that are permitted to fund a reserved account. This is mandatory if restrictPaymentSource is set to true. Click here to learn more about source account restriction. For merchants in the regulated business category, only the bvn and allowed payment source BVNS (if any) can fund a reserve account.
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 22

New Version Current

Key

Split payments on Reserved Accounts

Related Articles