Developer docs

API Documentation

নিজের সাইট বা অ্যাপ থেকে payment link তৈরি করুন, customer কে পাঠান, তারপর server থেকে যাচাই করে order confirm করুন। PHP, Node.js, Python বা cURL — যেটাই ব্যবহার করুন, নিয়ম একই।

Sandbox (test mode)

Account বা plan ছাড়াই পুরো integration test করতে পারবেন। নিচের URL ও key ব্যবহার করুন।

SANDBOXTest API credentials

Account, plan বা brand ছাড়াই API test করা যায়। আসল টাকা কাটে না।

https://sandbox.boishakhipay.com/api/v1
sbx_405d0c0f71ba3f3cef958718f0a36721
  • যেকোনো domain বা localhost থেকে call করা যায়; redirect_url brand domain এর হতে হয় না।
  • payment_url এ সব active payment method দেখায়; একটি বেছে পেমেন্ট বা বাতিল চাপলেই result test হয়।
  • Webhook (দিলে) দুই ক্ষেত্রেই যায়: status = COMPLETED / CANCELLED, সাথে "sandbox": true। শুধু public URL চলে।
  • Live এ যেতে API URL ও key দুটোই বদলান: নিজের live domain এর /api/v1 ও brand এর live API key দিন।
  • Limit: প্রতি IP তে ঘণ্টায় ৬০টি, payment ৩০ মিনিট চলে, ৭ দিন পর data মুছে যায়। আসল গ্রাহকের তথ্য দেবেন না, key সবার জন্য খোলা।

শুরুর আগে

Integration এ তিনটি কাজ: payment তৈরি, customer কে পাঠানো, আর শেষে যাচাই।

  1. Payment তৈরিআপনার server থেকে POST /create call করুন।
  2. Customer কে পাঠানResponse এর payment_url এ redirect করুন।
  3. যাচাই করুনCustomer ফিরলে POST /verify দিয়ে নিশ্চিত হোন।
https://boishakhipay.com/api/v1
X-API-KEY: YOUR_API_KEY

Authentication

প্রতিটি request এর header এ আপনার brand এর API key পাঠাতে হবে। Body হবে JSON।

headers
Content-Type: application/json
Accept: application/json
X-API-KEY: YOUR_API_KEY
মনে রাখুন: redirect_url অবশ্যই brand এ দেওয়া domain (বা তার subdomain) এর হতে হবে।

Payment তৈরি করুন

Customer এর জন্য একটি payment তৈরি করে checkout এর link নিন।

POSThttps://boishakhipay.com/api/v1/create

Request body

amountnumberআবশ্যক

BDT এ পরিমাণ। Brand এর min – max এর মধ্যে হতে হবে। Customer এর কাছে ০.০১–০.৯৯ যোগ হয়ে একটি unique amount দেখাতে পারে, যাতে SMS দেখে অটো মেলানো যায়।

redirect_urlstringআবশ্যক

Payment শেষে customer এখানে ফিরবে। Brand এর domain এর হতে হবে।

full_namestringঐচ্ছিক

Customer এর নাম।

emailstringঐচ্ছিক

Customer এর email।

cancel_urlstringঐচ্ছিক

Cancel করলে কোথায় যাবে। না দিলে redirect_url ই ব্যবহার হবে।

webhook_urlstringঐচ্ছিক

Payment complete হলে এই URL এ JSON POST যাবে।

metadataobjectঐচ্ছিক

নিজের যেকোনো data (যেমন order_id)। Verify ও webhook এ ফেরত আসবে।

উদাহরণ

<?php
$ch = curl_init("https://boishakhipay.com/api/v1/create");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        "amount"       => 500,
        "full_name"    => "Rahim Uddin",
        "email"        => "rahim@mail.com",
        "redirect_url" => "https://yourshop.com/thanks.php",
        "cancel_url"   => "https://yourshop.com/cart.php",
        "webhook_url"  => "https://yourshop.com/webhook.php",
        "metadata"     => ["order_id" => 1001]
    ]),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-KEY: YOUR_API_KEY"
    ]
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($res["payment_url"])) {
    header("Location: " . $res["payment_url"]);
    exit;
}

Response

200 OK
{
  "status": true,
  "message": "Payment Url",
  "invoice_id": "A1B2C3D4E5F60718",
  "payment_url": "https://pay.yourdomain.com/?id=A1B2C3D4E5F60718"
}

Payment যাচাই করুন

Customer ফিরে এলে বা webhook পেলে, order confirm করার আগে সবসময় server থেকে যাচাই করুন।

POSThttps://boishakhipay.com/api/v1/verify
invoice_idstringআবশ্যক

/create এর response এ পাওয়া invoice_id।

উদাহরণ

<?php
$ch = curl_init("https://boishakhipay.com/api/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(["invoice_id" => $_GET["invoice_id"] ?? ""]),
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "X-API-KEY: YOUR_API_KEY"
    ]
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($r["payment_status"] ?? "") === "COMPLETED") {
    // order paid
}

Response

200 OK
{
  "status": true,
  "invoice_id": "A1B2C3D4E5F60718",
  "payment_status": "COMPLETED",
  "amount": "500.00",
  "transaction_id": "BK12AB34CD",
  "sender": "01XXXXXXXXX",
  "full_name": "Rahim Uddin",
  "email": "rahim@mail.com",
  "metadata": { "order_id": 1001 }
}

payment_status

COMPLETEDটাকা পাওয়া গেছে
PENDINGএখনো অপেক্ষায়
EXPIREDসময় শেষ
CANCELLEDCustomer cancel করেছে

Webhook

Payment complete হলে আপনার webhook_url এ JSON POST যায়। Header এ X-API-KEY থাকে, আপনার brand এর key এর সাথে মিলিয়ে নিন।

Payload

webhook payload
{
  "invoice_id": "A1B2C3D4E5F60718",
  "status": "COMPLETED",
  "amount": "500.00",
  "transaction_id": "BK12AB34CD",
  "sender": "01XXXXXXXXX",
  "full_name": "Rahim Uddin",
  "email": "rahim@mail.com",
  "metadata": { "order_id": 1001 }
}

Handler উদাহরণ

<?php
// webhook.php
$key  = $_SERVER["HTTP_X_API_KEY"] ?? "";
$data = json_decode(file_get_contents("php://input"), true);

if (!hash_equals("YOUR_API_KEY", $key)) {
    http_response_code(401);
    exit;
}

if (($data["status"] ?? "") === "COMPLETED") {
    $orderId = $data["metadata"]["order_id"] ?? null;
    // $orderId কে paid হিসেবে mark করুন
}

http_response_code(200);
echo "ok";
Webhook না পৌঁছালেও সমস্যা নেই। Customer redirect_url এ ফিরলে /verify দিয়ে নিশ্চিত হতে পারবেন।

PHP SDK

PHP ব্যবহার করলে PayBridge.php ফাইলটি আপনার সাইটে রেখে কয়েক লাইনেই কাজ শেষ।

example.php
<?php
require "PayBridge.php";
$pb = new PayBridge("https://boishakhipay.com/api/v1", "YOUR_API_KEY");

// payment তৈরি করে customer কে পাঠান
$url = $pb->createPayment(
    500, "Rahim Uddin", "rahim@mail.com",
    "https://yourshop.com/thanks.php",
    "https://yourshop.com/webhook.php",
    ["order_id" => 1001]
);
header("Location: " . $url);

// thanks.php এ যাচাই
$r = $pb->verify($_GET["invoice_id"]);
if (($r["payment_status"] ?? "") === "COMPLETED") {
    // order paid
}

এক ফাইলের পুরো উদাহরণ

একটি ফাইলেই form, payment তৈরি আর যাচাই। Copy করে checkout.php নামে রেখে চালিয়ে দেখুন।

checkout.php
<?php
$API_URL = "https://boishakhipay.com/api/v1";
$API_KEY = "YOUR_API_KEY";
$self    = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? 'https://' : 'http://')
         . $_SERVER['HTTP_HOST'] . strtok($_SERVER['REQUEST_URI'], '?');

function pgCall($url, $data, $key) {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($data),
        CURLOPT_HTTPHEADER     => ["Content-Type: application/json", "X-API-KEY: " . $key]
    ]);
    $out = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $out ?: [];
}

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $res = pgCall($API_URL . "/create", [
        "amount"       => (float)$_POST['amount'],
        "full_name"    => $_POST['full_name'],
        "email"        => $_POST['email'],
        "redirect_url" => $self,
        "cancel_url"   => $self . "?cancel=1",
        "metadata"     => ["order_id" => time()]
    ], $API_KEY);
    if (!empty($res['payment_url'])) { header("Location: " . $res['payment_url']); exit; }
}

$verified = !empty($_GET['invoice_id'])
    ? pgCall($API_URL . "/verify", ["invoice_id" => $_GET['invoice_id']], $API_KEY)
    : null;
?>
<!DOCTYPE html><html><body style="font-family:sans-serif;max-width:440px;margin:30px auto;">
<?php if ($verified && ($verified['payment_status'] ?? '') === 'COMPLETED'): ?>
  <h2>Payment Successful!</h2>
  <p>TrxID: <?= htmlspecialchars($verified['transaction_id'] ?? '') ?></p>
  <a href="<?= htmlspecialchars($self) ?>">New Payment</a>
<?php else: ?>
  <form method="POST">
    <input name="full_name" value="Rahim" required><br><br>
    <input name="email" value="rahim@mail.com" required><br><br>
    <input name="amount" type="number" value="100" required><br><br>
    <button type="submit">Pay Now</button>
  </form>
<?php endif; ?>
</body></html>

Android Verifier App

Payment অটো যাচাই হয় আপনার ফোনে আসা bKash / Nagad / Rocket SMS দেখে। সেটআপ:

  • Dashboard → Devices থেকে device key নিন।
  • App এ আপনার account email আর device key দিয়ে login করুন।
  • SMS permission দিন। App incoming SMS server এ পাঠাবে।
  • App চালু রাখুন এবং ফোনের battery optimization বন্ধ রাখুন।

Error ও status code

কিছু ভুল হলে response এ "status": false আর একটি message আসে।

401
Invalid API key

API key ভুল, অথবা brand বন্ধ।

403
Merchant plan expired

Plan এর মেয়াদ শেষ।

403
Transaction limit reached

Plan এর transaction limit শেষ।

404
Invoice not found

Verify এ invoice_id ভুল, বা অন্য brand এর।

405
POST required

POST method ব্যবহার করুন।

422
Amount must be between …

Amount brand এর min – max এর বাইরে।

422
redirect_url must belong to brand domain …

redirect_url অন্য domain এর।

422
No payment method is configured / available …

Payment methods পেজে method যোগ করুন, অথবা amount limit দেখুন।