payguard/sdk

Official PHP SDK for PayGuard Payment Orchestration Platform

v1.0.1 2026-07-15 17:33 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Md. Sanaullah Asif

• payment
• tap
• bangladesh
• bkash
• nagad
• payguard

Published on Packagist.org on 2026-07-15 17:34 UTC

README

PayGuard PHP SDK

Accept payments via bKash, Nagad, TAP and more through one unified API — without per-transaction commission.

Installation

composer require payguard/sdk

Quick Start

use PayGuard\PayGuard;
use PayGuard\Exceptions\PayGuardException;

$pg = new PayGuard('your-api-key');

Create & Initiate Payment

bKash Payment

// 1. Create transaction
$transaction = $pg->createTransaction([
    'mfs_connection_id' => 1,          // Your bKash connection ID
    'amount'            => 500,        // BDT
    'reference_id'      => 'ORDER-123', // Your order ID (optional, idempotent)
    'customer_number'   => '01700000000',
    'customer_name'     => 'John Doe',
    'callback_url'      => 'https://yoursite.com/ipn', // IPN endpoint
]);

// 2. Initiate bKash payment
$payment = $pg->initiateBkash($transaction->getId());

// 3. Redirect customer to bKash checkout
header('Location: ' . $payment->getCheckoutUrl());
exit;

Nagad Payment

$transaction = $pg->createTransaction([
    'mfs_connection_id' => 2,
    'amount'            => 300,
    'customer_number'   => '01700000000',
]);

$payment = $pg->initiateNagad($transaction->getId());
header('Location: ' . $payment->getCheckoutUrl());

TAP Wallet (iFrame)

$transaction = $pg->createTransaction([
    'mfs_connection_id' => 3,
    'amount'            => 200,
]);

$tapConfig = $pg->initiateTap($transaction->getId());
// Pass $tapConfig to your view — load TAP script + call tapIFrame()

Check Payment Status

$transaction = $pg->getTransaction('ORDER-123'); // by reference_id

if ($transaction->isSuccess()) {
    // Payment confirmed — fulfill order
    echo "Payment received: ৳" . $transaction->getAmount();
    echo "TXN ID: " . $transaction->getMfsTransactionId();
}

if ($transaction->isFailed()) {
    echo "Payment failed: " . $transaction->getFailureReason();
}

Handle IPN Webhook

// Your IPN endpoint (POST https://yoursite.com/ipn)
$pg = new PayGuard('your-api-key');

try {
    $payload = $pg->parseWebhook(
        rawBody:       file_get_contents('php://input'),
        webhookSecret: 'your-webhook-secret', // from MFS connection settings
        signature:     $_SERVER['HTTP_X_PAYGUARD_SIGNATURE'] ?? ''
    );

    $referenceId = $payload['reference_id'];
    $status      = $payload['status'];
    $amount      = $payload['amount'];
    $event       = $payload['event']; // payment.success or payment.failed

    if ($event === 'payment.success') {
        // Mark order as paid in your system
        markOrderAsPaid($referenceId, $amount);
    }

    http_response_code(200);
    echo 'OK';

} catch (\PayGuard\Exceptions\PayGuardException $e) {
    http_response_code(400);
    echo 'Invalid webhook';
}

Laravel Integration

// config/services.php
'payguard' => [
    'api_key'  => env('PAYGUARD_API_KEY'),
    'base_url' => env('PAYGUARD_BASE_URL', 'https://app.sourcemonkey.online/api/v1'),
],

// AppServiceProvider.php
$this->app->singleton(\PayGuard\PayGuard::class, function () {
    return new \PayGuard\PayGuard(
        config('services.payguard.api_key'),
        config('services.payguard.base_url'),
    );
});

// In controller
use PayGuard\PayGuard;

class CheckoutController extends Controller
{
    public function __construct(private PayGuard $pg) {}

    public function pay(Request $request)
    {
        $transaction = $this->pg->createTransaction([
            'mfs_connection_id' => 1,
            'amount'            => $request->amount,
            'reference_id'      => $request->order_id,
            'callback_url'      => route('ipn'),
        ]);

        $payment = $this->pg->initiateBkash($transaction->getId());
        return redirect($payment->getCheckoutUrl());
    }

    public function ipn(Request $request)
    {
        $payload = $this->pg->parseWebhook(
            $request->getContent(),
            config('services.payguard.webhook_secret'),
            $request->header('X-PayGuard-Signature')
        );

        if ($payload['event'] === 'payment.success') {
            Order::where('id', $payload['reference_id'])->update(['status' => 'paid']);
        }

        return response('OK');
    }
}

Error Handling

use PayGuard\Exceptions\PayGuardException;
use PayGuard\Exceptions\AuthenticationException;
use PayGuard\Exceptions\ValidationException;

try {
    $transaction = $pg->createTransaction([...]);
} catch (AuthenticationException $e) {
    // Invalid API key
    echo "Auth failed: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid parameters
    echo "Validation errors: ";
    print_r($e->errors);
} catch (PayGuardException $e) {
    // Other errors
    echo "Error [{$e->errorCode}]: " . $e->getMessage();
}

Available Methods

Method	Description
createTransaction(array)	Create payment transaction
getTransaction(string)	Get by reference ID
listTransactions(array)	List with filters
getTransactionSummary(array)	Stats summary
initiateBkash(int)	Start bKash payment
queryBkash(int)	Check bKash status
refundBkash(int, float)	Refund bKash
initiateNagad(int)	Start Nagad payment
queryNagad(int)	Check Nagad status
initiateTap(int)	Get TAP iFrame config
queryTap(int)	Check TAP status
getConnections()	List MFS connections
testConnection(int)	Test a connection
getSubscription()	Get subscription
getPlans()	Available plans
verifyWebhook(...)	Verify IPN signature
parseWebhook(...)	Parse + verify IPN

Get API Key

Login to your merchant dashboard: https://app.sourcemonkey.online/merchant/api

Support

• Email: [e-mail]
• Documentation: https://app.sourcemonkey.online/merchant/api