PHP SDK - PayBridgeNP

Installation

composer require paybridge-np/sdk

Initialization

use PayBridgeNP\PayBridgeNP;

$paybridgenp = new PayBridgeNP([
    'apiKey'     => getenv('PAYBRIDGENP_API_KEY'), // sk_test_... or sk_live_...
    'baseUrl'    => 'https://api.paybridgenp.com', // optional
    'timeout'    => 30,                            // optional, seconds. default: 30
    'maxRetries' => 2,                             // optional. default: 2
]);

`$paybridgenp->checkout`

`checkout->create(array $params)`

Creates a checkout session.

$session = $paybridgenp->checkout->create([
    'amount'    => 10000,                              // required - paisa (NPR × 100)
    'returnUrl' => 'https://yoursite.com/success',    // required
    'cancelUrl' => 'https://yoursite.com/cart',       // optional
    'provider'  => 'khalti',                          // optional - omit to let customer pick
    'currency'  => 'NPR',                             // optional, default: "NPR"
    'metadata'  => ['orderId' => 'ORD-001'],          // optional
]);

echo $session['checkout_url'];  // redirect customer here
echo $session['id'];            // cs_...
echo $session['expires_at'];    // ISO timestamp

Parameters:

Name	Type	Required	Description
`amount`	`int`	Yes	In paisa. NPR 100.00 = `10000`
`returnUrl`	`string`	Yes	Redirect URL after payment
`cancelUrl`	`string`	No	Redirect URL on cancellation
`provider`	`string`	No	`"esewa"`, `"khalti"`, `"fonepay"`
`currency`	`string`	No	Default: `"NPR"`
`metadata`	`array`	No	Passed through to webhooks and payment records

`checkout->expire(string $id)`

Marks a session as expired so it can no longer accept payment. Use this when you mint a fresh session for a logical purchase that already had one outstanding (e.g. a customer requesting a new payment link), so the old URL stops being payable immediately rather than waiting for its 30-minute TTL.

$paybridgenp->checkout->expire('cs_6f2jHn2…');

Idempotent: calling on an already-terminal session is a no-op that returns the current row state without error.

`checkout->get(string $id)`

Fetches a checkout session by ID: its current status, amount, customer, and any collected address. Read-only (sessions are created with checkout->create).

$session = $paybridgenp->checkout->get('cs_6f2jHn2…');

echo $session['status'];        // "pending" | "initiated" | "success" | ...
echo $session['amount'];        // paisa
echo $session['customerName'];  // camelCase on the read shape

Note: the read shape uses camelCase keys (customerName, expiresAt, …), unlike the snake_case checkout->create response.

`checkout->list(array $params = [])`

Lists checkout sessions for the project, newest first.

$response = $paybridgenp->checkout->list([
    'limit'  => 20,         // optional, 1 to 100 (default 25)
    'offset' => 0,          // optional
    'status' => 'success',  // optional filter
]);

echo $response['meta']['total'];

`$paybridgenp->paymentLinks`

Reusable hosted payment pages. Methods need an API key with the links:read or links:write scope.

`paymentLinks->create(array $params)`

$link = $paybridgenp->paymentLinks->create([
    'title'   => 'Donation',  // required
    'amount'  => 50000,       // paisa. Omit for a customer-entered amount (use minAmount/maxAmount)
    'maxUses' => 100,         // optional
]);

echo $link['url']; // public hosted payment page

`paymentLinks->list(array $params = [])`

$response = $paybridgenp->paymentLinks->list([
    'active' => true, // optional filter
    'limit'  => 20,   // optional
]);

`paymentLinks->get(string $id)`

Returns the link plus aggregated view and conversion stats.

$link = $paybridgenp->paymentLinks->get('lnk_…');

echo $link['stats']['views'];
echo $link['stats']['conversion_rate'];

`paymentLinks->update(string $id, array $params)`

Updates editable fields. Only the keys you pass are changed.

$paybridgenp->paymentLinks->update('lnk_…', ['active' => false]);

`paymentLinks->cancel(string $id)`

Deactivates a link so it can no longer accept payments, while keeping it and its history for your records. The recommended way to retire a link that has already been used.

$paybridgenp->paymentLinks->cancel('lnk_…');

`paymentLinks->delete(string $id)`

Permanently deletes a link. Allowed only when the link has never been used. Otherwise it returns 422; cancel it instead.

$paybridgenp->paymentLinks->delete('lnk_…');

`$paybridgenp->payments`

`payments->list(array $params = [])`

$response = $paybridgenp->payments->list([
    'limit'  => 20,  // optional, default 20, max 100
    'offset' => 0,   // optional, default 0
]);

echo $response['meta']['total'];

foreach ($response['data'] as $payment) {
    echo $payment['id'] . ' ' . $payment['amount'] . ' ' . $payment['status'];
}

`payments->get(string $id)`

$payment = $paybridgenp->payments->get('pay_6f2jHn2...');

echo $payment['status'];       // "success" | "failed"
echo $payment['amount'];       // paisa
echo $payment['provider'];     // "esewa" | "khalti" | ...
echo $payment['provider_ref']; // provider's transaction reference

`$paybridgenp->webhooks`

`webhooks->create(array $params)`

$endpoint = $paybridgenp->webhooks->create([
    'url'    => 'https://yoursite.com/webhooks/paybridgenp',
    'events' => ['payment.succeeded', 'payment.failed'], // optional - omit for all
]);

echo $endpoint['signing_secret']; // save this - shown only once

`webhooks->list()`

$response = $paybridgenp->webhooks->list();
foreach ($response['data'] as $wh) {
    echo $wh['id'] . ' ' . $wh['url'];
}

`webhooks->delete(string $id)`

$paybridgenp->webhooks->delete('wh_...');

`PayBridgeNP::constructEvent(string $body, string $signature, string $secret)` (static)

Verifies a webhook signature and returns the parsed event. Use this in your webhook handler.

use PayBridgeNP\PayBridgeNP;
use PayBridgeNP\Exceptions\SignatureVerificationException;

$body      = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAYBRIDGENP_SIGNATURE'] ?? '';

try {
    $event = PayBridgeNP::constructEvent($body, $signature, getenv('PAYBRIDGENP_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit('Invalid signature');
}

switch ($event['type']) {
    case 'payment.succeeded':
        // $event['data']['id'], $event['data']['amount'], $event['data']['metadata']
        fulfillOrder($event['data']['metadata']['orderId'] ?? null);
        break;

    case 'payment.failed':
        notifyOrderFailed($event['data']['session_id']);
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

Throws SignatureVerificationException if:

The signature header is missing or malformed
The HMAC doesn’t match
The timestamp is more than 5 minutes old (replay attack protection)

`$paybridgenp->billing`

The billing methods provide access to plans, customers, subscriptions, and invoices. Billing API access requires the Growth plan or higher.

Plans

// Create a plan
$plan = $paybridgenp->plans->create([
    'name'          => 'Pro Monthly',
    'amount'        => 99900,   // paisa - NPR 999/month
    'intervalUnit'  => 'month',
    'intervalCount' => 1,
    'trialDays'     => 14,      // optional
]);

// List plans
$response = $paybridgenp->plans->list();

// Get a plan
$plan = $paybridgenp->plans->get('plan_...');

// Update a plan
$updated = $paybridgenp->plans->update('plan_...', ['name' => 'Pro Monthly v2']);

Customers

// Create a customer
$customer = $paybridgenp->customers->create([
    'name'               => 'Aarav Sharma',
    'email'              => 'aarav@example.com',
    'externalCustomerId' => 'user_123',  // optional
]);

// List customers
$response = $paybridgenp->customers->list();

// Get a customer
$customer = $paybridgenp->customers->get('cus_...');

// Update a customer
$updated = $paybridgenp->customers->update('cus_...', ['email' => 'new@example.com']);

// Delete a customer
$paybridgenp->customers->delete('cus_...');

Subscriptions

// Create a subscription
$sub = $paybridgenp->subscriptions->create([
    'customerId' => 'cus_...',
    'planId'     => 'plan_...',
]);

// List subscriptions
$response = $paybridgenp->subscriptions->list();

// Get a subscription
$sub = $paybridgenp->subscriptions->get('sub_...');

// Lifecycle actions
$paybridgenp->subscriptions->pause('sub_...');
$paybridgenp->subscriptions->resume('sub_...');
$paybridgenp->subscriptions->cancel('sub_...');

// Change plan
$paybridgenp->subscriptions->changePlan('sub_...', ['newPlanId' => 'plan_...']);

Invoices

// List invoices
$response = $paybridgenp->invoices->list([
    'subscriptionId' => 'sub_...',  // optional
]);

// Get an invoice
$invoice = $paybridgenp->invoices->get('inv_...');

echo $invoice['status'];      // "open" | "paid" | "overdue" | "void" | "uncollectible" | "write_off"
echo $invoice['amount_due'];  // paisa
echo $invoice['due_at'];      // ISO timestamp
echo $invoice['hosted_invoice_url']; // hosted payment link

Error handling

All SDK methods throw typed exceptions you can catch and inspect:

use PayBridgeNP\Exceptions\AuthenticationException;
use PayBridgeNP\Exceptions\PayBridgeException;

try {
    $paybridgenp->checkout->create(['amount' => 1000, 'returnUrl' => '...']);
} catch (AuthenticationException $e) {
    // Invalid API key
    error_log('Check your PAYBRIDGENP_API_KEY');
} catch (PayBridgeException $e) {
    error_log($e->getMessage());    // human-readable message
    error_log($e->getStatusCode()); // HTTP status
    error_log($e->getCode());       // machine-readable code
}

Exception classes

Class	Status	When
`AuthenticationException`	401	Invalid or missing API key
`InvalidRequestException`	400	Bad request parameters
`NotFoundException`	404	Resource not found
`RateLimitException`	429	Too many requests
`PayBridgeException`	5xx	Server error
`SignatureVerificationException`	-	Webhook HMAC mismatch or replay

Framework examples

Laravel

// config/services.php
'paybridgenp' => [
    'key'    => env('PAYBRIDGENP_API_KEY'),
    'secret' => env('PAYBRIDGENP_WEBHOOK_SECRET'),
],

// app/Http/Controllers/CheckoutController.php
use PayBridgeNP\PayBridgeNP;

class CheckoutController extends Controller
{
    public function create(Request $request)
    {
        $paybridgenp = new PayBridgeNP(['apiKey' => config('services.paybridgenp.key')]);

        $session = $paybridgenp->checkout->create([
            'amount'    => $request->amount,
            'returnUrl' => route('checkout.success'),
            'cancelUrl' => route('cart.index'),
            'metadata'  => ['orderId' => $request->order_id],
        ]);

        return redirect($session['checkout_url']);
    }
}

// app/Http/Controllers/WebhookController.php
use PayBridgeNP\PayBridgeNP;
use PayBridgeNP\Exceptions\SignatureVerificationException;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        try {
            $event = PayBridgeNP::constructEvent(
                $request->getContent(),
                $request->header('X-PayBridgeNP-Signature'),
                config('services.paybridgenp.secret'),
            );
        } catch (SignatureVerificationException $e) {
            return response()->json(['error' => 'Invalid signature'], 400);
        }

        if ($event['type'] === 'payment.succeeded') {
            Order::where('id', $event['data']['metadata']['orderId'] ?? null)
                ->update(['status' => 'paid']);
        }

        return response()->json(['received' => true]);
    }
}

​Installation

​Initialization

​$paybridgenp->checkout

​checkout->create(array $params)

​checkout->expire(string $id)

​checkout->get(string $id)

​checkout->list(array $params = [])

​$paybridgenp->paymentLinks

​paymentLinks->create(array $params)

​paymentLinks->list(array $params = [])

​paymentLinks->get(string $id)

​paymentLinks->update(string $id, array $params)

​paymentLinks->cancel(string $id)

​paymentLinks->delete(string $id)

​$paybridgenp->payments

​payments->list(array $params = [])

​payments->get(string $id)

​$paybridgenp->webhooks

​webhooks->create(array $params)

​webhooks->list()

​webhooks->delete(string $id)

​PayBridgeNP::constructEvent(string $body, string $signature, string $secret) (static)

​$paybridgenp->billing

​Plans

​Customers

​Subscriptions

​Invoices

​Error handling

​Exception classes

​Framework examples