Invoice

Monnify Invoicing allows you to generate invoices for your customers using our Create Invoice API. When you create an invoice, Monnify either generates a unique virtual account number tied to that invoice or provides a checkout URL so customers can make payments directly with their debit cards.

Types of Invoices

Monnify supports two types of invoices: Static Invoices and Dynamic Invoices. Both are created using the same Create Invoice API but differ in how virtual accounts are generated and used.

FeatureStatic InvoiceDynamic Invoice
Virtual Account NumberSame account reused for a specific customerNew account generated for every invoice
Account AvailabilityDormant until attached to an active invoiceActive only for the duration of that invoice
Use CaseRecurring billing, subscriptions, repeat customersOne-time payments, single-use invoices
Post-Payment BehaviorAccount becomes dormant until next invoiceAccount expires and cannot be reused
KYC RequirementRequires customer BVN or NIN to reserve the accountNo BVN/NIN required

1. Static Invoicing (Invoice Reserved Accounts)

Static invoicing is ideal when you bill the same customer repeatedly — for example, subscriptions, recurring services, or regular payments. Instead of generating a new virtual account number each time, Monnify lets you reserve a dedicated account number for that customer. This account number stays the same across all future invoices you send them, but it can only accept payments when attached to an active invoice.

Steps to Implement Static Invoicing

Follow these steps to set up and use static invoicing in your integration:


  1. Reserve a Virtual Account:
    Use the Create Invoice Reserved Account API to reserve a dedicated account for a customer. You will need to provide the customer’s BVN or NIN as part of this process. The response will include a accountReference that uniquely identifies the reserved account.

  2. Attach an Invoice to the Reserved Account:
    Once the account is reserved, use the Create Invoice API to generate an invoice linked to that reserved account. You must pass the accountReference you obtained earlier in the request payload. The invoice will use the same virtual account number every time.

  3. Send Invoice to Customer:
    Share the generated invoice details with your customer. They can pay by transferring funds into the reserved account or through the provided checkout URL.

  4. Handle Post-Payment Behavior:
    Once the invoice is paid, it expires immediately and the reserved account goes dormant. It remains inactive until a new invoice is generated for that customer.


Key characteristics:
  • A single virtual account number is reserved for a customer and reused for every invoice you send them.

  • Customers cannot make payments into this account unless it’s attached to an active invoice.

  • After payment, the invoice closes, and the account becomes dormant until the next invoice is generated.

  • Requires customer BVN or NIN during the initial reservation step.

  • Ideal for recurring billing, subscription-based services, or repeat customers.

2. Dynamic Invoicing

Dynamic invoicing is the simplest and most flexible way to bill customers. Each time you create an invoice, Monnify automatically generates a unique virtual account number tied to that specific invoice. Once the invoice is paid, it expires immediately, and the account number is no longer valid.


This approach is ideal when you do not bill the same customer repeatedly or when you want a fresh virtual account for every transaction. It requires no prior account reservation or KYC step.



Steps to Implement Dynamic Invoicing

Follow these steps to set up and use dynamic invoicing in your integration:


  1. Create an Invoice:
    Call the Create Invoice API endpoint to generate a new invoice. A virtual account number will be automatically created and linked to that invoice.

  2. Send Invoice to Customer:
    Share the invoice details with your customer. They can pay by transferring funds into the generated virtual account number or by using the provided checkout URL.

  3. Handle Post-Payment Behavior:
    Once payment is made, the invoice expires immediately. Since a new virtual account is generated for each invoice, subsequent invoices will each have their own dedicated account numbers.


Key characteristics:
  • A new virtual account number is generated for every invoice created.

  • No prior account reservation or BVN/NIN is required.

  • Once paid, the invoice expires immediately, and the virtual account is no longer active.

  • Ideal for one-time payments, unique transactions, or scenarios where customers vary frequently.


Additional Notes:
  • For static invoices, once an invoice expires or is paid, the reserved account simply goes dormant until a new invoice is created.

  • For dynamic invoices, a new virtual account is generated for every new invoice, and previous account numbers cannot be reused.



Sample Error Messages

Error MessageMeaningAction

Invoice with this reference already exists.

This implies that the invoiceReference in the request payload has already been used by you.

Retry with a unique invoiceReference

Unknown Contract Code provided.

The contractCode in the request parameter is not correct or it doesn’t belong to the merchant.

Navigate to the "Settings > Contract Setup", section of your Monnify dashboard to get your contact code

Amount must be greater than 20.

This implies that the amount field in the request payload must be at least 20 Naira

Increase the amount above N20

Unknown currency code supplied.

The currency code supplied is not valid or supported

Reconfirm the currency code supplied

Invalid invoice expiry date.

This implies that the expiryDate in the request payload is before the current date.

Invoice expiry date should be beyond current time.

Invalid invoice expiry date format

This implies that the expiryDate in the request payload is not in the correct format.

Change invoice expiry date format to match yyyy-MM-dd HH:mm:ss.

Rate this page

How would you rate your experience?

Copyright © 2025 Monnify
instagramfacebookicon