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).
This endpoint is protected with OAuth 2.0 Bearer token. To find out more about authorization for Monnify endpoints, check Here |
Endpoint URL: {{base_url}}/api/v2/bank-transfer/reserved-accounts
HTTP Method: POST
The {{base_url}} for test is |
Here is a sample request and response to help get you started:
Get a reserve account reserved with each of partner banks availableIf you want to reserve accounts across all partner banks for your customers, you will need to pass "true" for "getAllAvailableBanks". Note that Wema bank accounts are the default virtual account. |
Reserve Account Request (Get an account each for all available partner banks)
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", "bvn": "21212121212", "customerName": "John Doe", "getAllAvailableBanks": true } |
Specify the partner banks you wish to reserve accounts with.If you want to reserve accounts for only preferred partner banks for your customers, you will need to pass "False" for "getAllAvailableBanks" and supply the bank codes of the preferred banks in an array. |
Reserve Account Request (Get an account for preferred partner banks)
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", "nin": "12034875601", "customerName": "John Doe", "getAllAvailableBanks": false, "preferredBanks": ["035","232","50515","058"] } |
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, you will be notified with the transfer details along with the account reference you specified when reserving the account.
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
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 } ] } |
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
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" ] } } |
Reserve Account Response
{ "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 linked to its BVN or NIN |
bvn | BVN of the customer the account is being reserved for. 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. This field is not mandated 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. |
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 |