Customer Reserved Account

This API allows you to generate a virtual account for your customers. The account number generated is dedicated to a customer and every payment to that virtual account is associated with the customer for which the account was reserved.

CustomerReservedAccount:

Monnify Customer Reserved Account API Reference: Customer Reserved Account

create_general_reserve(account_reference: str, account_name: str, currency: str, merchant_code: str, customer_email: str, customer_name: str, bvn: str, nin: str, income_split_config: List[Dict[str, Any]] | None = None, allow_pay_source: Dict[str, List[Any]] | None = True, restrict_pay_source: bool | None = False, preferred_bank: List[Any] | None = None, get_all_banks: bool | None = True)→ MonnifyResponse

Create a dedicated virtual accounts for your customers

Parameters:

account_reference (str) – A unique reference generated
account_name (str) – The name of the account
currency (str, Currency (Enum) member value) – The currency of the account
merchant_code (str) – The merchant code of the account
customer_email (str) – The email of the customer
customer_name (str) – The name of the customer
bvn (str) – The BVN of the customer
nin (str) – The NIN of the customer
preferred_bank (list) – The preferred bank of the customer
income_split_config (List[Dict[str, Any]]) – The income split configuration among subaccounts
allow_pay_source (Dict[str, List[Any]]) – This captures bvns or account numbers or account names that are permitted to fund a reserved account. This is mandatory if restrict_pay_source is set to true
restrict_pay_source (bool, (default: False)) – if payment should be restricted to some reserved accounts
get_all_banks (bool, (default: True)) – Whether to get all banks

Returns:

The response from the API

Return type:

MonnifyResponse

Important

If the get_all_banks si set to False, the preferred_bank argument is mandatory.
If restrict_pay_source is set to True, the allow_pay_source parameter is mandatory.

create_invoice_reserve(account_reference: str, account_name: str, currency: str, merchant_code: str, customer_email: str, customer_name: str, bvn: str, nin: str, reserved_account: str | None = "INVOICE")→ MonnifyResponse

Create a invoice reserved accounts for your customers

Parameters:

account_reference (str) – A unique reference generated
account_name (str) – The name of the account
currency (str. Use the enum member value) – The currency of the account
merchant_code (str) – The merchant code of the account
customer_email (str) – The email of the customer
customer_name (str) – The name of the customer
reserved_account (str, (default: INVOICE)) – The reserved account number
bvn (str) – The BVN of the customer
nin (str) – The NIN of the customer

Returns:

The response from the API

Return type:

MonnifyResponse

get_reserve_detail(account_reference: str)→ MonnifyResponse

Get details of a reserved account

Parameters:: account_reference (str) – The reference to the account.
Returns:: The response from the API
Return type:: MonnifyResponse object

add_linked_account(account_reference: str, preferred_bank: list | None = None, get_all_banks: bool | None = True)→ MonnifyResponse

Add a linked account to a reserved account

Parameters:

preferred_bank (list) – The preferred bank code
account_reference (str) – The reference to the account
get_all_banks (bool, (default: True)) – Whether to get all banks

Returns:

The response from the API

Return type:

MonnifyResponse

update_bvn_reserve(account_reference: str, bvn: str) → MonnifyResponse

Update the BVN of a reserved account

Parameters:

account_reference (str) – The reference to the account
bvn (str) – The new BVN

Returns:

The response from the API

Return type:

MonnifyResponse

allow_payment_source(account_reference: str, allow_payment_source: Dict[str, List[Any]], restrict_pay_source: bool | None = True) → MonnifyResponse

Manages accounts that can fund a reserved account using either BVNs, Account Name or Account Number.

Parameters:

allow_payment_source (Dict[str, List[Any]]) – The allow payment source. Consists of dictionary of a list of bvns or bank accounts.
account_reference (str) – The reference to the account.
restrict_pay_source (bool, (default: True)) – Whether to allow or disallow payment source.

Returns:

The response from the API

Return type:

MonnifyResponse

update_split_config_account(account_reference: str, objects: List[Dict[str, Any]]) → MonnifyResponse

Update the income split configuration of a reserved account

Parameters:

account_reference (str) – The reference to the account
objects (List[Dict[str, Any]]) – The objects to update

Returns:

The response from the API

Return type:

MonnifyResponse

deallocate_customer(account_reference: str) → MonnifyResponse

Deallocate a reserved account

Parameters:: account_reference (str) – The reference to the account
Returns:: The response from the API
Return type:: MonnifyResponse

get_reserve_transactions(account_reference: str, per_page: int | None = 50, page: int | None = 0) → MonnifyResponse

Get transactions of a reserved account

Parameters:

account_reference (str) – The reference to the account
per_page (int, (default: 50)) – The number of results per page
page (int, (default: 0)) – The page number

Returns:

The response from the API

Return type:

MonnifyResponse

update_kyc_info(account_reference: str, bvn: str, nin: str) → MonnifyResponse

Update the KYC info of a reserved account

Parameters:

account_reference (str) – The reference to the account
bvn (str) – The new BVN
nin (str) – The new NIN

Returns:

The response from the API

Return type:

MonnifyResponse

You can use the tool kit in the helpers module as reference to get the string value of the Enum class parameter Tool kit

Allowed Payment Source(s)

To update or manage a reserved account to fund either using bvn, account name or account number, the data being passed into the allow_payment_source parameter is as such:

{
    "bvns": ["1234567890"],
    "bankAccounts": ["12345678"]
}

Updating the Split Configuration for Reserved Accounts

To update the split configuration of a reserved account, the following parameters are passed into the objects parameter:

objects = [
    {
        "subAccountCode": {{SubaccountCode}},
        "feePercentage": {{fee in percent}},  # float type
        "splitPercentage": {{split in percent}},  # float type
        "feeBearer": {{True or False}}
    }
]