Home / Docs / DGePay Experimental

DGePay

Status: experimental · Driver: dgepay · Refunds: no (use the DGePay merchant panel) · Sync: yes

DGePay is a Bangladesh Bank-licensed payment service operator. Its hosted checkout covers bKash, Nagad and other mobile wallets.

Experimental. DGePay's API guide is only given to merchants. This driver is built from the provider's published SDK. Request the integration guide and UAT credentials from DGePay, and verify the driver against UAT before going live.

Setup

DGEPAY_CLIENT_ID=
DGEPAY_CLIENT_SECRET=
DGEPAY_API_KEY=
DGEPAY_SANDBOX=true

// config/bdpaygate.php → gateways
'dgepay' => [
    'driver' => 'dgepay',
    'client_id' => env('DGEPAY_CLIENT_ID'),
    'client_secret' => env('DGEPAY_CLIENT_SECRET'),
    'api_key' => env('DGEPAY_API_KEY'),
    'sandbox' => env('DGEPAY_SANDBOX', true), // true = UAT

    // Optional:
    // 'base_url' => 'https://api-dev.dgepay.net/dipon/v3', // DGePay's DEV environment
    // 'failed_status_codes' => ['4'], // status codes treated as a definite failure
    // 'token_ttl' => 300,             // seconds, if the JWT has no exp claim
],

Capabilities

How a payment is verified

1. Authenticate. POST /payment_gateway/authenticate with Authorization: Basic base64(client_id:client_secret), plus the same two values in the JSON body. The JWT that comes back is cached until its exp claim, less a minute. If DGePay answers 401, the driver fetches a new token and retries once.

2. Initiate. POST /payment_gateway/initiate_payment sends amount, unique_txn_id, redirect_url and note. It also sends customer_token and payment_method (null unless you pass payment_method in $meta), and payee_information when the customer phone is a Bangladeshi mobile number.

   • unique_txn_id is this attempt's gateway_reference, new for every attempt.
   • The body is encrypted: JSON with sorted keys → AES-128-ECB (PKCS#7) → base64. The key is the client secret, padded with 0 or cut to 16 bytes.
   • The Signature header is base64(HMAC-SHA256(api key, canonical)). canonical is the same sorted JSON with { } " : , and spaces removed, so {"amount":150.0,"note":"Order 1"} becomes amount150.0noteOrder1. Nulls appear as null, and amounts as 150.0 or 150.5.
   • The customer is redirected to data.webview_url.

3. Return. DGePay returns the customer to /bdpaygate/dgepay/callback?data=<encrypted JSON>.

   • Query-string parsing turns + into spaces, so the driver restores the + signs, then decrypts.
   • Only unique_txn_id is used from the decrypted payload, to find the payment. Its status_code is ignored.

4. Confirm. POST /payment_gateway/check_transaction_status (encrypted and signed in the same way) gives the result:

   data.status_code	Result
   3	Completed, if data.amount matches
   8	Cancelled
   4 (failed_status_codes)	Failed
   anything else, or no data	stays pending

   On completion, txn_id goes into gateway_payment_id and txn_number into gateway_transaction_id.

Limits and quirks

• Errors come back with HTTP 200. The body has "success": 0 and an error list. The driver reads the body.
• Plain JSON is rejected. DGePay answers it with REQUESTED_PARAMETERS_ARE_MISMATCHED. Every call after authentication must be encrypted and signed.
• AES-ECB is DGePay's choice. It is a weak mode, used here only because the API requires it. Keep the client secret and API key out of version control.
• Signature formatting is strict. Numeric-looking strings (phone numbers, +88) are signed as given. Only real numbers are rendered as JSON numbers.

Unverified

These points come from DGePay's published SDK, not from the request-only API guide:

• The full status-code table. 3 (success) and 8 (cancelled) are documented. 4 comes from an SDK sample whose message is "TRANSACTION FAILED". Every other code is treated as pending.
• How amounts with two decimal places (150.25) appear in the signature. The driver uses the JSON form, 150.25. One unofficial client rounds to one decimal place instead.
• Whether authenticate also needs the body credentials. The SDK sends Basic auth only. This driver sends both.
• Whether payee_information and payment_method are validated.
• How long a token lasts, beyond the JWT exp claim.
• Whether DGePay has a webhook/IPN or a refund API. None is known.
• How to get UAT or DEV credentials.

Edit this page on GitHubView as Markdown