Developer REST API v2.4.0

Developer API Documentation

Integrate high-conversion bKash Personal and Merchant payments into your e-commerce platform or custom application.

HMAC-SHA256 Signatures Asia/Dhaka Service Hours Row-Level Lock Concurrency
1. Auth 2. Create 3. Hours 4. Webhooks 5. Callbacks 6. Examples
Security & Authentication

1. API Authentication

All merchant API requests require authentication. Pass your merchant secret key in the X-API-Key HTTP request header. Alternatively, you can include an api_key parameter in your JSON request body.

HTTP Header
X-API-Key: zp_live_9b83f0198c21a4e76d3e8b0...
Keep Keys Secret: Never expose your merchant API keys in client-side HTML or JavaScript. Always initiate payment session creation from your secure backend server.
Checkout Initiation

2. Create Payment Session

To redirect a customer to the payment gateway, generate a payment session by sending a POST request to /api/create.

POST https://pay.zarektia.site/api/create
Field Type Required Description
amount string|float Yes Payment amount in BDT (e.g. "500.00").
order_id string Yes Your unique internal invoice or merchant order ID.
method string Optional "bkash_personal" or "bkash_merchant". Omit to allow customer selection.
customer_name string Optional Customer's display name.
customer_phone string Optional Customer's phone number for contact.
callback_url string Yes Webhook URL where payment results and HMAC signatures are delivered.
return_url string Optional Redirect URL after customer completes verification.
JSON Request Payload:
{
  "amount": "500.00",
  "order_id": "ORD-2026-9810",
  "method": "bkash_personal",
  "customer_name": "Zarek Tia",
  "customer_phone": "01711000000",
  "callback_url": "https://yourdomain.com/api/payment-callback",
  "return_url": "https://yourdomain.com/orders/success?id=ORD-2026-9810"
}
Response (201 Created):
{
  "status": "success",
  "paymentID": "ZP_9F82A0B1C4",
  "order_id": "ORD-2026-9810",
  "amount": "500.00",
  "method": "bkash_personal",
  "payURL": "https://pay.zarektia.site/checkout?pid=ZP_9F82A0B1C4",
  "payment_status": "created"
}
Time-Based Gateways

3. Automated Service Hours Engine

Zarektia Pay automatically enforces operating hours in the Asia/Dhaka timezone. Gateways automatically shut OFF outside active hours without requiring manual intervention from the merchant administrator.

bKash Personal Standard Hours
10:00 AM - 05:00 PM BST
Send Money channel with TrxID validation
bKash Merchant Standard Hours
07:00 AM - 06:00 PM BST
Make Payment channel with Sender Phone verification
Offline Error Handling:

If a verification attempt occurs when the gateway is outside operating hours, the API returns HTTP 400 with code GATEWAY_SERVICE_CLOSED. The checkout page automatically renders the schedule notice and live Dhaka clock.

Unified Ingestion Endpoint

4. Unified Webhook Ingestion (webhook.php)

Configure your Android SMS forwarder, MacroDroid, Tasker, or automated daemon to send all incoming transaction notifications to the single /webhook.php endpoint. The engine automatically detects whether the incoming transaction is Personal or Merchant.

POST https://pay.zarektia.site/webhook.php
Accepts JSON body, form-urlencoded POST fields, or GET parameters. Direct /webhook.php access enabled.
bKash Personal Payload (with TrxID):
{
  "TrxID": "BJA39XZK1L",
  "amount": "100.00",
  "from": "01711000000",
  "timestamp": "2026-09-20 14:30:00"
}
bKash Merchant Payload (with Sender Phone):
{
  "number": "01826153835",
  "amount": "100.00",
  "raw": "You have received payment Tk 100.00 from 01826153835"
}
Important: Automatic Channel Classification

When a notification containing a TrxID is posted to webhook.php, it is stored for Personal verification. When a notification without a TrxID (or containing a Merchant payment message) is received, it is stored under Merchant verification where customers match by their 11-digit sender phone number. You may also explicitly pass ?method=bkash_personal or ?method=bkash_merchant.

Cryptographic Delivery

5. Signed Merchant Callbacks

When a payment is successfully verified, Zarektia Pay sends an HTTP POST request to your specified callback_url signed with HMAC-SHA256 in header X-Zarektia-Signature.

PHP Callback Verification & Order Fulfillment:
<?php
$rawPayload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ZAREKTIA_SIGNATURE'] ?? '';
$secretKey = 'YOUR_MERCHANT_CALLBACK_SECRET';

$expectedSignature = hash_hmac('sha256', $rawPayload, $secretKey);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    die('Invalid HMAC Signature');
}

$payload = json_decode($rawPayload, true);

if ($payload['status'] === 'success') {
    $orderId = $payload['order_id'];
    $amount = $payload['amount'];
    $paymentMethod = $payload['method'];
    $trxId = $payload['trx_id'] ?? null;
    $senderNumber = $payload['sender_number'] ?? null;

    // Fulfill customer order in database
}

http_response_code(200);
echo json_encode(['status' => 'acknowledged']);
Quick Integration

6. Ready-to-Use Code Samples

cURL (Command Line):
curl -X POST "https://pay.zarektia.site/api/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_MERCHANT_API_KEY" \
  -d '{
    "amount": "500.00",
    "order_id": "ORD-10023",
    "method": "bkash_personal",
    "customer_name": "Zarek Tia",
    "customer_phone": "01711000000",
    "callback_url": "https://yourdomain.com/api/payment-callback",
    "return_url": "https://yourdomain.com/checkout/success"
  }'
Node.js / JavaScript (Fetch):
const response = await fetch("https://pay.zarektia.site/api/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_MERCHANT_API_KEY"
  },
  body: JSON.stringify({
    amount: "500.00",
    order_id: "ORD-10023",
    method: "bkash_personal",
    customer_name: "Rahim Ahmed",
    customer_phone: "01711000000",
    callback_url: "https://yourdomain.com/api/payment-callback",
    return_url: "https://yourdomain.com/checkout/success"
  })
});

const data = await response.json();
if (data.status === "success") {
  // Redirect user to checkout payURL
  window.location.href = data.payURL;
}