DGePay PHP Client: Complete Guide to Integrating Bangladesh Payment Gateway in PHP
← Back to Blogs
3 min read 587 words Tamim Iqbal

DGePay PHP Client: Complete Guide to Integrating Bangladesh Payment Gateway in PHP

DGePayPHP Payment GatewaybKash IntegrationNagad IntegrationLaravel PaymentPHP SDKBangladesh FinTech

Introduction

If you are building a payment-enabled application in Bangladesh, integrating mobile financial services like bKash and Nagad is essential. The dgepay-php-client is a complete PHP SDK that simplifies integration with the DGePay Payment Gateway API.

This library is built from real-world production experience and handles many undocumented issues developers typically face.

Disclaimer

This is an unofficial, community-driven SDK and is not affiliated with DGePay or Bangladesh Bank.

About the Developer

Developed by Tamim Iqbal, an IT Manager and AI Developer, this SDK reflects practical implementation insights from live payment systems.

Key Features

  • Complete API coverage: authentication, payment initiation, callback handling, transaction status verification
  • AES-128-ECB encryption (automatic)
  • HMAC-SHA256 signature generation
  • Callback decryption and base64 character fixes
  • Laravel integration: service provider, facade, and config publishing
  • Framework-agnostic (works with any PHP 8.1+ project using cURL)
  • Production-tested, handling real-world edge cases

Requirements

  • PHP 8.1 or higher
  • ext-curl for HTTP requests
  • ext-json for JSON encoding/decoding
  • ext-openssl for AES encryption/decryption

Installation

Using Composer

composer require tamimiqbal/dgepay-php

Manual Installation

require_once 'path/to/dgepay-api/src/DgePay.php';

Quick Start

use DgePay\DgePay;

$dgepay = new DgePay([
    'client_id'      => 'your_client_id',
    'client_secret'  => 'your_client_secret',
    'client_api_key' => 'your_api_key',
]);

$orderId = DgePay::generateTransactionId();

$result = $dgepay->initiatePayment([
    'amount'      => 2499.00,
    'description' => 'Pro Plan - 1 Year',
    'orderId'     => $orderId,
    'redirectUrl' => 'https://yoursite.com/payment/callback',
]);

if ($result['success']) {
    header('Location: ' . $result['payment_url']);
    exit;
}

Payment Flow

  1. Authenticate to obtain a JWT token
  2. Initiate payment and receive a payment URL
  3. Redirect user to the payment page
  4. User completes payment via bKash or Nagad
  5. Callback with encrypted data is received
  6. Decrypt and parse callback data
  7. Verify transaction via API and activate order

Authentication

$auth = $dgepay->authenticate();

if ($auth['success']) {
    echo $auth['access_token'];
}

Authentication uses both:

  • Basic Auth header (client_id:client_secret)
  • POST body containing client credentials
  • Returns JWT token for subsequent requests

Initiating Payment

$result = $dgepay->initiatePayment([
    'amount'      => 2499.00,
    'redirectUrl' => 'https://...',
    'orderId'     => 'DG20260317...',
]);

Success Response

[
  'success' => true,
  'payment_url' => 'https://checkout...',
  'transaction_id' => 'DG202603...'
]

Handling Callback

DGePay sends encrypted data via query string:

?data=encrypted_base64

Important Fix: PHP converts + to spaces. Restore before decryption:

$rawData = str_replace(' ', '+', $_GET['data']);

Decrypt and parse:

$decrypted = $dgepay->decryptCallbackData($rawData);
$result = $dgepay->parseCallbackResult($decrypted);

Verifying Payment

$status = $dgepay->getTransactionStatus($orderId);

if ($status['success'] && $status['data']['status_code'] == 3) {
    // Activate order
}

Status Codes

Code Meaning
3 Success
8 Cancelled

Utility Methods

DgePay::generateTransactionId();
DgePay::isSuccessStatus('3');
DgePay::isCancelledStatus('8');

$dgepay->encryptPayload($data);
$dgepay->decryptPayload($data);
$dgepay->generateSignature($data);

Gotchas & Troubleshooting

  1. AES Encryption Required: All API POST requests must be AES-128-ECB encrypted.
  2. Plus Character in Callback: Replace spaces with + before decoding base64.
  3. Status Code Field: Use status_code instead of status.
  4. Signature Formatting: Numbers must be floats (e.g., 15 → "15.0").
  5. Nested Metadata Handling: Flatten objects correctly without prefixes.
  6. Dual Authentication Requirement: Both header and body credentials required.
  7. Incorrect JS SDK Endpoints: This SDK fixes endpoint paths for API v3.

Security Notes

  • Always verify callbacks via API before activating orders
  • Keep credentials in environment variables
  • Be aware of AES-ECB limitations (used as required by DGePay)

Laravel Integration

Supports Laravel with service provider, facade, and config publishing. Example usage in a controller:

$result = $this->dgepay->initiatePayment([
    'amount' => 2499.00,
    'orderId' => DgePay::generateTransactionId(),
    'redirectUrl' => route('payment.callback'),
]);

Testing

composer install
./vendor/bin/phpunit

Includes tests for: signature generation, encryption/decryption, callback parsing, status handling.

Project Structure

  • src/ – Core SDK
  • Laravel/ – Laravel integration
  • examples/ – Usage samples
  • tests/ – Unit tests

License

MIT License — free to use and modify.

Conclusion

The dgepay-php-client is a production-ready PHP SDK for integrating DGePay. It handles encryption, signatures, and callback quirks, making integration with bKash, Nagad, and other MFS providers in Bangladesh reliable and straightforward.

Browse Archive