Integrating Monnify is straightforward, but jumping straight into code without a clear plan can cause delayed launches.

To help your team begin production on time, we've broken the pre-integration process into three focused steps:

1. Step 1: Account Setup
2. Step 2: Plan With the Documentation
3. Step 3: Incorporate the Code Integration Guidelines

Step 1: Account Setup

Before you begin coding, you need a properly configured Monnify account.

1. Complete Your KYC Verification: Sign up on Monnify and submit your business details. Not sure what documents you need? See the KYC Checklist.
2. Retrieve Your Credentials: For API integrations, you'll need your unique identifiers. On your Monnify dashboard menu, navigate to Developers to copy your API Key, Secret Key, and Contract Code.

Step 2: Plan With the Documentation

Don't just build, build the right thing for your business.

1. Map Your Payment Use Case: Are you assigning virtual accounts to returning customers (reserved accounts)? Building a checkout page? Automating bulk payouts to vendors? Defining your use case upfront helps you select the right integration method and avoid rework later.
2. Read What’s relevant to You: You don’t need to read the entire API Docs, but you must read the guide for the specific feature you’re implementing. Security requirements vary by feature; for example, our Disbursement (Payout) API requires OTPs to protect your funds.
3. Understand Your Environments: Always begin in Test Mode (Sandbox). Understand the key differences between the sandbox and live (production) environments before you begin processing real transactions.

Step 3: Incorporate the Code Integration Guidelines

When integrating Monnify, your engineering team should integrate the following guidelines to protect your revenue:

1. Secure Every Request: All calls to the Monnify API must be authenticated using an OAuth 2.0 Bearer Token.
2. Use Unique Payment References: To initialize a payment, your backend will call the Initialize Transaction endpoint, then pass the amount, customer details, and a paymentReference. Your paymentReference must be strictly unique for every payment attempt. Reusing the same reference is a common cause of failed API calls.
3. Leverage Webhooks: Most payment methods are asynchronous (confirmation doesn't happen in real time), so do not fulfil an order based solely on a client-side success message. Instead, configure a Webhook URL so Monnify can notify your server the moment a payment is confirmed. Always verify the payment status on the server.
4. Test Beyond the “Happy Path”: The happy path (a customer pays, everything works) is only one scenario. Before going live, test for real-world edge cases such as expired accounts, partial payments, duplicate webhooks, and network delays. Handling these gracefully in Test mode (Sandbox) mode means your system is ready when they happen in Live mode (Production).

Ready to start building?

With your foundation in place, choose your next step:

1. Need a plan? Check our Payment Collection guides or Disbursement guides to find the right fit for your business. Or start with our overview: Monnify Products and Services.
2. Need the technical details? Visit the Monnify API Docs to begin implementing your chosen feature.
3. Setting up your environments? Read our guide on Sandbox vs. Production Environments