توثيق API

التدفق: أنشئ فاتورة → أرسل العميل إلى صفحة الدفع → استقبل webhook موقّعًا. البادئة /v1. المصادقة عبر ترويسة X-Api-Key.

مواصفات OpenAPI 3 (JSON) احصل على المفاتيح

الشبكات المدعومة

الانتقال من بوابة دفع أخرى — دون إعادة كتابة الكود

هل أنت متكامل بالفعل مع Cryptomus / NOWPayments / Coinbase Commerce؟ غيّر في الـ SDK ‏عنوان base-URL والمفتاح فقط — نقبل صيغة create-invoice الخاصة بهم، ونعيد صفحة الدفع لدينا بصيغة استجابتهم، ونرسل الويب هوك بمخططهم الموقّع، فيعمل كود التحقق لديك كما هو. المطابقة عبر order_id.

# قبل:  https://api.cryptomus.com/v1/payment
# بعد:  https://paygate.love/compat/cryptomus/v1/payment
# المفتاح: مفتاح API الخاص بك في paygate؛ سر الويب هوك = apiSecret الخاص بك في paygate

تحتاج بوابة أخرى؟ راسلنا وسنضيف المحوّل (إنه وحدة واحدة فقط).

قبول الدفع داخل بوت تيليجرام الخاص بك

متجرك عبارة عن بوت؟ لا تُحوّل المستخدم إلى موقع أو بوت-محفظة خارجي. يستدعي بوتك واجهتنا البرمجية، ويعرض العنوان + المبلغ + رمز QR مباشرةً في المحادثة، ويغيّر الرسالة تلقائيًا إلى «✅ مدفوع» بمجرد تأكيد الدفعة على الشبكة. نفس تجربة CryptoBot داخل البوت، لكن العملات تصلك مباشرةً، والمفاتيح مفاتيحك، والرسوم زهيدة.

1. POST /v1/invoices               # مفتاح API الخاص بك → { id, pay_address, pay_uri, amount_expected }
2. bot.sendPhoto( https://paygate.love/i/<id>/qr.png )   # رمز QR عام، تيليجرام يجلبه بنفسه
   + زر «فتح المحفظة» → pay_uri
3. ويب هوك invoice.paid لدينا → bot.editMessage → «✅ مدفوع»

لا يغادر المستخدم بوت التاجر إطلاقًا. نقطة QR ‏/i/<id>/qr.png عامة (تشفّر العنوان فقط). مثال جاهز للنسخ (grammy/telegraf) موجود في docs/BOT-INTEGRATION.md.

للستريمرز: تنبيهات التبرعات، شريط الهدف، لوحة المتصدرين

جميع نقاط النهاية الخاصة بالستريمر أدناه تستخدم رمز التنبيهات (alert token) — وهو مضمَّن بالفعل في روابط الأوفرلاي ولوحة المتصدرين في صفحة «التنبيهات» بلوحة التحكم. إنها صلاحية للقراءة فقط: لا تحل أبداً محل مفتاح API الخاص بك، لكن لا تنشر رابط الودجت علناً. من الداخل، التبرع مجرد فاتورة تحمل اسم المتبرع ورسالته.

كيف تُفعّل التبرعات في بثك — خطوة بخطوة

1. سجِّل كستريمر: في صفحة التسجيل اختر نوع الحساب «ستريمر / صانع محتوى» — فتتهيأ لوحة التحكم للتبرعات.
2. افتح لوحة التحكم → «التنبيهات»: هناك رابط الأوفرلاي (/alerts/widget?token=…) وإعدادات مظهر التنبيهات ومحرر الهدف. انسخ رابط الأوفرلاي.
3. في OBS/Streamlabs: المصادر → «+» → Browser Source → الصق الرابط، واضبط الحجم على مقاس اللوحة (مثلاً 1920×1080) → موافق. ستظهر التنبيهات وشريط الهدف الآن في البث؛ تحقق بزر التبرع التجريبي.
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 لأي شريط تقدم (سحب)

JSON عام للهدف الحالي (الرمز هو الصلاحية؛ يُخزَّن مؤقتاً نحو 5 ثوانٍ). يمكن لأي ودجت شريط تقدم خارجي استطلاعه لعرض المجموع المدمج في مكان آخر — هكذا تربط حملة paygate بشريط آخر.

curl "https://paygate.love/alerts/goal?token=<alertToken>"
→ { "active": true, "title": "New PC", "target": 1000,
    "current": 337.5, "currency": "USD" }
# لا يوجد هدف محدد → { "active": false }

تبرعات خارجية — ادمج مصادر أخرى في الشريط (دفع)

سجِّل تبرعاً حدث في مكان آخر (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 محفظتك في لوحة التحكم (غير وصائي) فتصل التبرعات مباشرة إلى محفظتك على EVM / TRON / BTC / LTC / DOGE.

برنامج الإحالة

ادعُ المتاجر والستريمرز — واحصل على حصة من عمولتنا على كل دفعة يجرونها، مدى الحياة. النسبة الافتراضية 20%، ويمكن تحديدها بشكل فردي لكل شريك.

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

رابطك الفريد موجود في لوحة التحكم → «الإحالات». كل من يسجّل عبره (يُلتقط رمز ?ref= عبر ملف cookie، أو يُدخل في الحقل الاختياري في نموذج التسجيل) يُربط بك بشكل دائم.

تُحتسب الأرباح تلقائياً على كل فاتورة مؤكدة (مدفوعة) للتاجر المُحال، بالدولار الأمريكي؛ والإحصاءات والمبالغ في لوحة التحكم → «الإحالات».

💸 محفظة المتبرّع المدفوعة مسبقًا (تبرعات فورية)

يشحن المشاهد مرة واحدة (يتأكّد الـ 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.

1. إنشاء فاتورة

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 (عملة المبلغ، الافتراضي USD)، order_id، callback_url (webhook خاص بكل فاتورة)، success_url (وجهة إعادة المشتري)، test (البيئة التجريبية). كما يتضمّن الرد الكامل status وnetwork وasset وamount_expected وrate_locked وfee_percent وtelegram_url.

بيئة الاختبار: أضف "test": true — لن تتم مراقبة الفاتورة على البلوكتشين ولن تؤثر أبدًا على رصيدك؛ يمكنك محاكاة دفعها من لوحة التحكم للتحقق من webhooks. يُوقَّع 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": "…" }

POST /v1/checkouts مع تحديد المبلغ ينشئ رابطًا يختار فيه المشتري الشبكة والعملة — مثالي بدون أي تكامل. الرد: checkout_url وshort_url وtelegram_url وexpires_at. يدعم نفس order_id وcallback_url وsuccess_url كما في الفواتير.

🤖 استقبل المدفوعات في بوت / متجر Telegram

تبيع مباشرة داخل Telegram؟ لا حاجة لموقع إلكتروني. يُنشئ البوت الخاص بك عملية دفع عبر API ويحصل على telegram_url — رابط عميق يفتح تدفق الدفع داخل بوت Telegram الخاص بنا: يختار المشتري العملة/الشبكة، ويرى العنوان ورمز QR، ويدفع. تستلم أنت Webhook موقّعًا وتسلّم البضاعة.

1. يضغط المشتري «شراء» في البوت الخاص بك ← يستدعي البوت POST /v1/checkouts (مع order_id و callback_url).
2. يرد البوت الخاص بك بزر مضمّن يحتوي على رابط telegram_url (أو short_url للدفع عبر صفحة ويب).
3. يدفع المشتري دون مغادرة Telegram ← يصلك Webhook بحدث 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_url للدفع داخل Telegram، أو short_url لصفحة دفع ويب عادية. اربط order_id بالمشتري (chat id) وبالطلب حتى يُطابق الـ Webhook بشكل لا لبس فيه. لا تسلّم البضاعة أبدًا ما دام test ليس false.

2. حالة الفاتورة

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 حتى 200، 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= — تسوية المُفوتَر مقابل المُستلَم (الحد 30 طلبًا/دقيقة).

التسوية: GET /v1/reconciliation?from=&to= — المبالغ المفوترة مقابل المستلمة (بعد خصم الرسوم) + الفروقات لكل طلب (دفع ناقص/زائد، غير مدفوع). نحن المصدر الموثوق لما وصل فعليًا؛ في الوضع غير الوصائي (non-custodial) قم بالتسوية مقابل محفظتك الخاصة. الأداة توفر البيانات — أما القرارات (الشحن، النزاعات) فهي مسؤوليتك.

3. Webhook

عند تغيّر الحالة نرسل POST إلى عنوان webhook الخاص بك. الترويسة 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

التسليم: 3 محاولات سريعة، ثم طابور دائم حتى 12 محاولة مع تباعد يصل إلى ساعة واحدة. أزِل التكرارات عبر X-Webhook-Id. يجب أن يكون عنوان الـ webhook عامًا عبر http(s) — تُرفض عناوين localhost والمضيفات الخاصة وإعادة التوجيه. لا تسلّم الطلب أبدًا ما دام test ليس false.

تعزيز الأمان

• Idempotency-Key عند إنشاء الفاتورة — إعادة المحاولات لا تُنشئ تكرارات.
• حد المعدل: 120 طلبًا/دقيقة لكل عنوان IP.
• Webhook: X-Signature (HMAC)، X-Webhook-Id (منع التكرار)، timestamp (حماية من إعادة التشغيل).