bursapay / bursapay-php

dev-main 2026-08-09 11:12 UTC

Requires

• php: >=8.0
• ext-hash: *
• ext-json: *
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^9.5 || ^10.0

MIT

• BursaPay Developer Team

• api
• payments
• sdk
• gateway
• paystack
• fintech
• bursapay

Published on Packagist.org on 2026-08-09 11:18 UTC

README

Official PHP SDK for integrating with the BursaPay Payment Gateway API.

Installation

Install via Composer:

composer require bursapay/bursapay-php

Quick Start

Initialize Client

use BursaPay\BursaPay;

$bursapay = new BursaPay(getenv('BURSAPAY_API_KEY'));

Usage Examples

1. Initialize a Payment

$response = $bursapay->payments->initialize([
    'amount' => 5000.00, // ₦5,000.00
    'email' => '[e-mail]',
    'currency' => 'NGN',
    'callback_url' => 'https://yoursite.com/payment/callback',
    'metadata' => [
        'order_id' => 'ORD-99120',
    ],
]);

// Redirect customer to checkout authorization URL
$checkoutUrl = $response['data']['authorization_url'];
$reference = $response['data']['reference'];

2. Verify Payment

$reference = 'BP_REF_123456789';
$verification = $bursapay->payments->verify($reference);

if ($verification['data']['status'] === 'success') {
    echo "Payment of ₦" . $verification['data']['amount'] . " confirmed!";
}

3. Dedicated Virtual Accounts

$account = $bursapay->virtualAccounts->create([
    'customer_email' => '[e-mail]',
    'bvn' => '12345678901',
    'preferred_bank' => 'Wema Bank',
]);

echo "Virtual Account Number: " . $account['data']['account_number'];

4. Verify Webhooks Safely

use BursaPay\Resources\Webhooks;
use BursaPay\Exceptions\SignatureVerificationException;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BURSAPAY_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_BURSAPAY_TIMESTAMP'] ?? '';
$secret = getenv('BURSAPAY_WEBHOOK_SECRET');

try {
    $event = Webhooks::constructEvent($payload, $signature, $timestamp, $secret);

    switch ($event['event']) {
        case 'payment.success':
            $paymentData = $event['data'];
            // Process order fulfillments...
            break;
        case 'dispute.created':
            // Log dispute notification...
            break;
    }

    http_response_code(200);
    echo json_encode(['status' => 'success']);
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    echo json_encode(['error' => $e->getMessage()]);
}

Error Handling

All SDK exceptions inherit from BursaPay\Exceptions\BursaPayException:

use BursaPay\Exceptions\AuthenticationException;
use BursaPay\Exceptions\InvalidRequestException;
use BursaPay\Exceptions\RateLimitException;
use BursaPay\Exceptions\BursaPayException;

try {
    $response = $bursapay->payments->initialize([...]);
} catch (AuthenticationException $e) {
    echo "Invalid API Key: " . $e->getMessage();
} catch (InvalidRequestException $e) {
    echo "Validation error: " . $e->getMessage();
} catch (RateLimitException $e) {
    echo "Rate limit exceeded. Retry later.";
} catch (BursaPayException $e) {
    echo "General API error: " . $e->getMessage();
}

License

MIT License. See LICENSE for details.