Versions Compared

Key

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

Monnify allows you Reserve an Account for your customers who you send invoices to. You can then attach these accounts to invoices being generated so the customer always receives the same account number for any invoice he receives.

These accounts are slightly different from regular customer reserved accounts as customers cannot pay into these accounts until they are attached to an invoice. Basically, the account number is only active when attached to an invoice.

NB
Info
title

Only one invoice can be attached to a Reserved Account at a time.

Reserving An Account (Invoice)

To create a reserved account invoice, send a request to the reserved account endpoint.

Info
titleEndpoint
POST: https://sandbox.monnify.com/api/v1

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

This endpoint is protected with OAuth 2.0 (Bearer Tokens)

Here is a sample request and responseHTTP Method: POST

Info

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

Sample Reserve Account (Invoice) Request

{ "contractCode":"166813296212",
Code Block
languagejs
themeMidnight
titleReserve Account (Invoice) Request
json
{
	"accountReference": "abc123708",
	"accountName": "JaneTest Reserved DoeAccount",
    	"currencyCode": "NGN",
	"contractCode":    "accountReference"100693167467",
	"customerEmail": "janedoe12233test@tester.com",
	"customerName": "John Doe",
 	"customerEmailgetAllAvailableBanks": "janedoe@gmail.com"false,
    "customerNamepreferredBanks": "Jane Doe"["035","232","50515"],
    "reservedAccountType": "INVOICE"
}
Code Block
title

Sample Reserve Account (Invoice) Response

Code Block
languagejson
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "contractCode": "166813296212100693167467",
        "accountReference": "janedoe12233abc123708",
        "accountName": "Jane DoeTes",
        "currencyCode": "NGN",
        "customerEmail": "janedoe@gmailtest@tester.com",
        "customerName": "John Doe",
        "accounts": [
            {
                "bankCode": "Paschal Ezenwankwo"50515",
                "bankName": "Moniepoint Microfinance Bank",
                "accountNumber": "1122334455",6106424552",
                "accountName": "Tes"
            },
            {
                "bankCode": "232",
                "bankName": "Sterling bank",
                "accountNumber": "GTBank8947206823",
                "accountName": "Tes"
            },
            {
                "bankCode": "035",
                "bankName": "Wema "058bank",
                "accountNumber": "7203133878",
                "accountName": "Tes"
            }
        ],
        "collectionChannel": "RESERVED_ACCOUNT",
        "reservationReference": "KN5PYJ78PLSX7ET2U0M1NB8XNYZASVFTRN9",
        "reservedAccountType": "INVOICE",
        "status": "INACTIVE",
        "createdOn": "20192023-0704-1819 1412:4648:12.591"
25.496",
        "incomeSplitConfig": [],
        "bvn": "21212121212",
        "restrictPaymentSource": false
    }
}

Info

The status is INACTIVE because the reserved account is of type INVOICE and no invoice is currently attached to the account. Once an invoice is attached, the account becomes active.


Attaching a Reserved Account to an Invoice

To attach an invoice to a Reserved Account, you simply need to include the accountReference of the reserved account in the create invoice request.

To create a reserved account invoice, send a request to the reserved account endpoint.

Info
titleEndpoint
POST:

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/v1/invoice/create

HTTP Method: POST

Info

The {{base_url}} for test is https://sandbox.monnify.com

/api/v1/invoice/create

This endpoint is protected with Basic Authentication

but when you go live, it changes to the live url

When the request is sent, an account number will be returned. The account number that will be returned will be the account number that was reserved using the accountReference specified.

Create Invoice Request

Code Block
languagejs
themeMidnight
titleCreate Invoice Request
json
{
    "amount": "999",
    "invoiceReference": "1838913182abc1237008",
	"accountReference": "janedoe12233",
    "description": "test invoice",
    "currencyCode": "NGN",
    "contractCode": "38238193818100693167467",
    "customerEmail": "janedoe@gmail.com",
    "customerName": "Jane Doe",
    "expiryDate": "20192023-1007-3005 1216:0001:0008"
}


Create Invoice Response

Code Block
languagejs
themeMidnight
titleCreate Invoice Responsejson
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "amount": 999,
        "invoiceReference": "1838913182abc1237008",
        "invoiceStatus": "PENDING",
        "description": "test invoice",
        "accountReference": "janedoe12233",
        "contractCode": "4876165459100693167467",
        "customerEmail": "janedoe@gmail.com",
        "customerName": "JaneJohn Doe",
        "expiryDate": "20192023-1007-1805 1416:4801:0008",
        "createdBy": "MK_TESTPROD_VR7J3UAACHGFVLE0PZTQ",
        "createdOn": "20192023-0807-2703 2316:1401:2908",
        "checkoutUrlaccountNumber": "https://sandbox.sdk.monnify.com/checkout/MNFY|20190827231429|0003407203133878",
        "accountNumberaccountName": "1122334455Tes",
        "accountNamebankName": "JaneWema Doebank",
        "bankNamebankCode": "GTBank035",
        "bankCodetransactionReference": "058MNFY|63|20230703160107|004057"
    }
}


Once the invoice is

...

attached to the reserved account, the customer can pay by simply doing a transfer to the virtual account number generated

...

Once the customer pays, we will notify you via your Webhook URL. 

Info
title

Webhook URL

Need help on how to implement your webhook url? Click here

...

Field Reference

(M) indicates fields that are mandatory in the request body

Field

Description

amount (M)

The amount to be paid by the customer

invoiceStatus

Status of the invoice. Can be either "PAID", "PENDING" or "EXPIRED"

currencyCode (M)

The currency of the transaction being initialized. "NGN"

invoiceReference (M)

Merchant's Unique reference for the invoice.

accountReference (M)

Your unique reference used to identify this reserved account

customerName (M)

Full name of the customer

customerEmail (M)

Email address of the customer

apiKey (M)

Merchant's API Key (Can be found on the Monnify dashboard)

contractCode (M)

Merchant's contract code (Can be found on the Monnify dashboard)

description (M)

Description for the transaction. Will be used as the account name for bank transfer

paymentsd

payments

expiryDate (M)

Expiry date for the invoice. After this date, the customer will no longer be able to pay for that invoice. Format is YYYY-MM-DD HH:MM:SS

checkoutUrl 

A URL which can be used to display the Monnify payment interface where the customer can then pay for the invoice via bank transfer or card. This is especially useful for card transactions as the account number can and SHOULD be displayed on the invoice directly.

accountNumber

The virtual account number generated for the invoice. This is the account number the customer can transfer to, to pay this invoice

accountName

The name that will be displayed to the customer when he performs name enquiry on the virtual account. Please note there may be Prefixes

bankName

The name of the bank where the virtual account number was generated. The customer will be expected to select this bank when doing the bank transfer

bankCode

The bank code of the bank where the virtual account number was generated

Filter by label (Content by label)
showLabelsfalse
showSpacefalse
cqllabel in ( "invoicing" , "invoicing-api" , "authentication" , "reserve-account-api" )