README

mainul/pay-station-disbursement is a Laravel package for the PayStation bKash disbursement API.

It currently implements the two documented endpoints:

The package is designed for Laravel 11, 12, and 13, uses Laravel's HTTP client, validates request payloads before sending them, and throws explicit exceptions for configuration, validation, transport, and API-level failures.

Features

• Laravel auto-discovery support (zero-config registration)
• Publishable configuration file with environment variable support
• Typed request payload and response objects (DTOs)
• Clear exception hierarchy for operational failures
• Runtime credential overrides for multi-merchant use cases
• Built-in request validation before HTTP calls
• Configurable timeout and retry logic
• Testbench test coverage for the documented endpoints

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x, or 13.x

Installation

Install the package with Composer:

composer require mainul/pay-station-disbursement

The service provider and facade are registered automatically via Laravel's package auto-discovery.

Publish the config file:

php artisan vendor:publish --tag=bkash-disbursement-config

This publishes config/bkash-disbursement.php to your application's config directory.

Configuration

Add these values to your .env file:

BKASH_DISBURSEMENT_BASE_URL=https://api.paystation.com.bd
BKASH_DISBURSEMENT_MERCHANT_ID=your_merchant_id
BKASH_DISBURSEMENT_PASSWORD=your_hashed_password
BKASH_DISBURSEMENT_PORTAL_KEY=your_portal_key

Optional configuration (with defaults):

BKASH_DISBURSEMENT_TIMEOUT=30
BKASH_DISBURSEMENT_CONNECT_TIMEOUT=10
BKASH_DISBURSEMENT_RETRY_TIMES=1
BKASH_DISBURSEMENT_RETRY_SLEEP=200

Note: The API requires the password to be sent in hashed form. The package does not hash it for you -- store the pre-hashed value in your environment.

Usage

Disbursement request

Using the DisbursementPayload DTO:

use Mainul12501\BkashDisbursement\Data\DisbursementPayload;
use Mainul12501\BkashDisbursement\Facades\BkashDisbursement;

$response = BkashDisbursement::disburse(new DisbursementPayload(
    invoiceNumber: '1213456789199973',
    bankType: 1,
    bankId: 2,
    accountNumber: '01726315133',
    amount: '20.00',
));

$response->transactionId;   // 73KIO6OC
$response->invoiceNumber;   // 1213456789199973
$response->amount;          // 20
$response->charge;          // 0.14
$response->transactionTime; // 2026-01-15 12:30:00
$response->message;         // The amount has been disbursed successfully

You can also pass a plain array:

$response = BkashDisbursement::disburse([
    'invoice_number' => '1213456789199973',
    'bank_type' => 1,
    'bank_id' => 2,
    'acc_no' => '01726315133',
    'amount' => '20.00',
]);

Transaction status

use Mainul12501\BkashDisbursement\Facades\BkashDisbursement;

$status = BkashDisbursement::status('178881732008099');

if ($status->isSuccessful()) {
    // Disbursement completed successfully.
    $status->transactionId;
    $status->amount;
}

if ($status->isNotFound()) {
    // No transaction matched the invoice number.
}

$status->message;

Dependency injection

use Mainul12501\BkashDisbursement\Contracts\BkashDisbursementClient;

class CheckDisbursementStatusAction
{
    public function __construct(
        private readonly BkashDisbursementClient $client,
    ) {
    }

    public function handle(string $invoiceNumber): string
    {
        return $this->client->status($invoiceNumber)->message;
    }
}

Runtime credential overrides

Useful when your application serves multiple merchants:

use Mainul12501\BkashDisbursement\Contracts\BkashDisbursementClient;

$client = app(BkashDisbursementClient::class)
    ->withCredentials(
        merchantId: 'another-merchant-id',
        password: 'another-hashed-password',
        requestFromMerchantPortalKey: 'another-portal-key',
    );

$response = $client->disburse([
    'invoice_number' => 'INV-2026-0001',
    'bank_type' => 1,
    'bank_id' => 2,
    'acc_no' => '01726315133',
    'amount' => '20.00',
]);

Error handling

The package throws specific exceptions so callers can handle failures precisely:

use Mainul12501\BkashDisbursement\Exceptions\ApiException;
use Mainul12501\BkashDisbursement\Exceptions\HttpRequestException;
use Mainul12501\BkashDisbursement\Exceptions\InvalidConfigurationException;
use Mainul12501\BkashDisbursement\Exceptions\RequestValidationException;
use Mainul12501\BkashDisbursement\Exceptions\UnexpectedResponseException;
use Mainul12501\BkashDisbursement\Facades\BkashDisbursement;

try {
    $response = BkashDisbursement::disburse([
        'invoice_number' => 'INV-2026-0001',
        'bank_type' => 1,
        'bank_id' => 2,
        'acc_no' => '01726315133',
        'amount' => '20.00',
    ]);
} catch (RequestValidationException $e) {
    // Local payload validation failed before the HTTP request was sent.
    $errors = $e->errors; // array keyed by field name
} catch (InvalidConfigurationException $e) {
    // Required credentials are missing from config or runtime overrides.
    $message = $e->getMessage();
} catch (HttpRequestException $e) {
    // The remote API returned a non-2xx response or could not be reached.
    $status = $e->httpStatus;     // ?int
    $body   = $e->responseBody;   // ?string
} catch (ApiException $e) {
    // The remote API returned an application-level failure (e.g. duplicate invoice).
    $apiCode     = $e->apiStatusCode; // ?string
    $apiResponse = $e->response;      // array
} catch (UnexpectedResponseException $e) {
    // The remote API returned a malformed or non-JSON response.
    $body = $e->responseBody; // ?string
}

Exception hierarchy

RuntimeException
 └── BkashDisbursementException
      ├── RequestValidationException
      ├── InvalidConfigurationException
      ├── HttpRequestException
      ├── ApiException
      └── UnexpectedResponseException

Response objects

DisbursementResponse

Returned by the disburse() method.

DisbursementStatusResponse

Returned by the status() method.

Helper methods:

Validation rules

The DisbursementPayload is validated before each request:

Testing

Run the package tests with:

composer test

API reference

The package was implemented from the PayStation bKash disbursement API documentation. The two supported endpoints are:

• Disbursement request: POST https://api.paystation.com.bd/merchant/disbursement/request
• Status check: POST https://api.paystation.com.bd/merchant/disbursement/status

Request headers (sent automatically by the package):

Disbursement form fields: invoice_number, bank_type, bank_id, acc_no, amount

Status form fields: invoice_number

License

This package is open-sourced software licensed under the MIT license.