LworxPay Merchant API

https://lworx.ug-web.com/api/v1

curl -X POST https://lworx.ug-web.com/api/v1/direct-charge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":       "0700123456",
    "amount":      10000,
    "currency":    "UGX",
    "description": "Payment for Order #456",
    "reference":   "ORD-456",
    "ipn_url":     "https://yoursite.com/webhook/lworxpay"
  }'

{
  "success": true,
  "message": "Payment prompt sent to +256700123456. Customer should approve on their phone.",
  "trx_id": "TXNABC123456789",
  "reference": "ORD-456",
  "amount": 10000,
  "fee": 200,
  "net_amount": 9800,
  "currency": "UGX",
  "status": "pending",
  "status_url": "https://lworx.ug-web.com/api/v1/charge-status/TXNABC123456789"
}

{
  "success": false,
  "error": "Failed to initiate payment. Invalid phone number."
}

{
  "success": true,
  "trx_id": "TXNABC123456789",
  "status": "pending",
  "amount": 10000,
  "currency": "UGX"
}

{
  "success": true,
  "trx_id": "TXNABC123456789",
  "status": "success",
  "amount": 10000,
  "fee": 200,
  "net_amount": 9800,
  "currency": "UGX",
  "reference": "ORD-456",
  "created_at": "2026-03-12T10:00:00.000000Z",
  "updated_at": "2026-03-12T10:01:23.000000Z"
}

{
  "success": true,
  "trx_id": "TXNABC123456789",
  "status": "failed",
  "amount": 10000,
  "currency": "UGX"
}

async function pollPaymentStatus(trxId, apiKey) {
    const maxAttempts = 20; // ~60 seconds
    let attempts = 0;

    const poll = setInterval(async () => {
        attempts++;

        const res = await fetch(`/api/v1/charge-status/${trxId}`, {
            headers: { 'Authorization': `Bearer ${apiKey}` }
        });
        const data = await res.json();

        if (data.status === 'success') {
            clearInterval(poll);
            // Payment confirmed — fulfill order
            onPaymentSuccess(data);
        } else if (data.status === 'failed') {
            clearInterval(poll);
            // Payment failed or expired
            onPaymentFailed(data);
        } else if (attempts >= maxAttempts) {
            clearInterval(poll);
            // Timed out waiting
            onPaymentTimeout();
        }
    }, 3000); // poll every 3 seconds
}

function onPaymentSuccess(data) {
    document.getElementById('status').textContent = '✅ Payment Confirmed!';
    // fulfill order, update UI, etc.
}

curl -X POST https://lworx.ug-web.com/api/v1/initiate-payment \
  -H "Content-Type: application/json" \
  -H "X-Environment: production" \
  -H "X-Merchant-Key: YOUR_MERCHANT_KEY" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "payment_amount":   50000,
    "currency_code":    "UGX",
    "ref_trx":          "ORDER_12345",
    "description":      "Payment for Order #12345",
    "customer_name":    "John Doe",
    "customer_email":   "john@example.com",
    "ipn_url":          "https://yoursite.com/webhook/lworxpay",
    "success_redirect": "https://yoursite.com/payment/success",
    "cancel_redirect":  "https://yoursite.com/payment/cancelled"
  }'

{
  "payment_url": "https://lworx.ug-web.com/payment/checkout?token=eyJ0eXAiOiJKV1Qi...",
  "info": {
    "ref_trx":        "ORDER_12345",
    "amount":         50000,
    "currency_code":  "UGX",
    "description":    "Payment for Order #12345",
    "customer_name":  "John Doe",
    "customer_email": "john@example.com",
    "environment":    "production"
  }
}

curl https://lworx.ug-web.com/api/v1/verify-payment/ORDER_12345 \
  -H "X-Merchant-Key: YOUR_MERCHANT_KEY" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Environment: production"

{
  "status": "completed",
  "ref_trx": "ORDER_12345",
  "amount": 50000,
  "currency": "UGX",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "created_at": "2026-03-12T10:00:00.000000Z",
  "completed_at": "2026-03-12T10:02:45.000000Z"
}

{
  "ipn_url": "https://yoursite.com/webhook/lworxpay"
}

{
  "data": {
    "ext_reference": "ORD-456",
    "phone": "+256700123456",
    "channel": "direct_charge",
    "merchant_name": "Your Store"
  },
  "message": "Payment Completed",
  "status": "completed",
  "timestamp": 1710240000
}

{
  "data": {
    "ref_trx": "ORDER_12345",
    "description": "Payment for Order #12345",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "merchant_name": "Your Store",
    "amount": 50000,
    "currency_code": "UGX",
    "ipn_url": "https://yoursite.com/webhook/lworxpay",
    "success_redirect": "https://yoursite.com/payment/success",
    "cancel_redirect": "https://yoursite.com/payment/cancelled"
  },
  "message": "Payment Completed",
  "status": "completed",
  "timestamp": 1710240000
}

<?php
if ($status === 'completed') {
    $ref   = $data['data']['ext_reference'] ?? $data['data']['ref_trx'];
    $order = Order::where('reference', $ref)->firstOrFail();

    if ($order->status !== 'paid') { // Idempotency check
        $order->update(['status' => 'paid', 'paid_at' => now()]);
        // Send receipt email, provision service, etc.
        Mail::to($order->customer_email)->send(new OrderPaidMail($order));
    }
}

# Install ngrok then expose your local server
ngrok http 8000

# Your webhook URL becomes something like:
# https://abc123.ngrok.io/webhook/lworxpay
# Pass this as ipn_url in your test requests

<?php
// ================================================================
// LworxPay Payment Link — All Countries (via Flutterwave)
// ================================================================

// .env
// LWORXPAY_BASE_URL=https://lworx.ug-web.com
// LWORXPAY_MERCHANT_KEY=your_merchant_key
// LWORXPAY_API_KEY=your_api_key
// LWORXPAY_CLIENT_SECRET=your_client_secret

class LworxPayService
{
    protected string $baseUrl;

    public function __construct()
    {
        $this->baseUrl = env('LWORXPAY_BASE_URL', 'https://lworx.ug-web.com');
    }

    public function initiatePayment(array $order): string
    {
        $response = Http::withHeaders([
            'Content-Type'   => 'application/json',
            'X-Environment'  => 'production',
            'X-Merchant-Key' => env('LWORXPAY_MERCHANT_KEY'),
            'X-API-Key'      => env('LWORXPAY_API_KEY'),
        ])->post($this->baseUrl . '/api/v1/initiate-payment', [
            'payment_amount'   => $order['amount'],
            'currency_code'    => $order['currency'] ?? 'UGX',
            'ref_trx'          => $order['reference'],
            'description'      => $order['description'],
            'customer_name'    => $order['customer_name'],
            'customer_email'   => $order['customer_email'],
            'ipn_url'          => route('webhook.lworxpay'),
            'success_redirect' => route('payment.success'),
            'cancel_redirect'  => route('payment.cancelled'),
        ]);

        if (!$response->successful()) {
            throw new Exception('LworxPay error: ' . $response->body());
        }

        return $response->json('payment_url');
    }

    public function verifyWebhook(string $payload, string $signature): bool
    {
        $expected = hash_hmac('sha256', $payload, env('LWORXPAY_CLIENT_SECRET'));
        return hash_equals($expected, $signature);
    }
}

// In your controller
class CheckoutController extends Controller
{
    public function checkout(Request $request, LworxPayService $lworxpay)
    {
        $order = Order::findOrFail($request->order_id);

        $paymentUrl = $lworxpay->initiatePayment([
            'amount'        => $order->total,
            'currency'      => 'UGX',
            'reference'     => 'ORD-' . $order->id,
            'description'   => 'Payment for Order #' . $order->id,
            'customer_name' => $request->user()->name,
            'customer_email'=> $request->user()->email,
        ]);

        return redirect($paymentUrl);
    }
}

// Webhook handler
Route::post('/webhook/lworxpay', function (Request $request) use ($lworxpay) {
    $payload   = $request->getContent();
    $signature = $request->header('X-Signature');

    if (!$lworxpay->verifyWebhook($payload, $signature)) {
        return response()->json(['error' => 'Invalid signature'], 401);
    }

    $data   = json_decode($payload, true);
    $status = $data['status'];
    $ref    = $data['data']['ref_trx'];

    if ($status === 'completed') {
        $orderId = str_replace('ORD-', '', $ref);
        Order::find($orderId)?->update(['status' => 'paid']);
    }

    return response()->json(['status' => 'ok']);
});

const axios  = require('axios');
const crypto = require('crypto');

const LWORXPAY_BASE     = process.env.LWORXPAY_BASE_URL || 'https://lworx.ug-web.com';
const MERCHANT_KEY      = process.env.LWORXPAY_MERCHANT_KEY;
const API_KEY           = process.env.LWORXPAY_API_KEY;
const CLIENT_SECRET     = process.env.LWORXPAY_CLIENT_SECRET;

// Initiate payment
async function initiatePayment(order) {
    const res = await axios.post(`${LWORXPAY_BASE}/api/v1/initiate-payment`, {
        payment_amount:   order.amount,
        currency_code:    order.currency || 'UGX',
        ref_trx:          order.reference,
        description:      order.description,
        customer_name:    order.customerName,
        customer_email:   order.customerEmail,
        ipn_url:          'https://yoursite.com/webhook/lworxpay',
        success_redirect: 'https://yoursite.com/payment/success',
        cancel_redirect:  'https://yoursite.com/payment/cancelled',
    }, {
        headers: {
            'Content-Type':  'application/json',
            'X-Environment': 'production',
            'X-Merchant-Key': MERCHANT_KEY,
            'X-API-Key':      API_KEY,
        }
    });
    return res.data.payment_url;
}

// Webhook handler
app.use('/webhook/lworxpay', express.raw({ type: 'application/json' }));
app.post('/webhook/lworxpay', (req, res) => {
    const payload   = req.body.toString();
    const signature = req.headers['x-signature'];
    const expected  = crypto.createHmac('sha256', CLIENT_SECRET).update(payload).digest('hex');

    if (expected !== signature) return res.status(401).json({ error: 'Invalid signature' });

    const data = JSON.parse(payload);
    if (data.status === 'completed') {
        // Fulfill order
        fulfillOrder(data.data.ref_trx);
    }

    res.json({ status: 'ok' });
});

# Sandbox direct charge test
curl -X POST https://lworx.ug-web.com/api/v1/direct-charge \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":       "0700000000",
    "amount":      1000,
    "currency":    "UGX",
    "description": "Sandbox test",
    "reference":   "TEST-001",
    "ipn_url":     "https://webhook.site/your-test-url"
  }'

# Sandbox payment link test
curl -X POST https://lworx.ug-web.com/api/v1/initiate-payment \
  -H "Content-Type: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_YOUR_MERCHANT_KEY" \
  -H "X-API-Key: test_YOUR_API_KEY" \
  -d '{
    "payment_amount":   5000,
    "currency_code":    "UGX",
    "ref_trx":          "TEST_ORDER_001",
    "description":      "Sandbox test payment",
    "customer_name":    "Test User",
    "customer_email":   "test@example.com",
    "ipn_url":          "https://webhook.site/your-test-url",
    "success_redirect": "https://yoursite.com/payment/success",
    "cancel_redirect":  "https://yoursite.com/payment/cancelled"
  }'