Merchant API Documentation

Integrate the AutoDeposit Gateway into your application.
1. Authentication 2. Create Payment 3. Payment Status 4. Verify Transaction 5. Callback 6. Webhook 7. Error Codes 8. PHP Integration
1. Authentication

All API requests must be authenticated using your API Key and signed using your Secret Key to prevent tampering. Never expose your Secret Key to the frontend.

Base URL: https://bd-prm.q-bdpay.com/public/api 
Authorization: Bearer YOUR_API_KEY
X-Timestamp: 1689000000
X-Signature: XXXXX
Content-Type: application/json
2. Create Payment

Initialize a new payment session. The API returns a payment URL to redirect your user.

POST /api.php?path=v2/payments (or /api/v2/payments)
Request Payload
{
    "operator": "bkash",
    "amount": 500.00,
    "customer_phone": "01712345678",
    "reference": "ORD1001",
    "callback_url": "https://merchant.com/callback"
}
Success Response
{
    "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
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
{
    "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
$payload = json_encode([
    'operator' => 'bkash',
    'amount' => 500.00,
    'customer_phone' => '01712345678',
    'reference' => 'ORD1001',
    'callback_url' => 'https://merchant.com/callback'
]);

$apiKey = 'YOUR_API_KEY';
$secret = 'YOUR_SECRET_KEY';
$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.');
}
?>