Create an Invoice

To create an invoice you simply need to send a request to the endpoint below

This endpoint is protected with OAuth 2.0 Bearer token

Endpoint URL: {{base_url}}/api/v1/invoice/create

HTTP Method: POST

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

When the request is sent, an account number will be returned. You should include that account number (and bank) on the invoice being sent to your customer. We also return a checkout URL which can be included on your invoices. This way customers who want to pay using their debit cards can simply click on the link and pay using the Monnify payment interface.

Create Invoice Request

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "amount": "999", "invoiceReference": "1838913182", "description": "test invoice", "currencyCode": "NGN", "contractCode": "38238193818", "customerEmail": "johnsnow@gmail.com", "customerName": "John Snow", "expiryDate": "2019-10-30 12:00:00", "paymentMethods": ["ACCOUNT_TRANSFER"], "incomeSplitConfig": [ { "subAccountCode": "MFY_SUB_319452883228", "feePercentage": 10.5, "splitAmount": 20, "feeBearer": true } ], "redirectUrl": "http://app.monnify.com" }

Create Invoice Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { "requestSuccessful": true, "responseMessage": "success", "responseCode": "0", "responseBody": { "amount": 999, "invoiceReference": "1566947667149", "invoiceStatus": "PENDING", "description": "test invoice", "contractCode": "4876165459", "customerEmail": "johnsnow@gmail.com", "customerName": "John Snow", "expiryDate": "2019-10-18 14:48:00", "createdBy": "MK_TEST_VR7J3UAACH", "createdOn": "2019-08-27 23:14:29", "checkoutUrl": "https://sandbox.sdk.monnify.com/checkout/MNFY|20190827231429|000340", "accountNumber": "2219635498", "accountName": "1566947667149", "bankName": "Providus Bank", "bankCode": "101" } }

Once the invoice is generated, the customer can pay by simply doing a transfer to the virtual account number generated or via their debit card using the checkout URL. Once the customer pays, we will notify you via your Webhook URL. 

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. (m) Indicates fields that are mandatory only if the parent object is not empty.

Field

Description

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

customerName (M)

Full name of the customer

customerEmail (M)

The 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 of the transaction. Will be used as the account name for bank transfer payments

expiryDate (M)

The expiry date for the invoice. After this date, the customer will no longer be able to pay for that invoice. The 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 inquiry 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

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

paymentMethods

The payment method which the customer will use to make the payments. This can be set as "ACCOUNT_TRANSFER", "CASH" or "CARD" . If not set, this would default to the enabled methods in the contract detail.

splitPercentage

The percentage of the amount paid to be split into the sub-account. 

redirectUrl

A URL which customer will be redirected to when payment is successfully completed on the Web SDK.