Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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)

Info

This endpoint is protected with OAuth 2.0 Bearer token

Endpoint URL: https://sandbox.monnify.com{{baseurl}}/api/v1/bank-transfer/reserved-accounts/limit

HTTP Method: POST

Info

This endpoint is protected by OAuth 2.0 Bearer TokenThe {{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

Code Block
languagejson
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
languagejson
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "contractCode": "915483727511",
        "accountReference": "ref-007",
        "accountName": "Kan Yo' Reserved with Limit ",
        "currencyCode": "NGN",
        "customerEmail": "KanYo@monnify.com",
        "customerName": "Kan Yo",
        "accountNumber": "9907335053",
        "bankName": "Providus Bank",
        "bankCode": "101",
        "reservationReference": "QSD79W83J766XMFYM58L",
        "status": "ACTIVE",
        "createdOn": "2019-10-29 13:59:37.983",
        "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

...