Developer API & Integration Documentation

Environments: Sandbox vs Live Production

Flux provides dedicated Sandbox and Live environments to ensure risk-free development and robust testing.

Dual Environment

SANDBOX Test Environment (flx_test_*)

Use keys starting with flx_test_. Simulated checkout and payout flows run without debiting or transferring real Pakistani Rupees. Test phone numbers (e.g. 03001234567) auto-complete for rapid integration validation.

LIVE Production Environment (flx_live_*)

Use keys starting with flx_live_. Connects directly to 1Link, State Bank of Pakistan Raast, JazzCash, and Easypaisa. Requires an active merchant account with verified KYC and approved settlement bank details.

Switching Environments

Both environments use the exact same endpoint routes and JSON request structure. To switch from Sandbox to Live, simply replace your flx_test_... Bearer key with your production flx_live_... key in your environment variables.

Authentication & Idempotency Guarantee

Every REST request must include your secret API key passed in the standard HTTP Authorization header.

Authorization: Bearer flx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Idempotency-Key Header

Network connections can experience transient resets or timeouts. Flux enforces strict effectively-once financial processing. Send a unique UUID or Order Token in the Idempotency-Key header with every payment or disbursement creation request. If a retry occurs with the same key, Flux returns the original authoritative response without creating duplicate transactions or debiting float balances twice.

Idempotency-Key: ORD-99281-UUID4-TOKEN

POST

Create Hosted Payment Session

Initializes a customer checkout session valid for 10 minutes and generates a secure hosted URL.

POST https://www.signup.gofluxpay.site/api/v1/payments/create

curl -X POST https://www.signup.gofluxpay.site/api/v1/payments/create \
  -H "Authorization: Bearer flx_live_sample_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-1001-A" \
  -d '{
    "amount": 2500.00,
    "order_id": "ORDER-1001",
    "payer_email": "customer@example.com",
    "customer_name": "Tariq Khan",
    "return_url": "https://merchant.example/payment-result",
    "webhook_url": "https://merchant.example/webhooks/flux"
  }'

Response Structure

{
  "success": true,
  "payment": {
    "payment_id": "flx_pay_8a1bc490",
    "order_id": "ORDER-1001",
    "status": "pending",
    "amount": "2500.00",
    "currency": "PKR",
    "expires_at": "2026-10-06 22:15:00",
    "checkout_url": "https://www.signup.gofluxpay.site/checkout/flx_pay_8a1bc490?token=sec_token_94812"
  }
}

Hosted Checkout Experience

Redirect your customer to payment.checkout_url. The customer can pay via JazzCash Mobile Account, Easypaisa App Push, or Raast Instant QR. Flux automatically detects payment receipt in real time and redirects the customer back to your return_url with a 3-second live countdown dialog.

GET

Inquire Payment Status

Inquires the current authoritative server status of a customer checkout.

GET https://www.signup.gofluxpay.site/api/v1/payments/status?payment_id=flx_pay_8a1bc490

{
  "success": true,
  "payment": {
    "payment_id": "flx_pay_8a1bc490",
    "order_id": "ORDER-1001",
    "status": "completed",
    "amount": "2500.00",
    "payment_method": "jazzcash",
    "transaction_id": "TRX-8291048",
    "reference": "REF-983192",
    "completed_at": "2026-10-06 22:08:14"
  }
}

GET

Payout: List Supported Banks

Fetches the list of all supported Pakistani commercial banks, microfinance banks, and digital wallets.

GET https://www.signup.gofluxpay.site/api/v1/payouts/banks

{
  "success": true,
  "banks": [
    { "id": 1, "bank_name": "Meezan Bank Limited", "bank_code": "MEZN" },
    { "id": 2, "bank_name": "Habib Bank Limited (HBL)", "bank_code": "HABB" },
    { "id": 3, "bank_name": "Bank Alfalah Limited", "bank_code": "BAFL" },
    { "id": 4, "bank_name": "JazzCash (Mobilink Microfinance)", "bank_code": "JCASH" },
    { "id": 5, "bank_name": "Easypaisa (Telenor Bank)", "bank_code": "EPASA" },
    { "id": 6, "bank_name": "SadaPay", "bank_code": "SADA" },
    { "id": 7, "bank_name": "NayaPay", "bank_code": "NAYA" }
  ]
}

Account Title Fetch (Name Verification)

Verifies the legal account holder title before dispatching funds to prevent misdirected payouts.

POST https://www.signup.gofluxpay.site/api/v1/payouts/title-fetch

curl -X POST https://www.signup.gofluxpay.site/api/v1/payouts/title-fetch \
  -H "Authorization: Bearer flx_live_sample_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identification": "0102030405060708",
    "beneficiary_bank_id": 1
  }'

{
  "success": true,
  "data": {
    "account_title": "MUHAMMAD USMAN",
    "account_number": "0102030405060708",
    "bank_name": "Meezan Bank Limited"
  }
}

Initiate Instant Payout

Transfers funds instantly from your settled float balance to any beneficiary account or digital wallet.

POST https://www.signup.gofluxpay.site/api/v1/payouts/create

curl -X POST https://www.signup.gofluxpay.site/api/v1/payouts/create \
  -H "Authorization: Bearer flx_live_sample_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: PO-REQ-901" \
  -d '{
    "amount": 5000.00,
    "beneficiary_name": "MUHAMMAD USMAN",
    "beneficiary_account": "0102030405060708",
    "beneficiary_bank_id": 1,
    "remarks": "Vendor Settlement"
  }'

Inquire Payout Status

GET https://www.signup.gofluxpay.site/api/v1/payouts/status?payout_id=flx_po_78a1bc

{
  "success": true,
  "payout": {
    "payout_id": "flx_po_78a1bc",
    "status": "completed",
    "amount": "5000.00",
    "fee": "15.00",
    "reference_no": "STAN-99182374",
    "beneficiary_name": "MUHAMMAD USMAN",
    "completed_at": "2026-10-06 22:18:04"
  }
}

Float Balance Inquiry

Checks your available and held disbursement float balances.

GET https://www.signup.gofluxpay.site/api/v1/payouts/balance

Cryptographically Signed Webhooks

Flux delivers real-time notifications via HTTP POST with an HMAC-SHA256 signature in the X-Flux-Signature header.

HMAC-SHA256

Supported Event Notifications: payment.completed · payment.failed · payment.expired · payout.completed · payout.failed · settlement.released

PHP Webhook Verification

<?php
$secret = 'flx_sec_live_9a2b8e4f1c';
$rawPayload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_FLUX_SIGNATURE'] ?? '';

$expectedSignature = hash_hmac('sha256', $rawPayload, $secret);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Signature verification failed');
}

$event = json_decode($rawPayload, true);

if ($event['event'] === 'payment.completed') {
    $orderId = $event['data']['order_id'];
    $amount = $event['data']['amount'];
    // Fulfill order in your database
}

http_response_code(200);
echo json_encode(['received' => true]);

Node.js Webhook Verification

const crypto = require('crypto');

app.post('/webhooks/flux', (req, res) => {
  const secret = process.env.FLUX_WEBHOOK_SECRET;
  const signature = req.headers['x-flux-signature'];
  const rawBody = req.rawBody; // Make sure raw body buffer is used

  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(rawBody).digest('hex');

  if (crypto.timingSafeEqual(Buffer.from(signature || ''), Buffer.from(digest))) {
    const event = JSON.parse(rawBody);
    // Process event
    return res.status(200).json({ received: true });
  }

  return res.status(401).send('Invalid signature');
});

Standardized Error Envelope

Every non-2xx API response returns a standard JSON error envelope with machine-readable error codes.

{
  "success": false,
  "request_id": "req_84f9a0c2",
  "error": {
    "code": "insufficient_balance",
    "message": "Available withdrawable balance is lower than the requested disbursement."
  }
}

Error Code	HTTP Status	Description & Remediation
`unauthorized`	401	Missing or invalid Bearer API key. Check key prefix.
`invalid_amount`	400	Payment amount must be greater than zero and formatted with 2 decimals.
`insufficient_balance`	422	Disbursement amount exceeds your available float balance. Top up float in Control Center.
`idempotency_conflict`	409	The Idempotency-Key was already used with different payload parameters.
`rate_limit_exceeded`	429	Request volume exceeded your configured per-minute limit. Retry with exponential backoff.

Production Go-Live Checklist

Ensure your integration complies with security standards before launching live transactions.

Compliance

1. Complete Business KYC

Submit CNIC, proof of settlement bank account, and business profile for verified live processing.

2. Server-side Status Authority

Never fulfill orders based on browser return redirects alone. Always verify via signed webhooks or GET /api/v1/payments/status.

3. Unique Idempotency Keys

Generate a unique Idempotency-Key for each checkout and disbursement to prevent double-charging on network retries.

4. Switch to Production Live Key

Replace your flx_test_... sandbox key with your flx_live_... production key in your server environment variables.