API Documentation

X-API-KEY: bgk_your_api_key_here
X-API-SECRET: bgs_your_api_secret_here
Content-Type: application/json
Accept: application/json

{
  "success": false,
  "error": "Insufficient wallet balance",
  "type": "INSUFFICIENT_BALANCE",
  "message": "Your wallet balance (GH₵2.50) is too low for this order (GH₵5.00)."
}

<?php

class BundlesGhana
{
    private $apiKey;
    private $apiSecret;
    private $baseUrl = 'http://www.fripalconnectgh.com/api/v1';

    public function __construct($apiKey, $apiSecret)
    {
        $this->apiKey    = $apiKey;
        $this->apiSecret = $apiSecret;
    }

    private function request($method, $endpoint, $data = [])
    {
        $url  = $this->baseUrl . $endpoint;
        $ch   = curl_init();
        $headers = [
            'X-API-KEY: '    . $this->apiKey,
            'X-API-SECRET: ' . $this->apiSecret,
            'Content-Type: application/json',
            'Accept: application/json',
        ];

        curl_setopt_array($ch, [
            CURLOPT_URL            => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => $headers,
            CURLOPT_TIMEOUT        => 30,
            CURLOPT_SSL_VERIFYPEER => true,
        ]);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return json_decode($response, true);
    }

    public function getBundles($network = null)
    {
        $ep = '/bundles' . ($network ? '?network=' . $network : '');
        return $this->request('GET', $ep);
    }

    public function placeOrder($bundleId, $phone, $webhookUrl = null)
    {
        $data = ['bundle_id' => $bundleId, 'phone' => $phone];
        if ($webhookUrl) $data['webhook_url'] = $webhookUrl;
        return $this->request('POST', '/order', $data);
    }

    public function placeBulkOrder($bundleId, array $phones, $webhookUrl = null)
    {
        $data = ['bundle_id' => $bundleId, 'phones' => $phones];
        if ($webhookUrl) $data['webhook_url'] = $webhookUrl;
        return $this->request('POST', '/order/bulk', $data);
    }

    public function getOrderStatus($reference)
    {
        return $this->request('GET', '/order/status/' . urlencode($reference));
    }

    public function getBalance()
    {
        return $this->request('GET', '/wallet/balance');
    }
}

$api = new BundlesGhana(
    'bgk_your_api_key_here',
    'bgs_your_api_secret_here'
);

// 1. Get all MTN bundles
$bundles = $api->getBundles('MTN');
if ($bundles['success']) {
    foreach ($bundles['bundles'] as $bundle) {
        echo $bundle['volume'] . ' — GH₵' . $bundle['price'] . "\n";
    }
}

// 2. Check balance before ordering
$wallet = $api->getBalance();
if ($wallet['balance'] < 5.00) {
    die('Insufficient balance!');
}

// 3. Place order (bundle_id 1 = MTN 1GB at GH₵5.00)
$order = $api->placeOrder(
    1,                                         // bundle_id
    '0241234567',                              // recipient phone
    'https://yoursite.com/webhook/bundles'    // optional webhook
);

if ($order['success']) {
    $ref = $order['order']['reference'];
    echo "Order placed! Reference: " . $ref;

    // Save $ref to your database for tracking
} else {
    echo "Error: " . $order['message'];
}

$api = new BundlesGhana('bgk_your_api_key', 'bgs_your_secret');

// Send MTN 1GB (bundle_id=1) to 3 numbers
$result = $api->placeBulkOrder(
    1,
    ['0241234567', '0201234567', '0551234567'],
    'https://yoursite.com/webhook/bundles'
);

if ($result['success']) {
    $bulkRef    = $result['bulk_order']['reference'];
    $totalCost  = $result['bulk_order']['total_price'];
    echo "Bulk order ref: {$bulkRef} — Cost: GH₵{$totalCost}";
}

$api = new BundlesGhana('bgk_your_api_key', 'bgs_your_secret');
$ref = 'BUD-API-A1B2C3D4-143022'; // saved from order placement

$maxAttempts = 10;
$attempt     = 0;

while ($attempt++ < $maxAttempts) {
    $result = $api->getOrderStatus($ref);
    $status = $result['order']['status'] ?? 'unknown';

    if ($status === 'delivered') {
        echo "✓ Delivered at: " . $result['order']['delivered_at'];
        break;
    }

    if (in_array($status, ['failed', 'cancelled'])) {
        echo "✗ Order {$status}";
        break;
    }

    echo "Status: {$status} — waiting...\n";
    sleep(8); // wait 8 seconds before next check
}

<?php
// webhook.php — your webhook endpoint

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

if (!$payload || $payload['event'] !== 'order.status.updated') {
    http_response_code(400);
    exit;
}

$reference = $payload['reference'];
$status    = $payload['status'];

// Update your database
switch ($status) {
    case 'delivered':
        // Mark order as complete in your DB, notify customer etc.
        markOrderDelivered($reference, $payload['delivered_at']);
        break;
    case 'failed':
        // Handle failed order, trigger refund logic etc.
        markOrderFailed($reference);
        break;
}

// Always return 200 quickly
http_response_code(200);
echo json_encode(['received' => true]);