مستنداتِ API

اتصال به درگاه — سه اندپوینت، همین‌قدر ساده.

اگر ربات یا سایتِ فروش دارید، با همین سه درخواست، پرداخت‌ها از این درگاه انجام می‌شود و پول در حسابِ خودتان ثبت می‌شود. نیازی به تغییرِ منطقِ پرداخت نیست؛ فقط آدرسِ سرویس و کلید را عوض کنید.

شروعِ سریع نمونه‌ی کُد

شروعِ سریع

سه قدم تا اولین پرداختِ تاییدشده.

۱
کلید بگیریداز داخلِ ربات، دکمه‌ی «🔗 اتصال درگاه (API)» — هر فروشنده یک کلیدِ یکتا دارد.
۲
آدرس را عوض کنیدآدرسِ پایه را در بخشِ پیکربندیِ پرداختِ رباتِ خود بگذارید؛ بقیه‌ی تنظیمات دست‌نخورده می‌ماند.
۳
فاکتور بسازید و تایید بزنید ساخت → استعلام → تایید؛ همان سه درخواستی که احتمالاً از قبل دارید.

آدرس و کلید

آدرسِ پایه	`https://pay.polgram.nls2026h.xyz`
احراز هویت	هدرِ `Authorization: Bearer ***` روی هر سه درخواست
دریافتِ کلید	از داخلِ همین ربات — دکمه‌ی «🔗 اتصال درگاه (API)»
حدِ مبلغ	10,000 تا 1,000,000 تومان برای هر فاکتور
فرمتِ درخواست	`JSON` با `Content-Type: application/json`
تستِ سلامت	بدونِ احراز: `https://pay.polgram.nls2026h.xyz/healthz`

POST ۱) ساختِ فاکتور

https://pay.polgram.nls2026h.xyz/pay/create-order.php

یک فاکتورِ پرداخت می‌سازد و شماره‌ی کارت، مبلغِ قابلِ واریز، مهلت و آدرسِ صفحه‌ی پرداخت را برمی‌گرداند.

{
  "order_id": "MY-1042",
  "price_amount": 125000
}

پاسخ:

{
  "success": true,
  "order_id": "MY-1042",
  "authority": "...",
  "pay_page_url": "https://pay.polgram.nls2026h.xyz/paypage/...",
  "pay_amount_toman": 125081,
  "expires_in_minutes": 30,
  "show_card_in_bot": true,
  "card": {"number": "...", "holder": "...", "bank": ""},
  "status": "pending"
}

ساختِ فاکتور چیزی از موجودیِ شما کم نمی‌کند و به موجودی هم اضافه نمی‌کند؛ فقط فاکتور ثبت می‌شود. مبلغِ قابلِ واریز (pay_amount_toman) با مبلغِ درخواستیِ کمی فرق دارد — همان را به خریدار بدهید.

GET ۲) استعلامِ وضعیت

https://pay.polgram.nls2026h.xyz/pay/check-order-status.php?order_id=MY-1042

وضعیتِ فاکتور را می‌گیرد. اگر پرداخت هنوز نیامده، خودِ درگاه یک استعلامِ محرک هم به ارائه‌دهنده می‌زند؛ پس لازم نیست شما چیزی را دستی «پرداخت‌شده» کنید.

status یکی از pending / paid / expired است و status_code برابر 0 / 100 / 101. وقتی پرداخت شد، paid_at و amount هم می‌آید. پاسخِ شکسته هم به‌صورتِ JSON می‌آید؛ پس خطا باید همیشه از بدنه‌ی پاسخ خوانده شود، نه فقط از کدِ HTTP.

POST ۳) تاییدِ نهایی

https://pay.polgram.nls2026h.xyz/smspay/api/verify-payment.php

{
  "authority": "..."
}

پاسخِ موفق: status: "verified" و status_code: 100. تکرارِ همان درخواست بی‌خطر است و چیزی را دوباره حساب نمی‌کند؛ اگر هنوز واریزی نیامده status_code: 0 و اگر مهلت تمام شده status_code: 101.

پول فقط بعد از این تایید، به موجودیِ فروشنده اضافه می‌شود؛ پس تا پرداخت واقعاً واریز نشده تایید نزنید.

نمونه‌ی کُد

کپی کنید، آدرس و کلید را عوض کنید.

curl -X POST https://pay.polgram.nls2026h.xyz/pay/create-order.php   -H "Authorization: Bearer ***"   -H "Content-Type: application/json"   -d '{"order_id":"MY-1042","price_amount":125000}'

import requests

BASE = "https://pay.polgram.nls2026h.xyz"
KEY = "YOUR_KEY"
H = {"Authorization": "Bearer " + KEY}

r = requests.post(BASE + "/pay/create-order.php", json={
    "order_id": "MY-1042", "price_amount": 125000}, headers=H, timeout=30)
inv = r.json()
print(inv["pay_amount_toman"], inv["card"]["number"])

st = requests.get(BASE + "/pay/check-order-status.php",
                  params={"order_id": "MY-1042"},
                  headers=H, timeout=30).json()
if st.get("paid"):
    ok = requests.post(BASE + "/smspay/api/verify-payment.php",
                       json={"authority": inv["authority"]},
                       headers=H, timeout=30).json()
    print(ok["status"])

$base = "https://pay.polgram.nls2026h.xyz";
$hdr = ["Authorization: Bearer ***",
        "Content-Type: application/json"];

$ch = curl_init($base . "/pay/create-order.php");
curl_setopt_array($ch, [CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => $hdr,
    CURLOPT_POSTFIELDS => json_encode(["order_id" => "MY-1042",
                                      "price_amount" => 125000])]);
$inv = json_decode(curl_exec($ch), true);
curl_close($ch);

ربات‌های آماده

۱
توکندر پنلِ رباتِ خود، به‌جایِ توکنِ درگاهِ قبلی، همین کلیدتان را بگذارید.
۲
آدرسسه خطِ اندپوینت در فایلِ پرداخت یا پیکربندیِ پرداخت را با https://pay.polgram.nls2026h.xyz عوض کنید؛ معمولاً همین‌قدر کافی است.
۳
بقیه‌ی کاراعلامِ پرداخت به خریدار، موجودی و برداشت دست‌نخورده می‌ماند.

کدهای وضعیت

وضعیت	status_code	معنی
`pending`	`0`	فاکتور ساخته شده؛ هنوز واریزی ثبت نشده است.
`paid`	`100`	پرداخت تایید و به موجودیِ فروشنده نوشته شد.
`expired`	`101`	مهلتِ فاکتور تمام شده؛ فاکتورِ تازه بسازید.

کدِ HTTP	چه وقت
`200`	درخواست پردازش شد؛ نتیجه در بدنه با `success` است.
`401`	کلید نیست، نادرست یا باطل شده است.
`404`	مسیر پیدا نشد یا سفارشی با این شناسه نیست.
`413`	بدنه‌ی درخواست بزرگ‌تر از سقف است.
`429`	سقفِ نرخ؛ سربرگِ `Retry-After` را بخوانید و بعد دوباره تلاش کنید.
`500`	خطای داخلی — پیامِ فارسی در بدنه است؛ چند ثانیه بعد دوباره امتحان کنید.

محدودیتِ نرخ

هر نوع سطلِ جداگانه دارد؛ مثلاً سقفِ ساختِ فاکتور، سهمیه‌ی استعلام را نمی‌سوزاند.

نوع	سقف	پنجره
ساختِ فاکتور	۲۰ درخواست	۶۰ ثانیه
استعلام و تایید	۱۲۰ درخواست	۶۰ ثانیه
صفحاتِ عمومی (مستندات، فاکتور، سلامت‌سنجی)	۳۰۰ درخواست	۶۰ ثانیه

درخواستِ بیش از حد با 429 و Retry-After رد می‌شود — با همان فاصله دوباره بفرستید.

قاعده‌ها

۱
شناسه‌ی سفارشفقط حروفِ انگلیسی، عدد، نقطه و خطِ زیر؛ حداکثر ۶۴ نویسه.
۲
شناسه‌ی تکراریتکرارِ همان order_id همان فاکتورِ قبلی را برمی‌گرداند؛ فاکتورِ دوم نمی‌سازد.
۳
هر کلید، فقط سفارش‌های خودشهر کلید فقط فاکتورهای خودش را می‌بیند و تایید می‌زند.
۴
تاییدِ تکراری بی‌خطر استدو بار تایید زدن چیزی را دوباره حساب نمی‌کند.
۵
دستی «پرداخت‌شده» نکنیدوضعیت همیشه از سمتِ درگاه بررسی می‌شود؛ عدد را خودتان عوض نکنید.

تستِ سلامت

curl https://pay.polgram.nls2026h.xyz/healthz

پاسخِ سالم: {"ok": true} — اگر چیزِ دیگری آمد یا کدِ 503 گرفتید، سرویس موقتاً در دسترس نیست و باید بعداً دوباره تلاش کنید.

کارمزدِ هر پرداخت از مبلغِ فروش کم می‌شود و مبلغِ خالص به موجودیِ شما می‌نشیند؛ نرخِ دقیق را در پنلِ همین ربات می‌بینید.