QR Code

Generate QR Payload

Generate a QR code payload for quick payment collection. The generated payload can be converted to a QR code image that customers can scan with the FLEX mobile app to make instant payments.

The API returns a QR payload string, not an image. You’ll need to encode this payload into a QR code image using a QR code generation library.

Request Parameters

number

required

Payment amount in the specified currency (maximum: 999,999,999)

string

Unique reference for tracking this transaction (max 100 characters). Auto-generated if not provided.

string

Description or note for the payment (max 250 characters)

string

default:"NGN"

Currency code: NGN (Nigerian Naira) or FP (FLEX Points)

object

Additional custom data to store with the transaction

Request Example

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/merchant/qr \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_client_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-location: your_location_id' \
  --data '{
    "amount": 2500,
    "reference": "QR-ORDER-789",
    "comment": "Product Purchase",
    "currency": "NGN",
    "metadata": {
      "product_id": "PROD-123",
      "order_id": "789"
    }
  }'

const response = await fetch('https://staging-api.yourflexpay.com/v2/merchant/qr', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-client-id': 'your_client_id',
    'x-api-key': 'your_api_key',
    'x-location': 'your_location_id'
  },
  body: JSON.stringify({
    amount: 2500,
    reference: 'QR-ORDER-789',
    comment: 'Product Purchase',
    currency: 'NGN',
    metadata: {
      product_id: 'PROD-123',
      order_id: '789'
    }
  })
});

const qrPayload = await response.json();

import requests

response = requests.post(
    'https://staging-api.yourflexpay.com/v2/merchant/qr',
    headers={
        'Content-Type': 'application/json',
        'x-client-id': 'your_client_id',
        'x-api-key': 'your_api_key',
        'x-location': 'your_location_id'
    },
    json={
        'amount': 2500,
        'reference': 'QR-ORDER-789',
        'comment': 'Product Purchase',
        'currency': 'NGN',
        'metadata': {
            'product_id': 'PROD-123',
            'order_id': '789'
        }
    }
)

qr_payload = response.json()

Response

The API returns a QR payload string that contains encrypted payment information.

"eyJhbW91bnQiOjI1MDAsInRhZyI6IkB5b3VyYnVzaW5lc3MiLCJyZWZlcmVuY2UiOiJRUi1PUkRFUi03ODkiLCJjb21tZW50IjoiUHJvZHVjdCBQdXJjaGFzZSIsImN1cnJlbmN5IjoiTkdOIiwibWV0YWRhdGEiOnsicHJvZHVjdF9pZCI6IlBST0QtMTIzIiwib3JkZXJfaWQiOiI3ODkifX0="

Converting Payload to QR Code

After receiving the QR payload, you need to encode it into a QR code image. Here’s how to do it in different languages:

const QRCode = require('qrcode');

async function generateQRImage(qrPayload) {
  try {
    // Generate QR code as Data URL (for web display)
    const qrDataURL = await QRCode.toDataURL(qrPayload, {
      errorCorrectionLevel: 'H',
      width: 300
    });

    // Or save as file
    await QRCode.toFile('payment-qr.png', qrPayload, {
      errorCorrectionLevel: 'H',
      width: 300
    });

    return qrDataURL;
  } catch (error) {
    console.error('QR generation failed:', error);
    throw error;
  }
}

// Usage
const qrPayload = await fetch('/merchant/qr', {...}).then(r => r.json());
const qrImage = await generateQRImage(qrPayload);

import qrcode
from PIL import Image

def generate_qr_image(qr_payload, filename='payment-qr.png'):
    """Generate QR code image from payload"""
    qr = qrcode.QRCode(
        version=1,
        error_correction=qrcode.constants.ERROR_CORRECT_H,
        box_size=10,
        border=4,
    )

    qr.add_data(qr_payload)
    qr.make(fit=True)

    img = qr.make_image(fill_color="black", back_color="white")
    img.save(filename)

    return filename

# Usage
qr_payload = response.json()
generate_qr_image(qr_payload)

<?php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;

function generateQRImage($qrPayload, $filename = 'payment-qr.png') {
    $qrCode = QrCode::create($qrPayload)
        ->setSize(300)
        ->setMargin(10);

    $writer = new PngWriter();
    $result = $writer->write($qrCode);

    // Save to file
    $result->saveToFile($filename);

    // Or get data URI for web display
    return $result->getDataUri();
}

// Usage
$qrPayload = json_decode($response);
$qrImage = generateQRImage($qrPayload);
?>

Installation Commands

npm install qrcode
# or
yarn add qrcode

pip install qrcode[pil]

composer require endroid/qr-code

Complete Example: Web Implementation

Here’s a complete example showing how to generate and display a QR code on a web page:

<!DOCTYPE html>
<html>
<head>
    <title>FLEX QR Payment</title>
    <script src="https://cdn.jsdelivr.net/npm/qrcode@1.5.1/build/qrcode.min.js"></script>
</head>
<body>
    <div id="qr-container">
        <h2>Scan to Pay</h2>
        <canvas id="qr-canvas"></canvas>
        <p>Amount: ₦<span id="amount"></span></p>
        <p>Reference: <span id="reference"></span></p>
    </div>

    <script>
        async function displayPaymentQR(amount, reference) {
            try {
                // Step 1: Generate QR payload from API
                const response = await fetch('https://staging-api.yourflexpay.com/v2/merchant/qr', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                        'x-client-id': 'your_client_id',
                        'x-api-key': 'your_api_key',
                        'x-location': 'your_location_id'
                    },
                    body: JSON.stringify({
                        amount: amount,
                        reference: reference,
                        comment: 'Product Purchase'
                    })
                });

                const qrPayload = await response.json();

                // Step 2: Generate QR code image
                const canvas = document.getElementById('qr-canvas');
                await QRCode.toCanvas(canvas, qrPayload, {
                    errorCorrectionLevel: 'H',
                    width: 300
                });

                // Step 3: Display payment details
                document.getElementById('amount').textContent = amount.toLocaleString();
                document.getElementById('reference').textContent = reference;

                console.log('QR code generated successfully');
            } catch (error) {
                console.error('Failed to generate QR:', error);
                alert('Failed to generate payment QR code');
            }
        }

        // Example usage
        displayPaymentQR(2500, 'QR-ORDER-789');
    </script>
</body>
</html>

import React, { useState, useEffect } from 'react';
import QRCode from 'qrcode';

function PaymentQR({ amount, reference }) {
  const [qrDataURL, setQrDataURL] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    generateQR();
  }, [amount, reference]);

  async function generateQR() {
    setLoading(true);
    setError(null);

    try {
      // Fetch QR payload from API
      const response = await fetch('https://staging-api.yourflexpay.com/v2/merchant/qr', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-client-id': process.env.REACT_APP_FLEXPAY_CLIENT_ID,
          'x-api-key': process.env.REACT_APP_FLEXPAY_API_KEY,
          'x-location': process.env.REACT_APP_FLEXPAY_LOCATION_ID
        },
        body: JSON.stringify({
          amount,
          reference,
          comment: 'Product Purchase'
        })
      });

      if (!response.ok) {
        throw new Error('Failed to generate QR payload');
      }

      const qrPayload = await response.json();

      // Convert payload to QR code image
      const dataURL = await QRCode.toDataURL(qrPayload, {
        errorCorrectionLevel: 'H',
        width: 300
      });

      setQrDataURL(dataURL);
    } catch (err) {
      setError(err.message);
      console.error('QR generation failed:', err);
    } finally {
      setLoading(false);
    }
  }

  if (loading) return <div>Generating QR code...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div className="payment-qr">
      <h2>Scan to Pay</h2>
      {qrDataURL && <img src={qrDataURL} alt="Payment QR Code" />}
      <p>Amount: ₦{amount.toLocaleString()}</p>
      <p>Reference: {reference}</p>
    </div>
  );
}

export default PaymentQR;

Use Cases

Point of Sale

Display QR codes at checkout counters for quick payment

E-commerce

Show QR code on order confirmation page as alternative payment method

Invoices

Include QR codes in PDF invoices for instant payment

Event Ticketing

Generate unique QR codes for ticket purchases

Best Practices

Use unique references for each QR code to track individual transactions

Set appropriate amounts - QR codes are typically used for fixed amounts

Include metadata to link QR payments back to your internal systems (order IDs, SKUs, etc.)

Display payment details alongside the QR code so customers know what they’re paying for

QR code payloads don’t expire automatically. Implement your own expiration logic if needed by tracking QR generation timestamps.

Error Responses

400 - Bad Request

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "amount must be a positive number"
  ]
}

401 - Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Payment Requests

Create payment requests with customer approval

Transaction History

Track all your transactions

Wallet SSO

Merchant

Partner

IDAAS

Generate QR Payload

Request Parameters

Request Example

Response

Converting Payload to QR Code

Installation Commands

Complete Example: Web Implementation

Use Cases

Point of Sale

E-commerce

Invoices

Event Ticketing

Best Practices

Error Responses

Payment Requests

Transaction History

​Generate QR Payload

​Request Parameters

​Request Example

​Response

​Converting Payload to QR Code

​Installation Commands

​Complete Example: Web Implementation

​Use Cases

Point of Sale

E-commerce

Invoices

Event Ticketing

​Best Practices

​Error Responses

​Related Endpoints

Payment Requests

Transaction History

Generate QR Payload

Request Parameters

Request Example

Response

Converting Payload to QR Code

Installation Commands

Complete Example: Web Implementation

Use Cases

Best Practices

Error Responses

Related Endpoints