RwandaPay API Documentation

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "reference": "ORDER-1780943716",
    "session_id": "CHK-V0CFMJGNI8ZWIJBR",
    "payment_url": "https://pay.rwandapay.rw/checkout/CHK-V0CFMJGNI8ZWIJBR",
    "status": "pending",
    "amount": 8000,
    "currency": "RWF",
    "mode": "test",
    "expires_at": "2024-12-15T14:30:00Z"
  }
}

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "reference": "ORDER-1780943716",
    "session_id": "CHK-V0CFMJGNI8ZWIJBR",
    "payment_url": "https://pay.rwandapay.rw/checkout/CHK-V0CFMJGNI8ZWIJBR",
    "status": "pending",
    "amount": 8000,
    "currency": "RWF",
    "mode": "live",
    "expires_at": "2024-12-15T14:30:00Z"
  }
}

async function initializePayment(paymentData, apiKeys) {
    // Validate input
    if (!paymentData.amount || paymentData.amount < 100) {
        throw new Error('Amount must be at least 100 RWF');
    }
    if (!paymentData.customer?.phone) {
        throw new Error('Customer phone number is required');
    }
    
    // Disable button and show loading
    const payButton = document.getElementById('pay-button');
    if (payButton) {
        payButton.disabled = true;
        payButton.innerHTML = '<div class="spinner"></div> Processing...';
    }
    
    try {
        const response = await fetch('https://pay.rwandapay.rw/api/v1/checkout/initialize', {
            method: 'POST',
            headers: {
                'X-Public-Key': apiKeys.publicKey,
                'X-Secret-Key': apiKeys.secretKey,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                amount: paymentData.amount,
                tx_ref: paymentData.tx_ref || 'ORDER-' + Date.now(),
                currency: paymentData.currency || 'RWF',
                customer: {
                    name: paymentData.customer.name,
                    email: paymentData.customer.email,
                    phone: paymentData.customer.phone
                },
                redirect_url: paymentData.redirect_url || window.location.href + '/callback',
                webhook_url: paymentData.webhook_url,
                description: paymentData.description,
                meta: paymentData.meta || {}
            })
        });
        
        const result = await response.json();
        
        if (result.success) {
            // Redirect to hosted payment page
            window.location.href = result.data.payment_url;
            return result.data;
        } else {
            throw new Error(result.message || 'Payment initialization failed');
        }
    } catch (error) {
        console.error('Payment error:', error);
        showErrorToast(error.message);
        return null;
    } finally {
        if (payButton) {
            payButton.disabled = false;
            payButton.innerHTML = 'Pay Now';
        }
    }
}

// Usage example
initializePayment({
    amount: 5000,
    tx_ref: 'ORDER-' + Date.now(),
    customer: {
        name: 'John Doe',
        email: 'john@example.com',
        phone: '0788123456'
    },
    redirect_url: 'https://yoursite.com/payment-callback',
    webhook_url: 'https://yoursite.com/api/webhook',
    description: 'Payment for Order #12345'
}, {
    publicKey: 'YOUR_PUBLIC_KEY',
    secretKey: 'YOUR_SECRET_KEY'
});

{
  "status": "pending",
  "completed": false,
  "success": false,
  "message": "Waiting for payment confirmation...",
  "elapsed_seconds": 15,
  "mode": "live"
}

{
  "status": "successful",
  "completed": true,
  "success": true,
  "message": "Payment successful!",
  "redirect_url": "https://yoursite.com/callback?reference=ORDER-123&status=successful&transaction_id=PAY-XXX",
  "amount": 5000,
  "mode": "live"
}

{
  "status": "successful",
  "completed": true,
  "success": true,
  "message": "Test payment successful!",
  "redirect_url": "https://yoursite.com/callback?reference=ORDER-123&status=successful",
  "amount": 5000,
  "mode": "test"
}

{
  "status": "failed",
  "completed": true,
  "success": false,
  "message": "Payment failed",
  "redirect_url": "https://yoursite.com/callback?reference=ORDER-123&status=failed"
}

function pollPaymentStatus(reference, redirectUrl) {
    let attempts = 0;
    const maxAttempts = 60; // 60 * 3 seconds = 3 minutes max
    let interval;
    
    function checkStatus() {
        attempts++;
        console.log(`Checking payment status (attempt ${attempts}/${maxAttempts})...`);
        
        fetch(`https://pay.rwandapay.rw/api/v1/checkout/${reference}/verify`, {
            headers: {
                'Accept': 'application/json'
            }
        })
        .then(response => response.json())
        .then(data => {
            if (data.completed === true) {
                clearInterval(interval);
                if (data.success === true) {
                    // Redirect to success URL
                    window.location.href = data.redirect_url || redirectUrl;
                } else {
                    // Show error and redirect
                    showError(data.message);
                    setTimeout(() => {
                        window.location.href = data.redirect_url || '/';
                    }, 3000);
                }
            } else if (attempts >= maxAttempts) {
                clearInterval(interval);
                showError('Payment verification timeout. Please check your email.');
            }
        })
        .catch(error => {
            console.error('Polling error:', error);
            if (attempts >= maxAttempts) {
                clearInterval(interval);
                showError('Unable to verify payment status.');
            }
        });
    }
    
    // Start polling every 3 seconds
    interval = setInterval(checkStatus, 3000);
    checkStatus(); // Check immediately
}

{
  "event": "payment.successful",
  "data": {
    "reference": "ORDER-12345",
    "amount": 5000,
    "currency": "RWF",
    "status": "successful",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "0788123456"
    },
    "paid_at": "2024-12-15T14:30:00Z",
    "transaction_id": "PAY-LIVE-XXXXXXXX-20241215143000",
    "paypack_reference": "550e8400-e29b-41d4-a716-446655440000",
    "mode": "live"
  },
  "timestamp": "2024-12-15T14:30:05Z"
}

<?php
// Your webhook endpoint (e.g., https://yoursite.com/api/webhook)
header('Content-Type: application/json');

$payload = json_decode(file_get_contents('php://input'), true);

// Verify webhook signature (implement your signature verification)
if (!verifyWebhookSignature($payload)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

if ($payload['event'] === 'payment.successful') {
    $data = $payload['data'];
    
    // Update your database
    $orderId = $data['reference'];
    $amount = $data['amount'];
    $transactionId = $data['transaction_id'];
    
    // Mark order as paid
    $updated = DB::table('orders')
        ->where('reference', $orderId)
        ->where('status', 'pending')
        ->update([
            'status' => 'paid',
            'transaction_id' => $transactionId,
            'paid_at' => now(),
            'updated_at' => now()
        ]);
    
    if ($updated) {
        // Send confirmation email to customer
        // Update inventory
        // Trigger any business logic
        Log::info("Payment confirmed for order: {$orderId}");
    }
}

// Always return 200 OK to acknowledge receipt
http_response_code(200);
echo json_encode(['status' => 'ok']);