Integration Guide

Overview

This guide walks you through building a complete wallet integration using the FLEX SSO API. You’ll learn how to handle authentication, display balances, process transactions, and manage payment requests.

Estimated Time: 2-3 hours for complete integrationPrerequisites:

Partner API credentials
Development environment set up
Understanding of OAuth 2.0 flow

Integration Roadmap

Environment Setup

Configure credentials and create API client

Implement Auth Flow

Add customer login and token management

Display Wallet Balance

Show customer wallet information

Build Transaction Features

Enable P2P transfers, withdrawals, and payments

Add Payment Requests

Create and manage payment requests

Test & Deploy

Verify integration and go live

Step 1: Environment Setup

Configure Environment Variables

.env

# FLEX SSO API Configuration
FLEX_BASE_URL=https://staging-api.yourflexpay.com/v2
PARTNER_CLIENT_ID=your_partner_client_id
PARTNER_API_KEY=your_partner_api_key
PARTNER_REDIRECT_URI=https://your-app.com/auth/flex/callback

# Session Secret (generate a strong random string)
SESSION_SECRET=your_session_secret_here

Create API Client

class FLEXClient {
  constructor() {
    this.baseURL = process.env.FLEX_BASE_URL;
    this.clientId = process.env.PARTNER_CLIENT_ID;
    this.apiKey = process.env.PARTNER_API_KEY;
  }

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

    if (customerToken) {
      headers['Authorization'] = `Bearer ${customerToken}`;
    }

    return headers;
  }

  async request(method, endpoint, data = null, token = null) {
    const config = {
      method,
      headers: this.getHeaders(token)
    };

    if (data) {
      config.body = JSON.stringify(data);
    }

    const response = await fetch(`${this.baseURL}${endpoint}`, config);

    if (!response.ok) {
      const error = await response.text();
      throw new Error(`API Error: ${response.status} - ${error}`);
    }

    const contentType = response.headers.get('content-type');
    if (contentType && contentType.includes('application/json')) {
      return response.json();
    }
    return response.text();
  }

  // Auth methods
  async getAuthCode(paytag, password) {
    return this.request('POST', '/sso/auth-code?scope=profile', {
      paytag,
      password
    });
  }

  async exchangeToken(authCode) {
    return this.request('GET', `/sso/token?auth-code=${authCode}`);
  }

  // Wallet methods
  async getWallet(token, currency = 'NGN') {
    return this.request('GET', `/sso/wallet?currency=${currency}`, null, token);
  }

  async getWalletHistory(token, filters = {}) {
    const params = new URLSearchParams(filters);
    return this.request('GET', `/sso/wallet/history?${params}`, null, token);
  }

  // Transaction methods
  async p2pTransfer(token, data) {
    return this.request('POST', '/sso/transaction/p2p', data, token);
  }

  async withdraw(token, data) {
    return this.request('POST', '/sso/transaction/withdraw', data, token);
  }
}

module.exports = new FLEXClient();

Step 2: Implement Authentication

const express = require('express');
const session = require('express-session');
const flexClient = require('./flex-client');

const app = express();
app.use(express.json());
app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: { secure: process.env.NODE_ENV === 'production' }
}));

// Login endpoint
app.post('/auth/flex/login', async (req, res) => {
  try {
    const { paytag, password } = req.body;

    // Step 1: Get auth code
    const redirectUrl = await flexClient.getAuthCode(paytag, password);

    // Return redirect URL to frontend
    res.json({ redirectUrl });
  } catch (error) {
    res.status(401).json({ error: 'Authentication failed' });
  }
});

// OAuth callback
app.get('/auth/flex/callback', async (req, res) => {
  try {
    const authCode = req.query['auth-code'];

    if (!authCode) {
      return res.status(400).send('Missing auth code');
    }

    // Step 2: Exchange auth code for token
    const customerToken = await flexClient.exchangeToken(authCode);

    // Store token in session
    req.session.flexToken = customerToken;
    req.session.save();

    // Redirect to wallet dashboard
    res.redirect('/wallet');
  } catch (error) {
    res.status(401).send('Token exchange failed');
  }
});

// Middleware to check authentication
function requireAuth(req, res, next) {
  if (!req.session.flexToken) {
    return res.status(401).json({ error: 'Not authenticated' });
  }
  next();
}

Step 3: Display Wallet Balance

Wallet Dashboard

app.get('/api/wallet', requireAuth, async (req, res) => {
  try {
    const wallet = await flexClient.getWallet(req.session.flexToken);

    res.json({
      balance: wallet.Balance,
      currency: wallet.Currency,
      paytag: wallet.PayTag?.Tag,
      name: wallet.PayTag?.Name
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch wallet' });
  }
});

app.get('/api/wallet/history', requireAuth, async (req, res) => {
  try {
    const { limit = 20, offset = 0, startDate, endDate } = req.query;

    const result = await flexClient.getWalletHistory(req.session.flexToken, {
      limit,
      offset,
      startDate,
      endDate
    });

    res.json(result);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch history' });
  }
});

function WalletDashboard() {
  const [wallet, setWallet] = useState(null);
  const [history, setHistory] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadWalletData() {
      try {
        const [walletData, historyData] = await Promise.all([
          fetch('/api/wallet').then(r => r.json()),
          fetch('/api/wallet/history?limit=10').then(r => r.json())
        ]);

        setWallet(walletData);
        setHistory(historyData.History.items);
      } catch (error) {
        console.error('Failed to load wallet:', error);
      } finally {
        setLoading(false);
      }
    }

    loadWalletData();
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <div className="wallet-dashboard">
      <div className="balance-card">
        <h2>₦{wallet.balance.toLocaleString()}</h2>
        <p>{wallet.paytag}</p>
        <p>{wallet.name}</p>
      </div>

      <div className="transactions">
        <h3>Recent Transactions</h3>
        {history.map(tx => (
          <div key={tx.ID} className="transaction-item">
            <span>{tx.Description}</span>
            <span>₦{tx.Amount.toLocaleString()}</span>
            <span>{tx.Status}</span>
          </div>
        ))}
      </div>
    </div>
  );
}

Step 4: Build Transaction Features

P2P Transfer

app.post('/api/transfer/p2p', requireAuth, async (req, res) => {
  try {
    const { recipient, amount, comment } = req.body;

    const transaction = await flexClient.p2pTransfer(req.session.flexToken, {
      recipient,
      amount,
      comment,
      saveBeneficiary: req.body.saveBeneficiary || false
    });

    res.json(transaction);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

function P2PTransferForm() {
  const [formData, setFormData] = useState({
    recipient: '',
    amount: '',
    comment: ''
  });
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);

    try {
      const response = await fetch('/api/transfer/p2p', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(formData)
      });

      const data = await response.json();

      if (response.ok) {
        setResult({ success: true, data });
        setFormData({ recipient: '', amount: '', comment: '' });
      } else {
        setResult({ success: false, error: data.error });
      }
    } catch (error) {
      setResult({ success: false, error: 'Transfer failed' });
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Recipient PayTag (e.g., @johndoe)"
        value={formData.recipient}
        onChange={(e) => setFormData({...formData, recipient: e.target.value})}
        required
      />
      <input
        type="number"
        placeholder="Amount"
        value={formData.amount}
        onChange={(e) => setFormData({...formData, amount: e.target.value})}
        required
      />
      <input
        type="text"
        placeholder="Comment (optional)"
        value={formData.comment}
        onChange={(e) => setFormData({...formData, comment: e.target.value})}
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Processing...' : 'Send Money'}
      </button>

      {result && (
        <div className={result.success ? 'success' : 'error'}>
          {result.success
            ? `Transfer successful! Reference: ${result.data.Reference}`
            : `Error: ${result.error}`
          }
        </div>
      )}
    </form>
  );
}

Withdrawal to Bank

app.post('/api/transfer/withdraw', requireAuth, async (req, res) => {
  try {
    const { accountNumber, amount, comment } = req.body;

    const transaction = await flexClient.withdraw(req.session.flexToken, {
      accountNumber,
      amount,
      comment
    });

    res.json(transaction);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

Step 5: Payment Requests

Create Payment Request

// Backend endpoint
app.post('/api/payment-request', requireAuth, async (req, res) => {
  try {
    const { payer, amount, comment, duration } = req.body;

    const paymentRequest = await flexClient.request(
      'POST',
      '/sso/payment-transfer',
      { payer, amount, comment, duration },
      req.session.flexToken
    );

    res.json(paymentRequest);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

// Frontend component
function PaymentRequestForm() {
  const [formData, setFormData] = useState({
    payer: '',
    amount: '',
    comment: '',
    duration: 60 // minutes
  });

  const handleSubmit = async (e) => {
    e.preventDefault();

    const response = await fetch('/api/payment-request', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });

    const result = await response.json();

    if (response.ok) {
      alert(`Payment request created! Reference: ${result.Reference}`);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Payer PayTag"
        value={formData.payer}
        onChange={(e) => setFormData({...formData, payer: e.target.value})}
        required
      />
      <input
        type="number"
        placeholder="Amount"
        value={formData.amount}
        onChange={(e) => setFormData({...formData, amount: e.target.value})}
        required
      />
      <input
        type="text"
        placeholder="Description"
        value={formData.comment}
        onChange={(e) => setFormData({...formData, comment: e.target.value})}
      />
      <button type="submit">Request Payment</button>
    </form>
  );
}

Step 6: Test & Deploy

Testing Checklist

✅ Authentication Flow

Login with existing customer works
PayTag creation flow completes successfully
Token is stored and persists across requests
Logout clears session properly
401 errors trigger re-authentication

✅ Wallet Operations

Balance displays correctly
Transaction history loads with pagination
Wallet limits are enforced
Virtual accounts display correctly

✅ Transactions

P2P transfers complete successfully
Withdrawals process correctly
Transaction status updates properly
Error messages are user-friendly

✅ Payment Requests

Creating payment requests works
Accepting payment requests completes transfer
Declining/canceling updates status
Expired requests are handled

Go Live Checklist

Complete Staging Tests

Verify all features work in staging environment

Update Environment

Switch to production URLs and credentials

FLEX_BASE_URL=https://api.yourflexpay.com/v2

Enable HTTPS

Ensure all requests use HTTPS in production

Set Up Monitoring

Implement logging and error tracking

Deploy & Monitor

Deploy to production and monitor closely

Best Practices

Token Management

Store tokens server-side only, never in localStorage

Error Handling

Provide clear error messages to users

Loading States

Show loading indicators during API calls

Transaction Receipts

Display confirmation for all transactions

Common Pitfalls

Don’t store passwords! Use the OAuth flow - passwords should only be sent to FLEX API

Handle token expiration! Catch 401 errors and prompt re-authentication

Validate amounts! Check for sufficient balance before attempting transfers

Next Steps

API Reference

Explore all available endpoints

Support

Questions? Contact us:

Email: developers@yourflexpay.com

Wallet SSO

Merchant

Partner

IDAAS

Integration Guide

Overview

Integration Roadmap

Step 1: Environment Setup

Configure Environment Variables

Create API Client

Step 2: Implement Authentication

Step 3: Display Wallet Balance

Wallet Dashboard

Step 4: Build Transaction Features

P2P Transfer

Withdrawal to Bank

Step 5: Payment Requests

Create Payment Request

Step 6: Test & Deploy

Testing Checklist

Go Live Checklist

Best Practices

Token Management

Error Handling

Loading States

Transaction Receipts

Common Pitfalls

Next Steps

API Reference

Support

​Overview

​Integration Roadmap

​Step 1: Environment Setup

​Configure Environment Variables

​Create API Client

​Step 2: Implement Authentication

​Login Flow

​Step 3: Display Wallet Balance

​Wallet Dashboard

​Step 4: Build Transaction Features

​P2P Transfer

​Withdrawal to Bank

​Step 5: Payment Requests

​Create Payment Request

​Step 6: Test & Deploy

​Testing Checklist

​Go Live Checklist

​Best Practices

Token Management

Error Handling

Loading States

Transaction Receipts

​Common Pitfalls

​Next Steps

API Reference

​Support

Overview

Integration Roadmap

Step 1: Environment Setup

Configure Environment Variables

Create API Client

Step 2: Implement Authentication

Login Flow

Step 3: Display Wallet Balance

Wallet Dashboard

Step 4: Build Transaction Features

P2P Transfer

Withdrawal to Bank

Step 5: Payment Requests

Create Payment Request

Step 6: Test & Deploy

Testing Checklist

Go Live Checklist

Best Practices

Common Pitfalls

Next Steps

Support