Download the PHP package amdadulhaq/bd-payment-laravel without Composer

BD Payment for Laravel

Accept payments from Laravel via Bangladeshi gateways (bKash, Nagad, Upay, SSLCommerz) or a manual personal-number driver, all behind one driver-based API.

Contents

• Requirements
• Installation
• Configuration
• Which driver do I need?
• Accepting a payment
• Handling webhooks / IPN
• API reference
• Adding your own gateway
• Testing
• Troubleshooting
• Running the package's own test suite
• License

Requirements

• PHP 8.2, 8.3, 8.4, or 8.5
• Laravel 11, 12, or 13

Installation

The service provider and Payment facade are auto-discovered. Publish the config file:

Configuration

Set the default driver and credentials in your .env:

manual needs no merchant account at all — set a personal/agent number and start collecting payments immediately, reviewing each transaction ID by hand.

Or, for bKash:

Or, for Nagad:

Or, for Upay:

Or, for SSLCommerz:

See config/payment.php for every driver's options. PAYMENT_DRIVER defaults to manual, so nothing breaks in local/testing environments without gateway credentials.

Which driver do I need?

Start with manual if you don't have a merchant account yet — the rest of your app (checkout flow, plan activation, tests) works identically once you switch PAYMENT_DRIVER later, since every driver returns the same PaymentResponse shape.

Accepting a payment

After the payer returns from the gateway (or, for manual, once they report their transaction ID):

Check a payment's status any time without mutating anything:

Refund a completed payment (not every gateway/driver supports this):

Use a specific driver, or a driver other than the default, for one call — same as Storage::disk():

Handling webhooks / IPN

Some gateways notify your server directly instead of (or in addition to) redirecting the payer's browser back. Point that URL at a route in your app and hand the request straight to the driver:

Every driver verifies the notification before trusting it — never on the payload alone:

• SSLCommerz posts a real signed IPN (verify_sign/verify_key). handleWebhook() recomputes the signature from your store password and rejects anything that doesn't match, then still re-confirms the transaction via validationserverAPI as a second check.
• bKash, Nagad, and Upay have no signed server push — only a browser redirect carrying an ID in the query string, which anyone could forge. handleWebhook() treats that as a hint at most: it extracts the ID and calls the gateway's own status-check endpoint to get the real, authoritative status rather than trusting the query string.
• manual has no webhook concept — it throws PaymentException.

A forged or tampered payload throws AmdadulHaq\BdPayment\Exceptions\PaymentException rather than returning a fake "success".

API reference

PaymentRequest

Everything a driver might need to start a payment — pass what applies, ignore the rest (e.g. the manual driver ignores every URL field).

PaymentResponse

What every driver method returns, so calling code never branches on which gateway answered.

PaymentStatus

$status->isFinal() is true for every case except Initiated/Pending.

Adding your own gateway

Register a custom driver:

Any driver just needs to implement AmdadulHaq\BdPayment\Contracts\PaymentDriver:

Testing

Use Payment::fake() to swap the real gateway with an in-memory fake and assert on what would have been charged, without dispatching anything or hitting the network:

Troubleshooting

bKash: "Failed to grant an access token." Double-check BKASH_USERNAME/BKASH_PASSWORD (your Tokenized Checkout portal credentials, not your personal bKash PIN) and that BKASH_BASE_URL matches your environment — the sandbox and production base URLs are different hosts, not just different credentials.

Nagad: "Invalid merchant private key." / "Invalid Nagad public key." Both keys must be full PEM strings, including the -----BEGIN ... KEY----- / -----END ... KEY----- lines. When storing a multi-line key in .env, wrap it in quotes and use \n for line breaks, or load it from a file path instead (e.g. NAGAD_MERCHANT_PRIVATE_KEY=file:///path/to/key.pem combined with your own file_get_contents() in a custom service provider binding) rather than pasting it raw into .env.

SSLCommerz: handleWebhook() throws "IPN signature verification failed." Make sure the route receiving the IPN excludes Laravel's CSRF middleware (SSLCommerz's server can't obtain a CSRF token) and that you're passing the entire raw POST payload — $request->all() — to handleWebhook(), not a filtered subset, since the signature covers specific fields named in verify_key.

"Nothing happens" in local development PAYMENT_DRIVER defaults to manual, which never hits the network. If you're expecting a real gateway call, confirm .env actually sets PAYMENT_DRIVER to bkash/nagad/sslcommerz and that you ran php artisan config:clear after changing it (cached config wins over .env).

Running the package's own test suite

License

MIT. See LICENSE.md.