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)
...
Here is a sample request and response to help get you started:
Reserve Account Request
| Code Block | ||
|---|---|---|
| ||
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",
"customerBvn": "21212121212",
"customerName": "John Doe"
} |
| Info |
|---|
Split payments on Reserved AccountsincomeSplitConfig 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 | ||
|---|---|---|
| ||
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",
"customerBvn": "21212121212",
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_319452883228",
"feePercentage": 10.5,
"splitPercentage": 20,
"feeBearer": true
}
]
} |
| Info |
|---|
Restriction of Payment Sources on Reserved AccountsThe restrict payment source parameter enables you to restrict accounts that can fund a reserved account. |
Reserve Account Request with Allowed Payment Sources
| Code Block | ||
|---|---|---|
| ||
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", "customerBvn": "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"
]
}
} |
Reserve Account Response
| Code Block | ||
|---|---|---|
| ||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "797854529434",
"accountReference": "abc123",
"accountName": "Test Reserved Account",
"currencyCode": "NGN",
"customerEmail": "test@tester.com",
"accountNumber": "9900910565",
"bankName": "Providus Bank",
"bankCode": "101",
"reservationReference": "E9Y49CFNYAVHFGSCKJ6N",
"status": "ACTIVE",
"createdOn": "2019-08-11 23:00:43.816",
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_319452883228",
"feePercentage": 10.5,
"feeBearer": true,
"splitPercentage": 20
}
]
}
} |
...
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 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 the account is being reserved for |
customerBvn | BVN of the customer the account is being reserved for. Although 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. |
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. |
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 |
...
Related Articles
| Filter by label (Content by label) | ||||||
|---|---|---|---|---|---|---|
|
...