Integration Guide

Overview

This guide will walk you through integrating the FLEX Merchant API into your application. By the end, you’ll be able to create payment requests, generate QR codes, and manage transactions.

Estimated Time: 30-45 minutesPrerequisites:

API credentials (client ID, API key, location ID)
Development environment set up
Basic understanding of REST APIs

Integration Steps

Set Up Your Environment

Configure your development environment with the necessary credentials and dependencies.

Verify PayTag

Implement PayTag verification to ensure customers exist before creating payment requests.

Create Payment Request

Build the core functionality to create payment requests for your customers.

Track Payment Status

Implement status tracking to monitor payment request lifecycle.

Handle Edge Cases

Add error handling and edge case management.

Test & Go Live

Test thoroughly in staging, then deploy to production.

Step 1: Set Up Your Environment

Install Dependencies

npm install axios dotenv
# or
yarn add axios dotenv

pip install requests python-dotenv

# PHP has built-in cURL support
composer require vlucas/phpdotenv

Configure Environment Variables

Create a .env file in your project root:

.env

# Staging Environment
FLEXPAY_BASE_URL=https://staging-api.yourflexpay.com/v2
FLEXPAY_CLIENT_ID=your_client_id_here
FLEXPAY_API_KEY=your_api_key_here
FLEXPAY_LOCATION_ID=your_location_id_here

# Production Environment (uncomment when ready)
# FLEXPAY_BASE_URL=https://api.yourflexpay.com/v2

Add .env to your .gitignore file to prevent committing sensitive credentials!

Create API Client

require('dotenv').config();
const axios = require('axios');

class FLEXClient {
  constructor() {
    this.baseURL = process.env.FLEXPAY_BASE_URL;
    this.clientId = process.env.FLEXPAY_CLIENT_ID;
    this.apiKey = process.env.FLEXPAY_API_KEY;
    this.locationId = process.env.FLEXPAY_LOCATION_ID;
  }

  getHeaders(includeLocation = true) {
    const headers = {
      'x-client-id': this.clientId,
      'x-api-key': this.apiKey,
      'Content-Type': 'application/json'
    };

    if (includeLocation) {
      headers['x-location'] = this.locationId;
    }

    return headers;
  }

  async makeRequest(method, endpoint, data = null, includeLocation = true) {
    try {
      const config = {
        method,
        url: `${this.baseURL}${endpoint}`,
        headers: this.getHeaders(includeLocation),
      };

      if (data) {
        config.data = data;
      }

      const response = await axios(config);
      return response.data;
    } catch (error) {
      console.error('API Error:', error.response?.data || error.message);
      throw error;
    }
  }
}

module.exports = new FLEXClient();

import os
import requests
from dotenv import load_dotenv

load_dotenv()

class FLEXClient:
    def __init__(self):
        self.base_url = os.getenv('FLEXPAY_BASE_URL')
        self.client_id = os.getenv('FLEXPAY_CLIENT_ID')
        self.api_key = os.getenv('FLEXPAY_API_KEY')
        self.location_id = os.getenv('FLEXPAY_LOCATION_ID')

    def get_headers(self, include_location=True):
        headers = {
            'x-client-id': self.client_id,
            'x-api-key': self.api_key,
            'Content-Type': 'application/json'
        }

        if include_location:
            headers['x-location'] = self.location_id

        return headers

    def make_request(self, method, endpoint, data=None, include_location=True):
        url = f"{self.base_url}{endpoint}"
        headers = self.get_headers(include_location)

        try:
            response = requests.request(
                method=method,
                url=url,
                headers=headers,
                json=data
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            raise

client = FLEXClient()

Step 2: Verify PayTag

Before creating a payment request, verify that the customer’s PayTag exists and is valid.

const flexPay = require('./api-client');

async function verifyPayTag(payTag) {
  try {
    const result = await flexPay.makeRequest(
      'GET',
      `/merchant/payment-request/resolve-paytag?tag=${payTag}`,
      null,
      false // x-location not required for this endpoint
    );

    console.log('PayTag verified:', result);
    return result;
  } catch (error) {
    if (error.response?.status === 404) {
      console.error('PayTag not found');
      return null;
    }
    throw error;
  }
}

// Usage
const customer = await verifyPayTag('@johndoe');
if (customer) {
  console.log(`Customer: ${customer.Name} (${customer.Tag})`);
}

from flexpay_client import client

def verify_paytag(pay_tag):
    try:
        result = client.make_request(
            'GET',
            f'/merchant/payment-request/resolve-paytag?tag={pay_tag}',
            include_location=False
        )
        print(f"PayTag verified: {result}")
        return result
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            print("PayTag not found")
            return None
        raise

# Usage
customer = verify_paytag('@johndoe')
if customer:
    print(f"Customer: {customer['Name']} ({customer['Tag']})")

Expected Response:

{
  "Name": "John Doe",
  "Tag": "@johndoe"
}

Step 3: Create Payment Request

Now create a payment request for your verified customer.

async function createPaymentRequest(payerTag, amount, options = {}) {
  const payload = {
    payer: payerTag,
    amount: amount,
    reference: options.reference || `REF-${Date.now()}`,
    comment: options.comment || 'Payment request',
    currency: options.currency || 'NGN',
    duration: options.duration || 30, // minutes
    metadata: options.metadata || {}
  };

  try {
    const paymentRequest = await flexPay.makeRequest(
      'POST',
      '/merchant/payment-request',
      payload
    );

    console.log('Payment request created:', paymentRequest);
    return paymentRequest;
  } catch (error) {
    console.error('Failed to create payment request:', error.response?.data);
    throw error;
  }
}

// Usage
const payment = await createPaymentRequest('@johndoe', 5000, {
  comment: 'Invoice #12345',
  duration: 60,
  metadata: {
    invoice_id: '12345',
    customer_email: 'john@example.com'
  }
});

console.log(`Payment Reference: ${payment.Reference}`);
console.log(`Status: ${payment.Status}`);
console.log(`Expires: ${payment.ExpiresAt}`);

def create_payment_request(payer_tag, amount, **options):
    payload = {
        'payer': payer_tag,
        'amount': amount,
        'reference': options.get('reference', f"REF-{int(time.time() * 1000)}"),
        'comment': options.get('comment', 'Payment request'),
        'currency': options.get('currency', 'NGN'),
        'duration': options.get('duration', 30),
        'metadata': options.get('metadata', {})
    }

    try:
        payment_request = client.make_request(
            'POST',
            '/merchant/payment-request',
            data=payload
        )
        print(f"Payment request created: {payment_request}")
        return payment_request
    except Exception as e:
        print(f"Failed to create payment request: {e}")
        raise

# Usage
payment = create_payment_request('@johndoe', 5000,
    comment='Invoice #12345',
    duration=60,
    metadata={
        'invoice_id': '12345',
        'customer_email': 'john@example.com'
    }
)

print(f"Payment Reference: {payment['Reference']}")
print(f"Status: {payment['Status']}")

Expected Response:

{
  "ID": 12345,
  "Reference": "REF-1722345678901",
  "Amount": 5000,
  "Status": "Pending",
  "Description": "Invoice #12345",
  "PayTag": {
    "ID": 1,
    "Tag": "@merchant",
    "Name": "Your Business"
  },
  "Payer": {
    "ID": 2,
    "Tag": "@johndoe",
    "Name": "John Doe"
  },
  "Type": "C2M",
  "ExpiresAt": "2026-07-30T15:30:00Z",
  "CreatedAt": "2026-07-30T14:30:00Z",
  "UpdatedAt": "2026-07-30T14:30:00Z"
}

Payment requests expire after the specified duration (default: 30 minutes). Customers must complete payment before expiration.

Step 4: Track Payment Status

Implement functionality to check payment request status and retrieve payment history.

Get Single Payment Request

async function getPaymentRequest(reference) {
  try {
    const payment = await flexPay.makeRequest(
      'GET',
      `/merchant/payment-request/${reference}`
    );

    console.log(`Payment ${reference}:`, payment.Status);
    return payment;
  } catch (error) {
    console.error('Payment not found');
    return null;
  }
}

// Usage
const payment = await getPaymentRequest('REF-1722345678901');
if (payment.Status === 'Accepted') {
  console.log('Payment completed!');
}

def get_payment_request(reference):
    try:
        payment = client.make_request(
            'GET',
            f'/merchant/payment-request/{reference}'
        )
        print(f"Payment {reference}: {payment['Status']}")
        return payment
    except Exception as e:
        print("Payment not found")
        return None

# Usage
payment = get_payment_request('REF-1722345678901')
if payment and payment['Status'] == 'Accepted':
    print('Payment completed!')

List All Payment Requests

async function listPaymentRequests(filters = {}) {
  const params = new URLSearchParams({
    limit: filters.limit || 20,
    offset: filters.offset || 0,
    ...(filters.status && { status: filters.status })
  });

  try {
    const response = await flexPay.makeRequest(
      'GET',
      `/merchant/payment-request?${params}`
    );

    console.log(`Found ${response.count} payment requests`);
    return response;
  } catch (error) {
    console.error('Failed to fetch payment requests');
    throw error;
  }
}

// Usage - Get pending payments
const pending = await listPaymentRequests({ status: 'Pending', limit: 10 });
pending.items.forEach(payment => {
  console.log(`${payment.Reference}: ${payment.Amount} NGN`);
});

def list_payment_requests(**filters):
    params = {
        'limit': filters.get('limit', 20),
        'offset': filters.get('offset', 0)
    }

    if 'status' in filters:
        params['status'] = filters['status']

    query_string = '&'.join([f"{k}={v}" for k, v in params.items()])

    try:
        response = client.make_request(
            'GET',
            f'/merchant/payment-request?{query_string}'
        )
        print(f"Found {response['count']} payment requests")
        return response
    except Exception as e:
        print("Failed to fetch payment requests")
        raise

# Usage
pending = list_payment_requests(status='Pending', limit=10)
for payment in pending['items']:
    print(f"{payment['Reference']}: {payment['Amount']} NGN")

Step 5: Handle Edge Cases

Cancel Payment Request

async function cancelPaymentRequest(reference) {
  try {
    const cancelled = await flexPay.makeRequest(
      'POST',
      `/merchant/payment-request/${reference}/cancel`
    );

    console.log('Payment request cancelled:', cancelled.Reference);
    return cancelled;
  } catch (error) {
    console.error('Failed to cancel payment:', error.response?.data);
    throw error;
  }
}

// Usage
await cancelPaymentRequest('REF-1722345678901');

def cancel_payment_request(reference):
    try:
        cancelled = client.make_request(
            'POST',
            f'/merchant/payment-request/{reference}/cancel'
        )
        print(f"Payment request cancelled: {cancelled['Reference']}")
        return cancelled
    except Exception as e:
        print(f"Failed to cancel payment: {e}")
        raise

Error Handling Best Practices

async function safeCreatePayment(payerTag, amount, options = {}) {
  try {
    // Step 1: Verify PayTag
    const customer = await verifyPayTag(payerTag);
    if (!customer) {
      return {
        success: false,
        error: 'Customer PayTag not found'
      };
    }

    // Step 2: Create payment request
    const payment = await createPaymentRequest(payerTag, amount, options);

    return {
      success: true,
      data: payment
    };
  } catch (error) {
    // Handle specific error cases
    if (error.response?.status === 400) {
      return {
        success: false,
        error: 'Invalid request parameters',
        details: error.response.data
      };
    }

    if (error.response?.status === 401) {
      return {
        success: false,
        error: 'Authentication failed. Check your API credentials.'
      };
    }

    // Generic error
    return {
      success: false,
      error: 'An unexpected error occurred',
      details: error.message
    };
  }
}

Step 6: Generate QR Codes (Optional)

Generate QR codes for quick payment collection.

async function generatePaymentQR(amount, options = {}) {
  const payload = {
    amount: amount,
    reference: options.reference || `QR-${Date.now()}`,
    comment: options.comment || 'QR Payment',
    currency: options.currency || 'NGN',
    metadata: options.metadata || {}
  };

  try {
    const qrPayload = await flexPay.makeRequest(
      'POST',
      '/merchant/qr',
      payload
    );

    console.log('QR Code generated:', qrPayload);
    // Returns a QR payload string that can be encoded to QR image
    return qrPayload;
  } catch (error) {
    console.error('Failed to generate QR:', error.response?.data);
    throw error;
  }
}

// Usage
const qrCode = await generatePaymentQR(2500, {
  comment: 'Product Purchase',
  metadata: { product_id: 'PROD-123' }
});

Step 7: Test & Go Live

Testing Checklist

✅ Verify Authentication

All API requests include correct headers
Credentials are stored securely in environment variables
401 errors are handled gracefully

✅ Test Core Flows

PayTag verification works correctly
Payment requests are created successfully
Payment status can be retrieved
Payment cancellation works
Pagination works for payment lists

✅ Error Handling

Invalid PayTags are handled
Network errors are caught and logged
Invalid amounts are rejected
Expired payments are handled

✅ Edge Cases

Duplicate references are prevented
Large amounts are tested
Currency switching works (NGN/FP)
Metadata is properly stored and retrieved

Go Live Checklist

Complete Staging Tests

Ensure all features work correctly in the staging environment

Update Environment Variables

Switch FLEXPAY_BASE_URL to production: https://api.yourflexpay.com/v2

Request Production Credentials

Contact FLEX to receive your production API credentials

Enable Monitoring

Set up logging and monitoring for API requests and errors

Deploy to Production

Deploy your integration and monitor closely for the first few transactions

Complete Example Application

Here’s a complete working example:

const flexPay = require('./api-client');

class PaymentService {
  async processPayment(customerPayTag, amount, invoiceId) {
    console.log(`\n🔄 Processing payment for ${customerPayTag}...\n`);

    // Step 1: Verify customer
    console.log('1️⃣ Verifying customer...');
    const customer = await verifyPayTag(customerPayTag);
    if (!customer) {
      console.error('❌ Customer not found');
      return { success: false, error: 'Customer not found' };
    }
    console.log(`✅ Customer verified: ${customer.Name}`);

    // Step 2: Create payment request
    console.log('\n2️⃣ Creating payment request...');
    const payment = await createPaymentRequest(customerPayTag, amount, {
      comment: `Invoice ${invoiceId}`,
      metadata: { invoice_id: invoiceId }
    });
    console.log(`✅ Payment created: ${payment.Reference}`);
    console.log(`   Amount: ${payment.Amount} ${payment.currency || 'NGN'}`);
    console.log(`   Status: ${payment.Status}`);
    console.log(`   Expires: ${payment.ExpiresAt}`);

    return {
      success: true,
      reference: payment.Reference,
      status: payment.Status,
      expiresAt: payment.ExpiresAt
    };
  }

  async checkPaymentStatus(reference) {
    const payment = await getPaymentRequest(reference);
    if (!payment) {
      return { found: false };
    }

    return {
      found: true,
      status: payment.Status,
      amount: payment.Amount,
      payer: payment.Payer?.Name
    };
  }
}

// Run example
(async () => {
  const service = new PaymentService();

  // Create payment
  const result = await service.processPayment('@johndoe', 15000, 'INV-001');

  if (result.success) {
    // Check status
    setTimeout(async () => {
      const status = await service.checkPaymentStatus(result.reference);
      console.log(`\n📊 Payment Status: ${status.status}`);
    }, 5000);
  }
})();

Next Steps

API Reference

Explore detailed API endpoint documentation

Overview

Merchant API overview

OpenAPI Spec

Complete API specification

Need Help?

Email: developers@yourflexpay.com

Wallet SSO

Merchant

Partner

IDAAS

Integration Guide

Overview

Integration Steps

Step 1: Set Up Your Environment

Install Dependencies

Configure Environment Variables

Create API Client

Step 2: Verify PayTag

Step 3: Create Payment Request

Step 4: Track Payment Status

Get Single Payment Request

List All Payment Requests

Step 5: Handle Edge Cases

Cancel Payment Request

Error Handling Best Practices

Step 6: Generate QR Codes (Optional)

Step 7: Test & Go Live

Testing Checklist

Go Live Checklist

Complete Example Application

Next Steps

API Reference

Overview

OpenAPI Spec

Need Help?

​Overview

​Integration Steps

​Step 1: Set Up Your Environment

​Install Dependencies

​Configure Environment Variables

​Create API Client

​Step 2: Verify PayTag

​Step 3: Create Payment Request

​Step 4: Track Payment Status

​Get Single Payment Request

​List All Payment Requests

​Step 5: Handle Edge Cases

​Cancel Payment Request

​Error Handling Best Practices

​Step 6: Generate QR Codes (Optional)

​Step 7: Test & Go Live

​Testing Checklist

​Go Live Checklist

​Complete Example Application

​Next Steps

API Reference

Overview

OpenAPI Spec

​Need Help?

Overview

Integration Steps

Step 1: Set Up Your Environment

Install Dependencies

Configure Environment Variables

Create API Client

Step 2: Verify PayTag

Step 3: Create Payment Request

Step 4: Track Payment Status

Get Single Payment Request

List All Payment Requests

Step 5: Handle Edge Cases

Cancel Payment Request

Error Handling Best Practices

Step 6: Generate QR Codes (Optional)

Step 7: Test & Go Live

Testing Checklist

Go Live Checklist

Complete Example Application

Next Steps

Need Help?