API ডকুমেন্টেশন

প্রবাহ: একটি ইনভয়েস তৈরি করুন → গ্রাহককে পেমেন্ট পেজে পাঠান → একটি স্বাক্ষরিত webhook গ্রহণ করুন। প্রিফিক্স /v1। X-Api-Key হেডারের মাধ্যমে Auth।

OpenAPI 3 স্পেক (JSON) কী পান

সমর্থিত নেটওয়ার্ক

অন্য প্রসেসর থেকে মাইগ্রেশন — কোড না লিখেই

ইতিমধ্যে Cryptomus / NOWPayments / Coinbase Commerce-এর সাথে ইন্টিগ্রেটেড? SDK-তে শুধু base-URL আর কী বদলান — আমরা তাদের create-invoice ফরম্যাট গ্রহণ করি, তাদের রেসপন্স ফরম্যাটে আমাদের পেমেন্ট পেজ ফেরত দিই এবং তাদের স্কিমে সাইনড ওয়েবহুক পাঠাই, তাই আপনার verify-কোড যেমন আছে তেমনই চলবে। ম্যাচিং হয় order_id দিয়ে।

# আগে:  https://api.cryptomus.com/v1/payment
# পরে:  https://paygate.love/compat/cryptomus/v1/payment
# কী: আপনার paygate API-কী; ওয়েবহুক সিক্রেট = আপনার paygate apiSecret

অন্য কোনো প্রসেসর দরকার? লিখুন, অ্যাডাপ্টার যোগ করে দেব (এটা মাত্র একটা মডিউল)।

আপনার নিজের Telegram-বটের ভেতরেই পেমেন্ট গ্রহণ

আপনার বটই মার্চেন্ট? ব্যবহারকারীকে সাইটে বা অন্যের ওয়ালেট-বটে পাঠাবেন না। বট আমাদের API কল করে, চ্যাটেই ঠিকানা + পরিমাণ + QR দেখায় এবং অন-চেইনে পেমেন্ট কনফার্ম হওয়া মাত্রই মেসেজটি নিজেই «✅ পরিশোধিত»-এ বদলে দেয়। CryptoBot-এর মতোই in-bot UX, কিন্তু ক্রিপ্টো সরাসরি আপনার কাছে যায়, কী আপনার, আর ফি নামমাত্র।

1. POST /v1/invoices               # আপনার API-কী → { id, pay_address, pay_uri, amount_expected }
2. bot.sendPhoto( https://paygate.love/i/<id>/qr.png )   # পাবলিক QR, Telegram নিজেই ফেচ করে
   + «ওয়ালেট খুলুন» বোতাম → pay_uri
3. আমাদের invoice.paid ওয়েবহুক → bot.editMessage → «✅ পরিশোধিত»

ব্যবহারকারী মার্চেন্টের বট ছেড়ে কোথাও যায় না। QR-এন্ডপয়েন্ট /i/<id>/qr.png পাবলিক (শুধু ঠিকানা এনকোড করে)। রেডি copy-paste উদাহরণ (grammy/telegraf) আছে — docs/BOT-INTEGRATION.md.

স্ট্রিমারদের জন্য: ডোনেশন অ্যালার্ট, গোল বার, লিডারবোর্ড

নীচের সব স্ট্রিমার এন্ডপয়েন্ট অ্যালার্ট টোকেন ব্যবহার করে — এটি ক্যাবিনেটের «অ্যালার্ট» পেজে দেখানো ওভারলে ও লিডারবোর্ড URL-এ আগে থেকেই যুক্ত। এটি কেবল-পড়ার ক্ষমতা: এটি কখনও আপনার API কী-র বিকল্প নয়, তবে উইজেট URL প্রকাশ্যে পোস্ট করবেন না। ভেতরে ভেতরে, একটি ডোনেশন হলো দাতার নাম ও বার্তাসহ একটি ইনভয়েস মাত্র।

আপনার স্ট্রিমে ডোনেশন চালু করবেন যেভাবে — ধাপে ধাপে

1. স্ট্রিমার হিসেবে নিবন্ধন করুন: সাইন-আপ পেজে «স্ট্রিমার / ক্রিয়েটর» অ্যাকাউন্ট ধরন বেছে নিন — ক্যাবিনেট ডোনেশনের উপযোগী হয়ে যাবে।
2. ক্যাবিনেট → «অ্যালার্ট» খুলুন: সেখানে ওভারলে URL (/alerts/widget?token=…), অ্যালার্টের চেহারার সেটিংস ও গোল এডিটর আছে। ওভারলে URL কপি করুন।
3. OBS/Streamlabs-এ: Sources → «+» → Browser Source → URL পেস্ট করুন, আকার আপনার ক্যানভাসের সমান দিন (যেমন 1920×1080) → OK। এখন অ্যালার্ট ও গোল বার স্ট্রিমে দেখাবে; টেস্ট-ডোনেশন বোতামে যাচাই করুন।
4. একই «অ্যালার্ট» পেজে ফান্ডরেইজিং গোল সেট করুন — শিরোনাম, লক্ষ্য পরিমাণ ও মুদ্রা। প্রগ্রেস বার ওভারলেতে এবং GET /alerts/goal-এর মাধ্যমে দেখা যাবে।
5. ডোনেশন লিংক তৈরি করুন (ক্যাবিনেট → «লিংক»), লিংক/QR দর্শকদের সাথে শেয়ার করুন, আর পাবলিক লিডারবোর্ড /d/<token> আপনার চ্যানেলে পোস্ট করুন।
6. অ্যাডভান্সড: অন্য প্ল্যাটফর্মের ডোনেশন POST /v1/donations/external দিয়ে পাঠান, বা তৃতীয় পক্ষের প্রগ্রেস বারকে GET /alerts/goal থেকে ডেটা দিন — বিস্তারিত নিচে।

OBS ওভারলে (Browser Source)

লাইভ ডোনেশন অ্যালার্ট ও গোল বারসহ একটি রেডি HTML পেজ — এটিকে OBS/Streamlabs-এ Browser Source হিসেবে যোগ করুন:

https://paygate.love/alerts/widget?token=<alertToken>

ফান্ডরেইজিং গোল — যেকোনো প্রগ্রেস বারের জন্য JSON (pull)

বর্তমান গোলের পাবলিক JSON (টোকেনই অ্যাক্সেস; ~৫ সেকেন্ড ক্যাশ)। যেকোনো বাইরের প্রগ্রেস-বার উইজেট এটি পোল করে সম্মিলিত মোট অন্য কোথাও দেখাতে পারে — এভাবেই paygate-এর ফান্ডরেইজার অন্য বারের সাথে যুক্ত হয়।

curl "https://paygate.love/alerts/goal?token=<alertToken>"
→ { "active": true, "title": "New PC", "target": 1000,
    "current": 337.5, "currency": "USD" }
# কোনো গোল সেট নেই → { "active": false }

বাহ্যিক ডোনেশন — অন্যান্য উৎস একই বারে মেশান (push)

অন্য কোথাও ঘটা ডোনেশন (PayPal, DonationAlerts, ম্যানুয়াল) রেকর্ড করুন যাতে সেটি একই গোল বারে গণনা হয় এবং চাইলে একই OBS অ্যালার্টও চালায়। এক বার — সব উৎস: ক্রিপ্টো আর যা-ই আপনি এখানে পাঠান। প্রমাণীকরণ: আপনার API কী।

curl -X POST https://paygate.love/v1/donations/external \
  -H "X-Api-Key: pk_..." -H "Content-Type: application/json" \
  -d '{ "amount": 5, "currency": "USD", "name": "Alice",
        "message": "gg!", "source": "paypal", "fire_alert": true }'
→ 201 { "ok": true, "amount_usd": 5 }

ফিল্ড: amount (>0, আবশ্যক), currency (ডিফল্ট USD), name (≤60), message (≤300), source (≤40, ডিফল্ট "api"), fire_alert (ডিফল্ট true)। গোলের মোটে পরিমাণটি USD-তে রূপান্তরিত হয়।

লাইভ অ্যালার্ট স্ট্রিম (SSE)

প্রতিটি ডোনেশনের সাথে Server-Sent Events — আমাদের উইজেটের বদলে সম্পূর্ণ নিজস্ব ওভারলে বানান:

const es = new EventSource(
  "https://paygate.love/alerts/stream?token=<alertToken>");
es.onmessage = (e) => {
  const d = JSON.parse(e.data); // { name, amount, currency, asset, message }
  showAlert(d);
};

পাবলিক লিডারবোর্ড

শেয়ারযোগ্য পাবলিক টপ-ডোনার পেজ (শীর্ষ সমর্থক, সাম্প্রতিক ডোনেশন, গোল) — এটি চ্যানেলের বিবরণে বা চ্যাটে পোস্ট করুন:

https://paygate.love/d/<alertToken>

পেআউট: ডিফল্টভাবে ডোনেশন কাস্টোডিয়াল — যখন খুশি ক্যাবিনেট থেকে তুলুন। অথবা ক্যাবিনেটে আপনার ওয়ালেটের xpub যোগ করুন (non-custodial) — ডোনেশন সরাসরি আপনার ওয়ালেটে EVM / TRON / BTC / LTC / DOGE-এ পৌঁছাবে।

রেফারেল প্রোগ্রাম

শপ ও স্ট্রিমারদের আমন্ত্রণ জানান — আর তাদের প্রতিটি পেমেন্ট থেকে আমাদের কমিশনের একটি অংশ পান, আজীবন। ডিফল্ট রেট 20%, এবং প্রতিটি পার্টনারের জন্য আলাদাভাবে নির্ধারণ করা যায়।

https://paygate.love/?ref=<yourCode>

আপনার ইউনিক লিংক আছে ক্যাবিনেট → «রেফারেল»-এ। এই লিংক দিয়ে যিনিই নিবন্ধন করবেন (?ref= কোডটি cookie-র মাধ্যমে ধরা পড়ে, অথবা সাইন-আপ ফর্মের ঐচ্ছিক ঘরে লেখা যায়), তিনি স্থায়ীভাবে আপনার সাথে যুক্ত হবেন।

রেফার করা মার্চেন্টের প্রতিটি নিশ্চিত (পরিশোধিত) ইনভয়েসে স্বয়ংক্রিয়ভাবে USD-এ আয় জমা হয়; পরিসংখ্যান ও পরিমাণ দেখুন ক্যাবিনেট → «রেফারেল»-এ।

💸 ডোনার প্রিপেইড ওয়ালেট (তাৎক্ষণিক ডোনেশন)

একজন দর্শক একবার টপ-আপ করেন (crypto একবারই নিশ্চিত হয়), তারপর অভ্যন্তরীণ ব্যালেন্স থেকে যেকোনো Paygate স্ট্রিমারকে তাৎক্ষণিক ডোনেশন পাঠান — অ্যালার্ট সঙ্গে সঙ্গে দেখা যায়, প্রতিটি ডোনেশনে নেটওয়ার্কের অপেক্ষা নেই। ডোনেশন আপনার সাধারণ ব্যালেন্সে আসে; বরাবরের মতো তুলে নিন। ওয়ালেট পেজ: /w (বিয়ারার লিঙ্ক, টোকেন #fragment-এ থাকে — কখনো লগে যায় না)।

🧩 Plugin setup guides

Before you start, grab your API key and secret from your store's Settings page. ⚙️

🛒 WooCommerce — setup

1. Download the plugin zip (the “Download” button on the Plugins page or in your dashboard).
2. WP Admin → Plugins → Add New → Upload Plugin → choose the zip → Install → Activate.
3. WooCommerce → Settings → Payments → enable “Paygate (crypto)” and click Manage.
4. Paste your API key and secret, save. The webhook is wired automatically.
5. Place a test order: pick “Paygate” at checkout, pay, and the order flips to Paid on the signed webhook.

🖥️ WHMCS — setup

1. Download and unzip. Inside you'll find a modules/gateways/ folder.
2. Upload the contents of modules/gateways/ into your WHMCS root (it merges with the existing structure).
3. WHMCS Admin → Setup → Payments → Payment Gateways → “All Payment Gateways” tab → activate “Paygate”.
4. Enter your API key and secret, save. Verify with a test invoice — status updates via the callback.

🛍️ OpenCart — setup

1. Download the zip. Copy the contents of upload/ into your OpenCart root (merges with admin/ and catalog/), or install the zip via Extensions → Installer.
2. Extensions → Extensions → Payments → find “Paygate — Crypto Payments” → “+” (Install) → pencil (Edit).
3. Status = Enabled, paste your API key and secret, pick the order statuses, save. The webhook is wired automatically (callback_url).
4. Test order: pick “Pay with Crypto” at checkout, pay, and the status updates via the signed webhook.

🧿 PrestaShop — setup

1. Download the module zip. Back office → Modules → Module Manager → “Upload a module” → choose the zip → install.
2. Click “Configure”, paste your API key and secret (leave base URL as https://paygate.love), save.
3. The webhook is wired automatically (callback_url) and shown on the settings page.
4. Test order: pick “Pay with Crypto”, pay, and the order moves to “Payment accepted” on the signed webhook.

🅜 Magento 2 — setup

1. Copy the Paygate folder into app/code/ (module lives at app/code/Paygate/Crypto).
2. From the Magento root: bin/magento module:enable Paygate_Crypto && bin/magento setup:upgrade && setup:di:compile && cache:flush.
3. Admin → Stores → Configuration → Sales → Payment Methods → “Paygate — Crypto Payments”: Enabled = Yes, paste your API key and secret, save.
4. Webhook: https://your-store/paygate/webhook (sent automatically as callback_url). Verify with a test order.

🛒 CS-Cart — setup

1. Download the zip. Administration → Add-ons → Manage add-ons → “+” (Upload & install) → choose the zip.
2. Administration → Payment methods → Add: Processor = “Paygate (crypto)”.
3. On the Configure tab paste your API key and secret (leave base URL as https://paygate.love), save and activate.
4. The webhook is wired automatically (callback_url). Verify with a test order — the status updates via the signed webhook.

🅱️ Blesta — setup

1. Download the zip. Copy components/gateways/nonmerchant/paygate/ into your Blesta install at the same path.
2. Settings → Company → Payment Gateways → Available → install “Paygate — Crypto Payments”.
3. Click “Manage”, enter your API key and secret (leave base URL as https://paygate.love), save.
4. The callback URL is Blesta's standard gateway callback, sent automatically. Verify with a test invoice.

🧾 FOSSBilling — setup

1. Download the zip and extract library/Payment/Adapter/Paygate.php into your FOSSBilling root (paths merge).
2. Admin → System → Payment gateways → New payment gateway → activate “Paygate”.
3. Paste your API key and secret (leave base URL as https://paygate.love), save.
4. The webhook (IPN) is wired automatically as callback_url. Verify with a test invoice — payment applies via the signed webhook.

💬 XenForo — setup

1. Download the zip and copy the contents of upload/ into your forum root (creates src/addons/Paygate/Crypto).
2. Admin → Add-ons → install “Paygate — Crypto Payments”.
3. Admin → Setup → Payment profiles → Add payment profile → Paygate: paste your API key and secret, save.
4. Attach the profile to your User upgrades. Payment confirms via the signed webhook through payment_callback.php.

📦 BoxBilling — setup

1. Download the zip and extract bb-library/Payment/Adapter/Paygate.php into your BoxBilling root.
2. Admin → Configuration → Payment gateways → New payment gateway → activate “Paygate”.
3. Paste your API key and secret (base URL https://paygate.love), save. The webhook (IPN) wires automatically.
4. Verify with a test invoice — payment applies via the signed webhook.

🎮 Paymenter — setup

1. Download the zip and extract extensions/Gateways/Paygate into your Paymenter root.
2. Admin → Extensions → Gateways → enable “Paygate”.
3. Paste your API key and secret (base URL https://paygate.love), save.
4. Webhook: /extensions/gateways/paygate/webhook (sent automatically as callback_url). Verify with a test invoice.

👥 Invision Community — setup

1. Download the zip and install the paygate application (AdminCP → System → Applications; see README for dev-mode / tar build).
2. AdminCP → Commerce → Payments → Payment Methods → Create New → Paygate.
3. Paste your API key and secret (base URL https://paygate.love), save.
4. Payment confirms via the signed webhook; underpaid goes to Held for manual review.

📋 vBulletin — setup (vB4 / vB5)

1. Pick your archive: vB4 (4.2.x) → includes/paymentapi/class_paygate.php; vB5 → core/includes/paymentapi/class_paygate.php.
2. Copy the class file to the right path and run install.sql from the archive (registers the method in the paymentapi table).
3. AdminCP → Paid Subscriptions → Payment API Manager → Paygate: enable, paste your API key and secret (base URL https://paygate.love).
4. The subscription activates via the signed webhook (payment_gateway.php); duplicates bounce on the transaction id.

🎮 Azuriom — setup

1. Download the zip and add PaygateMethod to the Shop plugin (see README: patch PaymentManager or register via registerPaymentMethod).
2. Admin → Shop → Settings → Payment gateways → Paygate: paste your API key and secret (base URL https://paygate.love).
3. Payment confirms via the signed webhook (shop.payments.notification); completed payments are idempotent.

🏬 Webasyst / Shop-Script — setup

1. Download the zip and extract wa-plugins/payment/paygate into your Webasyst root.
2. Store → Settings → Payment → add method → Paygate: paste your API key and secret (base URL https://paygate.love).
3. Payment confirms via the signed webhook (waPayment relay URL); dedup via native_id.

🛒 X-Cart — setup

1. Download the zip and extract classes/ and skins/ into your X-Cart root, then rebuild the cache (Re-deploy).
2. Admin → Store setup → Payment methods → enable “Paygate”.
3. Paste your API key and secret (base URL https://paygate.love), save. Payment confirms via the signed webhook.

🛍️ Zen Cart — setup

1. Download the zip: module file to includes/modules/payment/, language to includes/languages/english/modules/payment/, and ipn_paygate.php to the store root.
2. Admin → Modules → Payment → Paygate → Install; paste your API key and secret (base URL https://paygate.love).
3. The order is created as pending; status updates via the signed webhook (ipn_paygate.php).

🏪 osCommerce — setup

1. Download the zip (targets osCommerce 2.3.x): module file to includes/modules/payment/, callback.php to ext/modules/payment/paygate/, language to includes/languages/english/….
2. Admin → Modules → Payment → Paygate → Install; paste your API key and secret (base URL https://paygate.love).
3. Order status updates via the signed webhook (ext/…/callback.php); the webhook retries until the order is found.

🛒 VirtueMart (Joomla) — setup

1. Joomla → Extensions → Install: upload the zip (or copy to plugins/vmpayment/paygate/ and click Discover).
2. Enable the “VM Payment - Paygate” plugin, then VirtueMart → Payment Methods → create a method using it.
3. Paste your API key and secret (base URL https://paygate.love), save. Payment confirms via the signed webhook.

💧 Drupal Commerce — setup

1. Extract the module to modules/custom/paygate (or via composer), enable it on Extend.
2. Commerce → Configuration → Payment gateways → Add: choose Paygate (off-site redirect).
3. Paste your API key and secret (base URL https://paygate.love), save. The notify webhook is the source of truth.

⬇️ Easy Digital Downloads — setup

1. WP Admin → Plugins → Add New → Upload → choose the zip → Install → Activate.
2. Downloads → Settings → Payment Gateways → enable “Paygate” and open its settings.
3. Paste your API key and secret (base URL https://paygate.love), save. Payment confirms via the signed webhook (edd-listener).

🧾 HostBill — setup (free bridge)

1. This is a lightweight bridge, not the paid SDK module: unzip it into a web-accessible folder, e.g. https://your-billing/paygate/.
2. HostBill → Settings → API: create an API user, whitelist this server's IP. Copy config.sample.php → config.php and fill in the HostBill + Paygate keys and a random link_secret.
3. In your Paygate store settings set the webhook/callback → https://your-billing/paygate/callback.php. A payment closes the invoice automatically via the Admin API (addInvoicePayment).
4. Add the “Pay with Crypto” button to invoices via the hooks/paygate_button.php hook (into includes/hooks/) or a ready signed link pay.php?invoice_id=…&token=… — see the README.

🖥️ WISECP — setup

1. Copy the coremio/ folder from the zip over your WISECP root (the module lands in coremio/modules/Payment/Paygate/).
2. Admin → Settings → Payment Gateways → enable “Paygate — Crypto Payments” and paste your API key and secret (base URL https://paygate.love).
3. No webhook setup needed: the module passes its callback link with every checkout. Payment confirms via the signed webhook.

🧾 ClientExec — setup

1. Unzip the archive into plugins/gateways/paygate/ of your ClientExec install.
2. Settings → Plugins → Payment Processors → activate Paygate and paste your API key and secret (base URL https://paygate.love).
3. Webhook: https://your-domain/plugins/gateways/paygate/callback.php — set it in your Paygate store settings.

🎨 Tilda — setup (universal payment system)

1. This is a self-hosted bridge: unzip it onto your PHP hosting (e.g. https://your-domain/paygate/) and fill in config.php from the sample.
2. In Tilda: Site Settings → Payment Systems → Universal payment system → API URL = https://your-domain/paygate/receive.php; field mapping and signature per the README.
3. Paygate webhook: https://your-domain/paygate/callback.php. On payment the bridge sends Tilda a signed notification — the order flips to paid.

🛒 BigCommerce — setup (bridge)

1. BigCommerce's native payment list is partner-gated, so this is a bridge: unzip onto your PHP hosting and fill in config.php.
2. In BigCommerce create a store-level API account (Orders scope), enable the offline method “Cryptocurrency (Paygate)” and add the pay button per the README (Script Manager).
3. Paygate webhook: https://your-domain/paygate/callback.php — on payment the order moves to Awaiting Fulfillment automatically.

🛍️ Zid — setup (private bridge)

1. Zid's App Store won't list crypto (SAMA), so the bridge runs privately with your own partner credentials. Deploy the Node service from the zip (npm i && npm run build).
2. Fill in .env (Zid tokens, Paygate keys) and register the order-created webhook per the README.
3. The buyer pays via the /pay/:orderId link; on confirmation the bridge marks the order paid through the Zid API.

১. একটি ইনভয়েস তৈরি করুন

POST /v1/invoices
X-Api-Key: pk_...
Idempotency-Key: order-1042        # ঐচ্ছিক, ডুপ্লিকেট প্রতিরোধ করে
Content-Type: application/json

{ "network": "ton", "asset": "USDT", "amount": "25.00", "order_id": "1042" }

রেসপন্সে id, pay_address, pay_uri, expires_at থাকে। ক্রেতাকে /pay/-এ পাঠান।

অনুরোধের ঐচ্ছিক ফিল্ড: quote_currency (amount-এর মুদ্রা, ডিফল্ট USD), order_id, callback_url (এই ইনভয়েসের জন্য আলাদা webhook), success_url (ক্রেতাকে যেখানে ফেরত পাঠানো হবে), test (স্যান্ডবক্স)। সম্পূর্ণ রেসপন্সে আরও থাকে status, network, asset, amount_expected, rate_locked, fee_percent, telegram_url।

স্যান্ডবক্স: "test": true যোগ করুন — ইনভয়েসটি ব্লকচেইনে ট্র্যাক হয় না এবং আপনার ব্যালেন্সে কখনও প্রভাব ফেলে না; webhook যাচাই করতে ড্যাশবোর্ডে এর পেমেন্ট সিমুলেট করুন। এর webhook একইভাবে স্বাক্ষরিত, তবে এতে থাকে "test": true — শুধুমাত্র test === false হলেই অর্ডার সরবরাহ করুন।

1b. Live rate — price a USD amount in BTC/LTC

GET /v1/quote?asset=BTC&quote_currency=USD
X-Api-Key: pk_...
→ { "asset": "BTC", "quote_currency": "USD", "rate": "63022.25" }

# price a $12.99 item in BTC:
#   amount = 12.99 / 63022.25 = 0.00020612  → send as "amount" to /v1/invoices
# optional: pass &amount=12.99 to get "quote_amount" back too

The amount is denominated in quote_currency (default USD) — the gateway converts it to the coin at the live rate, no manual math needed. For USDT/USDC quoted in USD that's 1:1. To price directly in the coin, set quote_currency to the coin symbol (e.g. quote_currency=BTC) — then no conversion happens. The rate comes from CoinGecko/Coinbase, refreshes every ~45s and is locked into the invoice (rate_locked), so the buyer always pays the correct up-to-the-minute amount. The response returns quote_amount (as you sent it) and amount_expected (the final coin amount).

Don't want to do the math? Use POST /v1/checkouts with a USD amount — the buyer picks the coin and we handle the live conversion.

পেমেন্ট লিংক (ক্রেতা নিজেই কয়েন বেছে নেয়)

POST /v1/checkouts
X-Api-Key: pk_...
Content-Type: application/json

{ "amount": "25.00", "quote_currency": "USD", "order_id": "1042" }
→ { "checkout_url": "https://…/checkout/…", "short_url": "https://…/c/…",
    "telegram_url": "https://t.me/…", "expires_at": "…" }

amount সহ POST /v1/checkouts এমন একটি লিংক তৈরি করে যেখানে নেটওয়ার্ক ও কয়েন ক্রেতা নিজেই বেছে নেয় — কোনো ইন্টিগ্রেশন ছাড়াই ব্যবহারের জন্য আদর্শ। রেসপন্স: checkout_url, short_url, telegram_url, expires_at। ইনভয়েসের মতোই একই order_id, callback_url ও success_url সাপোর্ট করে।

🤖 Telegram বট / শপে পেমেন্ট গ্রহণ করুন

সরাসরি Telegram-এর ভেতরেই বিক্রি করছেন? কোনো ওয়েবসাইটের দরকার নেই। আপনার বট API-এর মাধ্যমে একটি চেকআউট তৈরি করে এবং একটি telegram_url পায় — এটি একটি ডিপ লিংক, যা আমাদের Telegram বটের ভেতরেই পেমেন্ট ফ্লো খুলে দেয়: ক্রেতা কয়েন/নেটওয়ার্ক বেছে নেয়, ঠিকানা ও QR দেখে, এবং পেমেন্ট করে। আপনি একটি স্বাক্ষরিত ওয়েবহুক পান এবং পণ্য ডেলিভারি করেন।

1. ক্রেতা আপনার বটে «কিনুন» চাপে → আপনার বট POST /v1/checkouts কল করে (order_id ও callback_url সহ)।
2. আপনার বট telegram_url লিংকযুক্ত একটি ইনলাইন বাটন দিয়ে উত্তর দেয় (অথবা ওয়েব পেজে পেমেন্টের জন্য short_url)।
3. ক্রেতা Telegram থেকে না বেরিয়েই পেমেন্ট করে → আপনি invoice.paid ওয়েবহুক পান → আপনার বট পণ্য/অ্যাক্সেস দিয়ে দেয়।

// Telegram bot (grammY/Telegraf) — sell for crypto
bot.callbackQuery("buy", async (ctx) => {
  const r = await fetch("https://paygate.love/v1/checkouts", {
    method: "POST",
    headers: { "X-Api-Key": PK, "Content-Type": "application/json" },
    body: JSON.stringify({ amount: "9.99", quote_currency: "USD",
      order_id: ctx.from.id + ":" + Date.now(),
      callback_url: "https://my-bot.example/paygate-webhook" }),
  }).then((x) => x.json());
  // r.telegram_url opens the pay flow INSIDE Telegram (coin choice + address + QR)
  await ctx.reply("Оплатить криптой:", {
    reply_markup: { inline_keyboard: [[{ text: "💳 Pay", url: r.telegram_url }]] },
  });
});

// Deliver the goods on the signed webhook (see "Webhooks" below)
app.post("/paygate-webhook", (req, res) => {
  if (verifySignature(req) && req.body.event === "invoice.paid" && !req.body.test)
    deliverOrder(req.body.order_id);   // ship / grant access
  res.sendStatus(200);
});

টিপস: Telegram-এর ভেতরে পেমেন্টের জন্য telegram_url ব্যবহার করুন, আর সাধারণ ওয়েব চেকআউট পেজ চাইলে short_url। order_id-কে ক্রেতা (chat id) ও অর্ডারের সাথে যুক্ত করুন, যাতে ওয়েবহুক নিঃসন্দেহে ম্যাচ করে। test যতক্ষণ false না হয়, ততক্ষণ কখনোই পণ্য ডেলিভারি করবেন না।

২. ইনভয়েস স্ট্যাটাস

GET /v1/invoices/<id>
X-Api-Key: pk_...
→ { "status": "paid", "amount_received": "25",
    "settlement": { "gross": "25", "fee": "…", "spread": "…", "net": "…", "revenue": "…" } }

স্ট্যাটাস: pending → detected → paid (এছাড়াও underpaid, overpaid, expired, cancelled, settled)।

আরও এন্ডপয়েন্ট

GET /v1/invoices — পেজিনেশনসহ ইনভয়েসের তালিকা (limit সর্বোচ্চ ২০০, offset, status ফিল্টার)।
POST /v1/invoices/<id>/cancel — pending/detected ইনভয়েস বাতিল করুন (invoice.cancelled ইভেন্ট পাঠায়)।
GET /v1/quote?asset=&quote_currency=&amount= — রেট ও রূপান্তরিত অঙ্কের প্রিভিউ।
GET /v1/networks — নেটওয়ার্ক ও কয়েনের তালিকা (কোনো কী লাগে না)।
GET /v1/reconciliation?from=&to= — ইস্যুকৃত-বনাম-প্রাপ্ত রিকনসিলিয়েশন (সীমা ৩০ অনুরোধ/মিনিট)।

রিকনসিলিয়েশন: GET /v1/reconciliation?from=&to= — ইনভয়েসকৃত বনাম প্রাপ্ত অর্থ (ফি বাদে) + অর্ডারভিত্তিক গরমিল (কম/বেশি পরিশোধিত, অপরিশোধিত)। কী এসেছে সে বিষয়ে আমরাই সত্যের উৎস; নন-কাস্টোডিয়ালের ক্ষেত্রে নিজের ওয়ালেটের সাথে মিলিয়ে নিন। টুলটি ডেটা দেয় — সিদ্ধান্ত (শিপিং, বিরোধ) আপনার দায়িত্বে।

৩. Webhook

স্ট্যাটাস পরিবর্তনে আমরা আপনার webhook URL-এ POST করি। হেডার X-Signature = HMAC-SHA256(body, api_secret)। প্রক্রিয়াকরণের আগে স্বাক্ষর ও সতেজতা (timestamp) যাচাই করুন।

Webhook পেলোড

{
  "event": "invoice.paid",
  "invoice_id": "inv_…", "order_id": "1042",
  "status": "paid", "test": false,
  "asset": "USDT", "network": "ton",
  "quote_currency": "USD",
  "amount_expected": "25", "amount_received": "25",
  "tx_hash": "…", "timestamp": "2026-07-12T20:00:00.000Z",
  "invoice": { "id": "inv_…", "order_id": "1042", "status": "paid",
               "quote_currency": "USD",
               "amount_expected": "25", "amount_received": "25" }
}

ইভেন্ট: invoice.detected, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.cancelled। হেডার: X-Signature, X-Webhook-Id, X-Event।

// Node — verify signature (constant-time), dedupe, gate on test
import crypto from "node:crypto";
const expected = crypto.createHmac("sha256", API_SECRET).update(rawBody).digest("hex");
const sig = String(req.headers["x-signature"] ?? "");
if (sig.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
  return res.sendStatus(401);
const evt = JSON.parse(rawBody);
if (Date.now() - new Date(evt.timestamp) > 5*60_000) return res.sendStatus(400); // anti-replay
if (seen(req.headers["x-webhook-id"])) return res.sendStatus(200);               // idempotency
if (evt.event === "invoice.paid" && evt.test === false) fulfil(evt.order_id);   // only real payments

ডেলিভারি: ৩টি দ্রুত চেষ্টা, তারপর টেকসই কিউতে সর্বোচ্চ ১২টি চেষ্টা, backoff সর্বোচ্চ ১ ঘণ্টা পর্যন্ত। X-Webhook-Id দিয়ে ডুপ্লিকেট বাদ দিন। Webhook URL অবশ্যই পাবলিক http(s) হতে হবে — localhost/প্রাইভেট হোস্ট ও রিডাইরেক্ট প্রত্যাখ্যাত হয়। test যতক্ষণ false না হয়, ততক্ষণ কখনোই অর্ডার সম্পন্ন করবেন না।

হার্ডেনিং

• ইনভয়েস তৈরিতে Idempotency-Key — রিট্রাই ডুপ্লিকেট তৈরি করে না।
• রেট লিমিট: প্রতি IP ঠিকানায় ১২০ রিকোয়েস্ট/মিনিট।
• Webhook: X-Signature (HMAC), X-Webhook-Id (idempotency), timestamp (অ্যান্টি-রিপ্লে)।