/
Reserve An Account (V2)

Reserve An Account (V2)

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 https://sandbox.monnify.com but when you go live, it changes to the live url.

Here is a sample request and response to help get you started:

Get a reserve account reserved with each of partner banks available

If you want to reserve accounts across all partner banks for your customers, you will need to pass "true" for "getAllAvailableBanks". Note that Moniepoint 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 }

 

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": ["50515"] }

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. 

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 } ] }

 


Reserve Account Request with Allowed Payment Sources

Reserve Account Response

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

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