API Documentation - Gateway Monitor

1. Authentication

All API requests must be authenticated using your API Key. You can provide your API Key via HTTP Headers (X-API-Key / Authorization) or directly inside the JSON request body (api_key field).

Base URL: https://bd-prm.q-bdpay.com/public/api

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

# Optional HMAC Security Headers:
X-Timestamp: 1689000000
X-Signature: YOUR_HMAC_SHA256_SIGNATURE

2. Create Payment

Initialize a new payment session. The API returns a payment URL to redirect your customer to complete the checkout.

POST /api.php?path=v2/payments (or /api/v2/payments)

Request Payload (JSON)

{
    "api_key": "YOUR_API_KEY",
    "operator": "bkash",
    "amount": 500.00,
    "customer_phone": "01712345678",
    "reference": "ORD1001",
    "callback_url": "https://merchant.com/callback"
}

Parameters

Field	Type	Required	Description
`api_key`	string	Required*	Your Merchant API Key (*can be sent in header `X-API-Key` or body).
`operator`	string	Required	Payment method: `bkash`, `nagad`, `rocket`, `upay`
`amount`	float	Required	Payment amount in BDT (Min: 10, Max: 500,000).
`customer_phone`	string	Required	Customer mobile number (e.g. `01712345678`).
`reference`	string	Optional	Your internal Order/Invoice ID for tracking.
`callback_url`	string	Optional	URL to receive instant HTTP POST webhook when payment completes.

Success Response (201 Created)

{
    "status": "success",
    "data": {
        "payment_id": "PAY-85F0F8D98C2D",
        "payment_url": "https://deposit.adminbd.top/public/index.php?route=pay&id=PAY-85F0F8D98C2D",
        "operator": "bkash",
        "amount": 500.00,
        "customer_phone": "01712345678",
        "status": "pending",
        "created_at": "2026-07-22T03:32:00+06:00"
    }
}

3. Payment Status

Check the real-time status of a deposit request using the payment ID returned during creation.

GET /api.php?path=v2/payments/status&payment_id=PAY-85F0F8D98C2D&api_key=YOUR_API_KEY

Example Response

{
    "status": "success",
    "data": {
        "payment_id": "PAY-85F0F8D98C2D",
        "trxid": "8JN29JK10",
        "operator": "bkash",
        "amount": 500.00,
        "customer_phone": "01712345678",
        "status": "success",
        "error_message": null,
        "created_at": "2026-07-22 03:32:00",
        "completed_at": "2026-07-22 03:35:00"
    }
}

4. Verify Transaction

Verify if a specific transaction ID exists and matches a payment request.

POST /api.php?path=v2/payments/verify

Request Payload

{
    "api_key": "YOUR_API_KEY",
    "trxid": "8JN29JK10",
    "payment_id": "PAY-85F0F8D98C2D"
}

Response

{
    "status": "success",
    "data": {
        "payment_id": "PAY-85F0F8D98C2D",
        "trxid": "8JN29JK10",
        "operator": "bkash",
        "amount": 500.00,
        "status": "success",
        "completed_at": "2026-07-22 03:35:00"
    }
}

5. Callback

The system will send an HTTP POST request callback to your provided callback_url when a payment succeeds.

Important: Your callback script must respond with HTTP Status 200 OK. If the response is not 200, the gateway will queue the webhook for automatic retries.

Example Payload Sent to You

{
    "payment_id": "PAY-85F0F8D98C2D",
    "status": "success",
    "amount": 500.00,
    "operator": "bkash",
    "trxid": "8JN29JK10",
    "timestamp": "2026-07-22T03:32:00+06:00"
}

6. Webhook

Webhooks notify you of global events outside of standard user checkouts. If your server does not return HTTP 200, the webhook system will automatically retry delivery following the same payload structure as the Callback.

Webhook Payload Format

{
    "payment_id": "PAY-85F0F8D98C2D",
    "status": "success",
    "amount": 500.00,
    "operator": "bkash",
    "trxid": "8JN29JK10",
    "timestamp": "2026-07-22T03:32:00+06:00"
}

7. Error Codes

Code	Meaning
400	Invalid Request (Missing parameters)
401	Unauthorized (Invalid API Key or Signature)
403	Forbidden (Account inactive)
404	Not Found (Transaction or Request ID does not exist)
409	Duplicate Transaction
422	Validation Error (Invalid amount or format)
429	Rate Limit Exceeded
500	Internal Server Error

8. PHP Integration

A simple PHP cURL example to create a payment.

<?php
$apiKey = 'YOUR_API_KEY';
$secret = 'YOUR_SECRET_KEY';

$payload = json_encode([
    'api_key'        => $apiKey,
    'operator'       => 'bkash',
    'amount'         => 500.00,
    'customer_phone' => '01712345678',
    'reference'      => 'ORD1001',
    'callback_url'   => 'https://merchant.com/callback'
]);

$timestamp = time();
$signature = hash_hmac('sha256', $timestamp . $payload, $secret);

// Use raw api.php?path=v2/payments to bypass potential .htaccess rewrite discrepancies
$ch = curl_init('https://bd-prm.q-bdpay.com/public/api.php?path=v2/payments');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey,
    'X-Timestamp: ' . $timestamp,
    'X-Signature: ' . $signature
]);

$response = curl_exec($ch);
curl_close($ch);

$resData = json_decode($response, true);
if (isset($resData['status']) && $resData['status'] === 'success') {
    // Redirect customer to hosted checkout page
    $paymentUrl = $resData['data']['payment_url'];
    header('Location: ' . $paymentUrl);
    exit;
} else {
    echo "Error: " . ($resData['message'] ?? 'Unable to initiate payment.');
}
?>

Merchant API Documentation