Wallet Creation

The Monnify Wallet Creation API facilitates the process of creating wallets for customers. This API provides the necessary functionality to generate wallets, allowing businesses to effortlessly create wallets for their customers through integration with the Monnify platform.

This endpoint is protected with a Basic Authentication. To access this endpoint, include the Authorization header in your HTTP requests. The header should start with the word "Basic" followed by a space and a base64-encoded string representing your apiKey and clientSecret as "apiKey:clientSecret".

Endpoint URL: {{base_url}}/api/v1/disbursements/wallet

HTTP Method: POST

The {{base_url}} for test is https://sandbox.monnify.com but when you go live, it changes to the live url

The API would require the following information: customer's wallet reference number, wallet name, customer name, BVN details, and customer email address. Once these details are sent through the endpoint, the API will return a Moniepoint account number along with the wallet details. The associated account name will match the customer name provided in the request.

You might also want to specify how disbursement fees should be handled; if it should be borne by the new wallet or any of the existing wallets. You can do this using the feeBearer and feeSourceAccountNumber parameter

See sample request and responses below:

Create Wallet Request

{
    "walletReference":"ref1684248425966",
    "walletName":"Staging Wallet - ref1684248425966",
    "customerName": "John Doe",
    "bvnDetails": {
    "bvn": "22222222226",
    "bvnDateOfBirth": "1993-10-03" 
    },
    "customerEmail": "test@tester.com",
    "feeBearer":"CUSTOM",
    "feeSourceAccountNumber":"8016472829"
}

Create Wallet Response

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "walletName": "Staging Wallet - ref1684248425966",
        "walletReference": "ref1684248425966",
        "customerName": "Test01-John Doe",
        "customerEmail": "test@tester.com",
        "feeBearer": "CUSTOM",
        "feeSourceAccountNumber": "8016472829",
        "bvnDetails": {
            "bvn": "22222222226",
            "bvnDateOfBirth": "1993-10-03"
        },
        "accountNumber": "8048865560",
        "accountName": "Test01-John Doe",
        "topUpAccountDetails": {
            "accountNumber": "0437959204",
            "accountName": "Test01-John Doe",
            "bankCode": "50515",
            "bankName": "Moniepoint MFB"
        }
    }
}

Debiting The Wallet

To debit the generated Monnify wallet, you simply make a POST request to the initiate transfer API.

The sourceAccountNumber in your request parameter becomes the internal accountNumber (that is the internal wallet id) of the generated wallet.

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
walletReference ^(M)	A uniquely generated reference that identifies the wallet
walletName ^(M)	A descriptive name for the generated wallet
customerName ^(M)	This is name of the customer whom the wallet is assigned to.
bvn ^(M)	The valid bvn of the customer
bvnDateOfBirth ^(M)	The date of birth linked to the bvn in the format yyyy-mm-dd
customerEmail ^(M)	Email address of the customer.
accountNumber	The internal wallet account id for disbursement purpose.
feeBearer	This specifies who bears the fees for every disbursement done through the wallet. This can either be SELF or CUSTOM and if not specified, the default SELF is used.
feeSourceAccountNumber	When feeBearer is set to Custom, you will need to specify the wallet account number of the wallet that will bear the disbursement fee.
topUpAccountDetails	An object containing the top up details of the customer.
topUpAccountDetails.accountNumber	The customer’s top up account number.
topUpAccountDetails.bankCode	The top up bank code.
topUpAccountDetails.bankName	The top up bank name.
topUpAccountDetails.accountName	The top up account name that displays during name enquiry.