Quickstart

Before You Begin

You will need:

1. A Monnify merchant account. Sign up at app.monnify.com
2. Your API Key, Secret Key and Contract Code from Developers > API Keys & Contracts on your dashboard

Sandbox first:

Use your test API key and the base URL https://sandbox.monnify.com while building. Switch to https://api.monnify.com and your live keys when you are ready to go live.

Choose Your Integration Path

Path A – Checkout SDK (No Authentication Required)

Use this path if you want to open Monnify's payment modal directly from your frontend. You only need your apiKey and contractCode, with no server-side token exchange needed.

Step 1 – Add the SDK and Open the Checkout

Option A – Script tag (no bundler)

Drop the Monnify script into your HTML and call MonnifySDK.initialize() directly. No installation needed.

Option B – npm Package (React, Vue, Angular)

If you're using a framework with a bundler, install the package that matches your project:

Both packages expose the same class-based API. Instantiate with your credentials and call initializePayment(). Here's a React example:

The same pattern works in Vue and Angular. Instantiate Monnify and call initializePayment() inside your component's pay handler.

Reference must be unique:

Generate a fresh reference for every new transaction. Reusing a reference from a previous payment will cause the checkout to fail.

Step 2 – Verify the Payment (Server-Side)

Critical:

Always verify the transaction on your server before delivering value. Never trust the client callback alone, as it can be tampered with.

When onComplete fires, send the paymentReference to your server and call the verification endpoint using your Secret Key for authentication.

Only mark an order as fulfilled when paymentStatus === "PAID" and amountPaid matches your expected amount.

Step 3 – Handle Webhooks

Set your webhook URL in Developers > Webhook URLs on the Monnify dashboard. Monnify will POST a notification to your endpoint for every completed transaction. Use this as a reliable server-side trigger instead of relying only on the onComplete callback.

See the Webhooks section for the full list of event types and how to verify the webhook signature.

Path B – API-First Integration

Use this path when you need full server-side control: authenticate to get a Bearer token, initialize a transaction via the API, and then either redirect the customer to the checkoutUrl or open the checkout from your frontend.

Step 1 – Authenticate

All Monnify API calls require a Bearer token. Generate one by Base64-encoding your apiKey:secretKey and calling the login endpoint. Tokens expire after 1 hour.

Store the accessToken and send it as Authorization: Bearer <token> on every subsequent request.

Step 2 – Initialize a Transaction

Call the Initialize Transaction endpoint with your payment details. Use a unique paymentReference per transaction.

Step 3 – Open the Checkout

You have two options for presenting the payment UI to your customer:

Option A – Redirect to Checkout URL

Redirect the customer directly to the checkoutUrl returned in Step 2. Monnify will redirect them back to your redirectUrl after payment.

Option B – Call Payment APIs Directly

Skip the hosted checkout entirely and drive the payment flow from your server. Two methods are available after initializing a transaction:

• Pay with Transfer: pass your transactionReference to the Pay with Bank Transfer endpoint and Monnify returns a dynamic, time-bound account number. Display that account number in your own UI; once the customer transfers the exact amount to it, Monnify notifies you via webhook. No PCI-DSS required.

• Charge a Card: collect card details in your own UI and submit them directly to Monnify's card charge endpoint . This bypasses the checkout UI completely but requires PCI-DSS certification. Contact [email protected] to enable this on your account.

Step 4 – Verify the Payment (Server-Side)

Critical:

Always verify the transaction on your server before delivering value. Never trust the client callback alone, as it can be tampered with.

Only mark an order as fulfilled when paymentStatus === "PAID" and amountPaid matches your expected amount.

Step 5 – Handle Webhooks

Set your webhook URL in Developers > Webhook URLs. Monnify will POST a notification to your endpoint for every completed transaction. Use this as a reliable server-side trigger instead of relying only on the redirect callback.

See the Webhooks section for the full list of event types and how to verify the webhook signature.

Path C – WordPress / WooCommerce Plugin

Running a WordPress store? Skip the code entirely. The official Monnify WooCommerce plugin adds card and bank transfer as payment options to your checkout with a few clicks.

Step 1 – Install the Plugin

1. In your WordPress admin, go to Plugins > Add New.
2. Search for Monnify and click Install Now on the Monnify Official plugin.
3. Click Activate.

Or download the ZIP directly from the WordPress Plugin Directory and upload it via Plugins > Add New > Upload Plugin.

Step 2 – Enter Your API Keys

1. Go to WooCommerce > Settings > Payments and click Manage next to Monnify.
2. Enter your API Key, Secret Key, and Contract Code from the Monnify dashboard.
3. Set the environment to Sandbox for testing, then Save changes.

Where to find your keys:

In your Monnify dashboard, go to Settings > API Keys & Webhooks for your API Key and Secret Key. Your Contract Code is under Settings > Contracts.

Step 3 – Test, then Go Live

Place a test order on your store in Sandbox mode to confirm payments are working. Once satisfied, return to the plugin settings, switch the environment to Live, swap in your live keys, and save.

Webhook setup:

Add your webhook URL in the Monnify dashboard under Settings > API Keys & Webhooks so WooCommerce order statuses update automatically when customers pay. Your webhook URL is: https://yourstore.com/?wc-api=monnify_webhook

Next Steps

1. Explore all Payment Methods supported by Monnify
2. Checkout API: integrate using the JS, Android, Flutter, or iOS SDK
3. Verify Transactions: detailed guide on server-side verification
4. Going Live: checklist before switching to your production keys