Download the PHP package tamimiqbal/dgepay-php without Composer

DGePay PHP Client

⚠️ Disclaimer
This is an unofficial community-driven integration for DGePay.
This project is not affiliated with or endorsed by DGePay or Bangladesh Bank.

Developer: Tamim Iqbal — IT Manager & AI Developer

A complete PHP SDK for the DGePay Payment Gateway API (Bangladesh). Supports bKash, Nagad, and other MFS (Mobile Financial Service) providers through the DGePay payment aggregator.

Built from real-world production integration, with all the undocumented gotchas already handled.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Laravel Integration
• API Reference
  • Authentication
  • Initiate Payment
  • Handle Callback
  • Check Transaction Status
  • Utilities
• Payment Flow
• Status Codes
• Gotchas & Troubleshooting
• Security Notes
• Testing
• License

Features

• Complete API coverage — Authentication, payment initiation, callback handling, and transaction status checks
• AES-128-ECB encryption — Automatic payload encryption/decryption as required by DGePay
• HMAC-SHA256 signatures — Correct signature generation matching DGePay API documentation v1.9
• Callback decryption — Handles encrypted callback data with base64 + character fix
• Laravel integration — Service provider, facade, and config publishing out of the box
• Framework-agnostic — Works with any PHP 8.1+ project (uses cURL internally)
• Production-tested — Built from a live integration, with all edge cases and undocumented behaviors handled

Requirements

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

Installation

Via Composer

Manual Installation

Clone or download the repository, then include the autoloader:

Quick Start

Laravel Integration

Auto-Discovery

If you're using Laravel 5.5+, the service provider and facade are auto-discovered.

Manual Registration

Add to config/app.php:

Publish Config

Environment Variables

Add to your .env file:

Usage in Controllers

API Reference

Authentication

How it works:

• Sends HTTP Basic Auth header: base64(client_id:client_secret)
• POST body contains client_id and client_secret
• Returns a JWT access token used in subsequent requests

Note: You don't need to call authenticate() manually. It's called automatically by initiatePayment() and getTransactionStatus().

Initiate Payment

Returns on success:

Returns on failure:

Handle Callback

After payment, DGePay redirects the user to your redirectUrl with encrypted data:

⚠️ CRITICAL: PHP converts + to spaces in query strings. You MUST fix this before decryption.

Decrypted callback data structure:

Check Transaction Status

Utilities

Generate Transaction ID

Status Constants

Encrypt/Decrypt Payloads

Signature Generation

Custom Logger

Payment Flow

Authentication → Initiate Payment → User Pays → Callback → Verify → Activate

Status Codes

Gotchas & Troubleshooting

These are real issues encountered during production integration that are not documented in the official DGePay API docs.

1. Request Body Must Be AES Encrypted

The API requires all POST request bodies to be encrypted with AES-128-ECB using your client_secret as the key. Sending plain JSON will return:

This SDK handles encryption automatically.

2. PHP Converts + to Spaces in Query Strings

DGePay sends encrypted callback data as a base64-encoded query parameter:

PHP's $_GET and Laravel's $request->query() automatically convert + to spaces, breaking the base64 decoding. You must restore + before decryption:

This SDK's examples and documentation always include this fix.

3. Callback Uses status_code, Not status

The encrypted callback data uses status_code (integer: 3 for success, 8 for cancelled), not status. The parseCallbackResult() method handles both cases.

4. Signature — Numbers Must Be Formatted as Floats

Integer values (like amount: 15) must be formatted as "15.0" in the signature string. This SDK handles this automatically.

⚠️ Important: String values that look like numbers (phone numbers like "+8801712345678") must NOT be converted to floats. This SDK uses is_int() || is_float() type checks (not is_numeric()) to handle this correctly.

5. Signature — Nested Object Key Handling

For nested objects like meta_data, the parent key is printed once, then children are recursively flattened:

Not:

6. Authentication Uses Both Basic Auth AND Body Params

The /authenticate endpoint requires:

• Authorization: Basic base64(client_id:client_secret) header
• client_id and client_secret in the POST body

Both must be present.

7. LOG_LEVEL May Suppress Your Logs

If your Laravel app has LOG_LEVEL=warning (common in production), Log::info() calls will be silently suppressed. Use Log::warning() for important payment debugging.

8. The JS SDK Has Wrong Endpoints

DGePay's JavaScript SDK references endpoints like /payment/initiate which return 404. The correct API v3 endpoints are:

Security Notes

• Always verify callbacks server-side — Don't trust the callback data alone. Call getTransactionStatus() to verify with DGePay's API before activating orders.
• AES-128-ECB limitation — ECB mode doesn't use an IV and identical plaintext blocks produce identical ciphertext. This is DGePay's requirement, not a choice. Don't reuse this pattern in your own systems.
• Protect your credentials — Never commit client_id, client_secret, or client_api_key to version control. Use environment variables.

Testing

Tests cover:

• Signature generation (verified against official documentation example)
• Numeric string handling (phone numbers not converted to floats)
• Integer/float normalization
• Callback parsing (success, cancelled, plain query params, empty)
• AES encryption/decryption roundtrip
• Transaction ID generation
• Status code constants

Project Structure

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Credits

• Developer: Tamim Iqbal — IT Manager & AI Developer
• Website: tamimiqbal.com
• DGePay API Documentation: v1.9
• Built with real-world production testing against DGePay's live API