ডেভেলপার ডকুমেন্টেশন

সব রিকোয়েস্ট যায় এই ঠিকানায়, JSON পাঠান আর JSON পান।

https://telegramdownloadmanager.com/v1

টাকা সবসময় পয়সায় লিখতে হয়: ৫০০ টাকা মানে 50000। সময় UTC-তে, ISO 8601 ফরম্যাটে।

API key

ড্যাশবোর্ডের প্রজেক্ট ও API পাতা (বা টেলিগ্রাম বটের প্রজেক্ট) থেকে Live key বা Test key নিন। key একবারই দেখানো হয়, হারালে নতুন বানাতে হয়। নতুন বানালে আগেরটা সাথে সাথে বন্ধ হয়ে যায়।

প্রতিটা রিকোয়েস্টের হেডার
Authorization: Bearer sk_live_...
key শুধু আপনার সার্ভারে রাখুন। ওয়েবসাইটের পেজে, JavaScript-এ বা মোবাইল অ্যাপের ভেতরে কখনো না।

পেমেন্ট পেজ দিয়ে শুরু

সবচেয়ে সহজ উপায়। নম্বর দেখানো, TrxID নেওয়া, ভুল হলে কারণ বলা, সব আমাদের পেজ করে।

  1. ক্রেতা "কিনুন" চাপলে আপনার সার্ভার invoice বানায়, সাথে success_url।
  2. ক্রেতাকে উত্তরের checkout_url-এ পাঠান।
  3. পেমেন্ট সফল হলে ক্রেতা success_url-এ ফিরে আসে।
  4. অর্ডার চালু করুন webhook এলে। শুধু success_url-এ ফেরার ওপর ভরসা করবেন না, ওটা যে কেউ খুলতে পারে।

Invoice তৈরি

POST/v1/invoices
ফিল্ডধরনমানে
amountআবশ্যকintegerপয়সায়। ৫০০ টাকা = 50000
referencestring, ২০০আপনার নিজের আইডি, যেমন অর্ডার নম্বর। webhook-এ ফেরত আসে
descriptionstring, ৫০০ক্রেতা পেমেন্ট পেজে দেখে
metadataobjectযা খুশি, ৪০০০ অক্ষর পর্যন্ত। ক্রেতা দেখে না
expires_in_minutesintegerডিফল্ট ৬০, সর্বোচ্চ ১০০৮০ (৭ দিন)
success_urlstringসফল হলে ক্রেতাকে এখানে ফেরানো হয়
cancel_urlstringক্রেতা "ফিরে যান" চাপলে
currencystringএখন শুধু BDT
curl https://telegramdownloadmanager.com/v1/invoices \
  -H "Authorization: Bearer $PAYGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "reference": "order_77",
    "description": "HSC Physics কোর্স",
    "success_url": "https://shop.example/thanks"
  }'

উত্তর

200 OK
{
  "id": "inv_7Qm2rT9cK1aB3dE5fG7h",
  "object": "invoice",
  "mode": "live",
  "status": "pending",
  "amount": 50000,
  "currency": "BDT",
  "reference": "order_77",
  "description": "HSC Physics কোর্স",
  "metadata": {},
  "paid_amount": null,
  "overpaid_amount": null,
  "failure_code": null,
  "checkout_url": "https://telegramdownloadmanager.com/pay/inv_7Qm2rT9cK1aB3dE5fG7h",
  "telegram_url": "https://t.me/bikashchayanbikashbot?start=inv_7Qm2rT9cK1aB3dE5fG7h",
  "success_url": "https://shop.example/thanks",
  "cancel_url": null,
  "expires_at": "2026-10-04T13:05:00+00:00",
  "paid_at": null,
  "created_at": "2026-10-04T12:05:00+00:00",
  "payment": null
}

পেমেন্ট হয়ে গেলে payment-এ থাকে provider, trx_id, sender, amount, received_at।

Invoice দেখা

GET/v1/invoices/{id}

একই আকারের invoice ফেরত দেয়। শুধু যে প্রজেক্টের key দিয়ে বানানো হয়েছিল, সেই key দিয়েই দেখা যায়।

TrxID জমা

POST/v1/invoices/{id}/submit

নিজের পেমেন্ট ফর্ম বানালে ক্রেতার TrxID এখানে পাঠান। পেমেন্ট পেজ ব্যবহার করলে এটা লাগে না।

ফিল্ডমানে
trx_idআবশ্যকক্রেতা যেমন পেয়েছে। ছোট হাতের অক্ষর, ফাঁকা জায়গা আর ড্যাশ নিজেই ঠিক করে নেওয়া হয়
senderআবশ্যকযে নম্বর থেকে টাকা পাঠানো হয়েছে। +880 থাকলেও চলে
providerbkash, nagad বা rocket। না দিলে সব মাধ্যমে খোঁজা হয়
200 OK
{
  "result": "paid",
  "message": "পেমেন্ট সফল! ৳500 পাওয়া গেছে।",
  "invoice": { "status": "paid", ... }
}

message ক্রেতাকে হুবহু দেখানোর মতো করে লেখা, আপনার সেটিংসের ভাষায়। সব result-এর তালিকা এখানে।

Invoice বাতিল

POST/v1/invoices/{id}/cancel

শুধু pending বা verifying invoice বাতিল করা যায়। invoice.cancelled webhook যায়।

ওয়ালেট

GET/v1/wallets

আপনার যে নম্বরগুলোর পেমেন্ট অটো যাচাই হয়। নিজের ফর্মে নম্বর দেখাতে এটা ব্যবহার করুন, তাহলে নম্বর বদলালে কোড বদলাতে হয় না।

200 OK
{ "data": [ { "provider": "nagad", "msisdn": "01700000000", "kind": "personal" } ] }

Webhook

ড্যাশবোর্ডে প্রজেক্টের Webhook URL দিন। প্রতিটা ঘটনায় সেখানে একটা POST যায়। ঠিকানা https:// হতে হবে, লোকাল বা প্রাইভেট IP নেওয়া হয় না।

ঘটনাকখন
payment.succeededটাকা মিলেছে। বেশি এলে overpaid_amount-এ বাড়তি অংশ
payment.underpaidকম টাকা এসেছে, invoice বন্ধ। কত এসেছে paid_amount-এ
payment.failedদেওয়া TrxID-র পেমেন্ট নির্দিষ্ট সময়ের মধ্যে পাওয়া যায়নি। failure_code = not_found
invoice.expiredমেয়াদ শেষ, টাকা আসেনি
invoice.cancelledআপনি বাতিল করেছেন
pingড্যাশবোর্ডের "টেস্ট পাঠান" বাটন
POST → আপনার URL
PayGate-Event-Id: evt_Zp4kQ8vN2mX7cR1tY6bW
PayGate-Signature: t=1791118932,v1=5d41402abc4b2a76b9719d911017c592...
Content-Type: application/json

{
  "id": "evt_Zp4kQ8vN2mX7cR1tY6bW",
  "type": "payment.succeeded",
  "created": "2026-10-04T12:06:41+00:00",
  "data": { /* পুরো invoice, payment সহ */ }
}
  • ২০০-২৯৯ ফেরত দিলে পাঠানো সফল ধরা হয়। না দিলে আবার পাঠানো হয়: ১ মিনিট, ৫ মিনিট, ৩০ মিনিট, ২ ঘণ্টা, ১২ ঘণ্টা পর।
  • একই ঘটনা একাধিকবার আসতে পারে। id দেখে একবারই কাজ করুন।
  • অর্ডার চালু করার আগে data.status, data.amount আর data.reference নিজের ডাটাবেসের সাথে মিলিয়ে নিন।

সই যাচাই

ড্যাশবোর্ড থেকে Webhook secret (whsec_...) নিন। সই হলো HMAC-SHA256(secret, t + "." + raw_body), hex-এ। যে body এসেছে হুবহু সেটাই ব্যবহার করুন, JSON পার্স করে আবার বানাবেন না। ৫ মিনিটের বেশি পুরনো t বাতিল করুন।

$raw = file_get_contents("php://input");
parse_str(str_replace(",", "&", $_SERVER["HTTP_PAYGATE_SIGNATURE"] ?? ""), $sig);
$expected = hash_hmac("sha256", ($sig["t"] ?? "") . "." . $raw, getenv("PAYGATE_WEBHOOK_SECRET"));

if (!hash_equals($expected, $sig["v1"] ?? "") || abs(time() - (int)$sig["t"]) > 300) {
  http_response_code(401); exit;
}
$event = json_decode($raw, true);
if ($event["type"] === "payment.succeeded") {
  // $event["data"]["reference"] → অর্ডার চালু করুন (একবারই)
}
http_response_code(200);

অবস্থা ও ফলাফল

Invoice-এর status

pendingটাকার অপেক্ষায়
verifyingTrxID দেওয়া হয়েছে, যাচাই চলছে
paidসফল। আর বদলায় না
underpaidকম টাকা, বন্ধ। আর বদলায় না
expiredমেয়াদ শেষ
cancelledআপনি বাতিল করেছেন

TrxID জমার result

paidমিলেছে, সফল
already_paidএই invoice আগেই এই TrxID দিয়ে সফল হয়েছে
verifyingএখনো নিশ্চিত হয়নি। হলে webhook যাবে
underpaidকম টাকা, invoice বন্ধ
sender_mismatchটাকা এই নম্বর থেকে আসেনি। আবার চেষ্টা করা যায়
trx_already_usedTrxID অন্য পেমেন্টে ব্যবহার হয়ে গেছে
bad_trx, bad_senderলেখার ফরম্যাট ঠিক নেই
too_many_attemptsএই invoice-এ অনেকবার ভুল, লক
expired, cancelledinvoice আর খোলা নেই

এরর

সব এরর একই আকারে আসে:

4xx
{ "error": { "code": "invalid_api_key" } }
HTTPcode
401invalid_api_key: key ভুল, বাতিল, বা প্ল্যানের মেয়াদ শেষ
404invoice_not_found
400invalid_amount, invalid_ttl, invalid_return_url, invalid_provider, invoice_closed, metadata_too_large, unsupported_currency
422invalid_request: fields-এ কোন ফিল্ড ঠিক নেই
429rate_limited: প্রতি key মিনিটে ৬০০ রিকোয়েস্ট

টেস্ট মোড

sk_test_ key দিয়ে বানানো invoice শুধু টেস্ট পেমেন্ট দিয়ে মেলে, আসল টাকা দিয়ে কখনো না। উল্টোটাও সত্যি।

  1. ড্যাশবোর্ডের ফোন পাতার টেস্ট অংশ থেকে একটা টেস্ট পেমেন্ট তৈরি করুন।
  2. sk_test_ key দিয়ে invoice বানান, পেমেন্ট পেজে ওই TrxID আর নম্বর দিন।
  3. পেজে TEST চিহ্ন দেখাবে। webhook-এ data.mode হবে test। আসল অর্ডার চালু করার কোডে এটা অবশ্যই দেখবেন।