Payment Gateway Integration Fundamentals

Integrating a payment gateway requires understanding the entire lifecycle of a transaction, not just the API calls to initialize a payment. This guide covers the fundamentals of processing payments through Nigerian payment gateways.

The Payment Collection Lifecycle

The process of collecting a payment generally follows a standardized lifecycle across modern gateways:

1. Customer Initiates: A customer confirms their order and proceeds to checkout on your platform.
2. Payment Initialization: Your backend server makes a secure API call to the gateway to initialize the payment, generating a unique transaction reference.
3. Gateway Processing: The customer enters their payment details (card, bank transfer, USSD, etc.) on a secure page hosted by the gateway, or seamlessly within your application.
4. Payment Confirmation: The gateway attempts to authorize and capture the funds through acquiring banks and card networks.
5. Merchant Notification: Upon a definitive success or failure, the gateway notifies your server asynchronously via a webhook.
6. Settlement: The gateway later transfers the collected funds (minus processing fees) to your business bank account.

Hosted Checkout vs Direct API Integration

When integrating payment providers like Paystack, Flutterwave, or Monnify, you generally have two primary integration patterns. All three providers support both approaches.

Hosted Checkout

With hosted checkout, you redirect the customer to a secure page hosted by the payment provider, or you load the provider’s payment modal via an inline script over your page.

Advantages:

• Significantly reduces your PCI-DSS compliance burden because payment details never touch your servers.
• The provider handles UI updates, error handling, and alternative payment methods (like Apple Pay, USSD, or Bank Transfer) automatically.

Direct API Integration (Server-to-Server)

With direct API integration, you build your own checkout UI and securely pass the payment details directly to the provider’s API.

Advantages:

• Complete control over the user experience.
• Seamless flow without leaving your application.

Note: Direct API integrations typically require a higher level of PCI-DSS compliance and stricter security measures on your infrastructure.

Payment Status and State Machine

A payment transaction is a state machine. While specific status codes differ slightly among providers, the generic states typically include:

• Initiated / Pending: The payment has been requested, but the customer has not yet completed the transaction, or the network is still processing it.
• Successful: The funds have been successfully authorized and captured.
• Failed: The transaction was declined by the bank, or an error occurred during processing.
• Abandoned: The customer closed the checkout page or did not complete the transaction within a specific timeframe.
• Reversed: The transaction was initially successful but later reversed (e.g., due to a refund or chargeback).

Your application should be designed to handle these state transitions gracefully.

Webhook-Driven Payment Confirmation

A common mistake in early integrations is relying on the frontend application to confirm a payment status. Network instability or users closing the browser window early can result in missed confirmations.

Therefore, webhooks are essential for reliable payment confirmation. Webhooks are HTTP callbacks made by the payment provider to your server whenever a transaction’s status changes.

• Paystack and Monnify secure their webhooks using HMAC-SHA512 signature verification.
• Flutterwave secures its webhooks using a Secret Hash mechanism.

For a deep dive into securing these endpoints, read our guide on Webhook Verification for Payment Providers.

Idempotency and Retry Safety

Network requests can fail or timeout. When interacting with financial APIs, it is critical that retrying a request does not result in charging a customer multiple times.

This concept is known as idempotency. To achieve this:

1. Always generate a unique, client-side transaction reference (like a UUID) for every new payment attempt.
2. Send this unique reference when initializing a payment.
3. If the initialization request times out, you can safely retry the exact same request with the exact same reference. The gateway will recognize the duplicate reference and return the existing transaction state rather than creating a new one.

Settlement and Reconciliation

It is important to distinguish between payment collection (when the customer is charged) and settlement (when the funds reach your bank account).

While Nigerian gateways process collections in real-time, settlements occur in batches. The exact settlement timing depends on the provider and your business verification status. While T+1 (next business day) is common, you should verify the specific settlement terms in your provider’s dashboard or documentation.

Reconciliation involves matching the successful transactions recorded in your database against the settlement reports provided by the gateway to ensure all expected funds have been received.

Sandbox and Testing

Before going live, it is imperative to thoroughly test your integration using the provider’s sandbox environment. These environments simulate payment processing without real money, allowing you to trigger various successful and failed scenarios.

All three providers offer comprehensive sandbox environments:

• Paystack: Sign up and access test credentials at https://dashboard.paystack.com/#/signup.
• Flutterwave: Create a test account at https://dashboard.flutterwave.com/signup.
• Monnify: Access the sandbox dashboard at https://sandbox.monnify.com.

Ensure you switch your API keys and endpoints to the live environment only after verifying your integration and webhooks in the sandbox.

Choosing a Provider

Selecting the right payment gateway depends on your specific business requirements, target audience, and preferred payout methods. To help you make an informed decision, read our guide on Comparing Nigerian Payment Gateways and explore our detailed Providers Directory.

Official Documentation

Always refer to the official API documentation for the most accurate and up-to-date integration details:

• Paystack: https://paystack.com/docs/api
• Flutterwave: https://developer.flutterwave.com/docs
• Monnify: https://docs.monnify.com