Download the PHP package monnify/monnify-laravel without Composer

Monnify Laravel

A Laravel package for integrating the Monnify payment gateway into your Laravel application. It covers collections, disbursements, virtual accounts, bills payment, verification, and more — all through a clean, consistent API.

Table of Contents

• Requirements
• Installation
• Configuration
• Quick Start
• How Responses Work
• Error Handling
• Webhooks
• Services
  • Transactions
  • Customer Reserved Accounts
  • Invoices
  • Disbursements (Transfers)
  • Wallets
  • Verification
  • Sub Accounts
  • Refunds
  • Settlements
  • Limit Profiles
  • Pay Codes
  • Direct Debit
  • Recurring Payments
  • Bills Payment
  • Helper / Utilities
• Contributing
• Credits
• License

Requirements

• PHP 8.1 or higher
• Laravel 8.x – 12.x
• A Monnify merchant account (sign up here)

Installation

Install the package via Composer:

Publish the config file:

This creates a config/monnify.php file in your application.

Configuration

Add the following to your .env file:

Where do I find these? Log in to your Monnify dashboard, go to Developers → API Keys & Contract to get your API key, secret, and contract code.

Tip: Always start with MONNIFY_ENVIRONMENT=SANDBOX while building and testing. Switch to LIVE only when you are ready for production.

Quick Start

The most common flow: collect a payment and verify it when the customer returns.

Step 1 — Initialize the payment and redirect the customer:

Step 2 — Verify the payment in your callback handler:

Important: Never rely solely on the redirect URL parameters to confirm a payment. Always call statusByReference() (or status()) from your callback handler to verify the payment directly with Monnify before fulfilling orders. For an additional layer of reliability — especially for payments that complete after a timeout or network drop — subscribe to Monnify webhook notifications and treat them as a second source of truth.

How Responses Work

Every method in this package returns an array with two keys:

Why $response['body']['responseBody']? Monnify's API always wraps the actual data inside a responseBody key within body. This is a Monnify API convention — the package returns it as-is so nothing is hidden from you. When you see $response['body']['responseBody']['checkoutUrl'], the two levels are: body (this package's wrapper) → responseBody (Monnify's wrapper) → the actual data.

On a failed request (e.g. a network error or a 4xx/5xx response), the array will look like:

Practical example — reading a response:

Error Handling

Wrap your calls in a try/catch block to handle validation errors (thrown before the request is made) and unexpected network failures:

Webhooks

Monnify sends an HTTP POST to your server whenever a significant event occurs (payment received, transfer completed, refund processed, etc.). Webhooks are the most reliable way to keep your system in sync — they fire even if your customer closes the browser mid-flow or a network timeout prevents the redirect from completing.

Full details: Webhook Overview · Event Types

Setting Up

1. Log in to your Monnify dashboard
2. Go to Developers → Webhook URLs
3. Enter your endpoint URL for each notification type (Transaction Completion, Disbursement, Refund, Settlement)

Event Types

Every webhook payload follows this structure:

Verifying the Signature

Monnify signs every webhook request with a monnify-signature header — an HMAC-SHA512 hash of the raw request body, keyed with your secret key.

Always verify this before processing any webhook. Skipping this check means anyone who knows your endpoint URL could send fake events.

Note: Use hash_equals() instead of === to prevent timing attacks.

Handling Webhooks in Laravel

1. Create the controller:

2. Register the route (webhooks must be excluded from CSRF verification):

Best Practices

• Verify the signature on every request before touching eventData
• Return HTTP 200 immediately — do heavy processing in a queued job. Monnify will retry delivery if it does not receive a 200 within a reasonable timeout
• Deduplicate events — store processed event references (e.g. transactionReference) and skip duplicates; Monnify may send the same event more than once
• Whitelist Monnify's IP (35.242.133.146) at your firewall or in middleware as an extra layer of protection

Services

All services are accessed through the Monnify facade:

Transactions

Handles payment initialisation, card charges, and status checks.

Initialize a Transaction

The starting point for collecting a payment. Returns a checkout URL you redirect your customer to.

Required fields: amount, customerEmail, paymentReference, currencyCode, contractCode, redirectUrl Optional fields: customerName, paymentDescription, paymentMethods, incomeSplitConfig

Production checklist: When a customer completes payment and is redirected to your redirectUrl, always call statusByReference() to verify the payment server-side before fulfilling the order. Additionally, subscribe to the SUCCESSFUL_TRANSACTION webhook event on your Monnify dashboard so your system is notified even if the customer closes the browser before the redirect completes. See the Webhooks section for setup details.

Pay with Bank Transfer

Use this when you want to generate a bank transfer payment directly inside your app (without redirecting to checkout).

Charge a Card

Sandbox test cards — use these card numbers in your SANDBOX environment. All share PIN 1234 and CVV 123.

Authorize with OTP

Called after chargeCard() when the bank requires OTP confirmation.

Authorize 3D Secure Card

3DS requires browser/device metadata collected from your customer's browser via JavaScript. Gather these values on your frontend and pass them along with the card details.

How to collect device information on the frontend: Add a small JavaScript snippet that reads these values from the browser's navigator and screen objects, then POST them to your backend before calling this endpoint. This data is required by card networks for 3DS fraud assessment.

Get All Transactions

Get Transaction Status

Customer Reserved Accounts

Reserved accounts are dedicated virtual bank accounts assigned to a customer. Any payment made to that account is automatically recognised and processed.

Create a General Reserved Account

Create an Invoice Reserved Account

Similar to a general account but tied to a specific invoice amount.

Get Account Details

Add Linked Accounts

Link additional bank accounts to an existing reserved account.

Update BVN

Update KYC Info

Restrict Payment Sources

Limit which BVNs or account numbers can fund a reserved account.

Update Split Configuration

Get Account Transactions

Deallocate (Delete) an Account

Invoices

Create time-limited payment requests you can send to customers.

Create an Invoice

Get Invoice Details

Get All Invoices

Cancel an Invoice

Attach a Reserved Account to an Invoice

Disbursements (Transfers)

Send money from your Monnify wallet to bank accounts — one at a time or in bulk.

Single Transfer

Two-factor note: By default, transfers require OTP authorisation. If you receive a PENDING_AUTHORIZATION status, call authoriseSingle() with the OTP.

Authorise a Single Transfer (OTP)

Resend OTP for a Single Transfer

Single Transfer Status

Bulk Transfer

Send payments to multiple recipients in one request.

Authorise a Bulk Transfer (OTP)

Resend OTP for a Bulk Transfer

Bulk Transfer Status (Per Transaction)

Lists individual transactions within a batch.

Bulk Batch Summary

Gets the overall summary of a batch (total sent, total failed, etc.).

List All Transfers

Search Transfers

Get Disbursement Wallet Balance

Returns the available balance on your Monnify disbursement wallet account.

Note: This returns the balance for your Monnify disbursement (merchant) wallet — identified by accountNumber. For the balance of a customer sub-wallet, use Monnify::wallet()->balance($accountNumber) instead.

Wallets

Activation required: The Wallet service is not enabled by default. Contact [email protected] to have it activated on your account.

Manage Monnify sub-wallets for your customers.

Create a Wallet

Get Wallet Details

Check Wallet Balance

Returns the balance for a specific customer sub-wallet (Wallet Service endpoint).

Note: This uses the Wallet Service endpoint (/api/v1/disbursements/wallet/balance) and requires the customer's sub-wallet account number. To check your Monnify disbursement wallet balance instead, use Monnify::transfer()->walletBalance($accountNumber).

Get Wallet Transactions

Verification

Verify bank accounts, BVN, and NIN before processing payments or disbursements.

Verify Bank Account

Verify BVN Information

Match BVN with Bank Account

Verify NIN

Sub Accounts

Activation required: The Sub Account service is not enabled by default. Contact [email protected] to have it activated on your account.

Sub accounts let you split incoming payments between multiple bank accounts automatically.

Create a Sub Account

Note: The API accepts an array of sub accounts, so always wrap a single sub account in an outer array as shown above.

Get All Sub Accounts

Update a Sub Account

Delete a Sub Account

Refunds

Activation required: The Refund service is not enabled by default. Contact [email protected] to have it activated on your account.

Reverse a completed transaction and return funds to the customer.

Initiate a Refund

Check Refund Status

Get All Refunds

Settlements

Query how funds were settled into your bank account.

Get Transactions by Settlement Reference

Get Settlement Info for a Transaction

Limit Profiles

Set transaction limits on reserved accounts — useful for KYC tier management.

Get All Limit Profiles

Create a Limit Profile

Update a Limit Profile

Create a Reserved Account with a Limit Profile

Update a Reserved Account's Limit Profile

Pay Codes

Activation required: The Pay Code service is not enabled by default. Contact [email protected] to have it activated on your account.

Generate single-use payment codes that can be redeemed at ATMs or agent locations.

Create a Pay Code

Get Pay Code Details

Pay Code History

Delete a Pay Code

Direct Debit

Set up mandates to debit a customer's account automatically on a schedule.

Create a Mandate

Get Mandate Details

Debit a Mandate

Get Debit Status

Cancel a Mandate

Recurring Payments

Activation required: Card tokenisation is not enabled by default. You must request it from Monnify before card tokens will be returned. Contact [email protected] to have it enabled on your account.

Once enabled, you can charge a customer's saved card token for future payments without asking them to re-enter their card details.

How Card Tokens Work

1. A customer completes a first-time card payment through your integration
2. After the payment succeeds, you call the transaction status requery endpoint
3. If tokenisation is enabled on your account, the requery response will include a cardToken
4. You store this token securely in your database against the customer's record
5. For all future charges, you pass the stored token to chargeCardToken() — no card details needed

Charge a Card Token

Bills Payment

Pay utility bills, buy airtime, subscribe to cable TV, and more.

Note: Bills Payment is not enabled by default. To activate it, email [email protected].

Typical Bills Payment Flow

Get Biller Categories

List Billers

Get Biller Products

Validate Customer

Always call this before vend() to confirm the customer ID (meter number, decoder ID, etc.) is valid. Some products also require you to pass back the validationReference in the vend request.

Process a Bill (Vend)

Check Bill Payment Status

Call this when vend() returns IN_PROGRESS to get the final result.

Complete Example — Pay an Electricity Bill

Helper / Utilities

Fetch general information like a list of banks.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature or bug-fix branch (git checkout -b feature/my-feature)
3. Make your changes and add tests where applicable
4. Submit a Pull Request with a clear description of what you changed and why

Please ensure your code follows the existing style and that all tests pass before submitting.

Credits

• Babatunde Adelabu
• Aransiola Ayodele
• Auwal MS
• Moses Adewale

License

This package is open-sourced under the MIT License.

Support

For integration questions or to activate additional features (like Bills Payment), contact the Monnify team:

• Email: [email protected]
• Developer Docs: developers.monnify.com