PAYEXA SOLUTIONS

راه‌حل استفاده از بات آماده تلگرام پی‌اکسا

دقیقاً هم‌خانواده‌ی راه‌حل بات بله: به‌جای اینکه خودتان شماره کارت و مبلغ را در ربات‌تان نشان دهید، مشتری را با یک لینک به بات آماده‌ی تلگرام پی‌اکسا (@payexa_bot) می‌فرستید و خودش کل تجربه پرداخت را نشان و رصد می‌کند.

صفر خط کد برای نمایش پرداخت فقط یک لینک (telegram_deep_link) دو مرحله: هشدار مبلغ سپس جزئیات کارت هنوز به Verify نیاز دارید

Quick Start

یک payment/request بزنید، فیلد telegram_deep_link پاسخ را بگیرید و به مشتری بدهید.

Operational Rule

هرگز فقط منتظر برگشت کاربر نمانید؛ سرور خودتان باید مستقل و دوره‌ای verify بزند.

تفاوت با راه‌حل API مستقیم

نمایش کارت و استعلام وضعیت را دیگر شما پیاده نمی‌کنید؛ بات پی‌اکسا خودش انجام می‌دهد.

AUTH HEADER

X-API-KEY

فقط برای ساخت درخواست (payment/request) و verify لازم است.

FINALIZATION

Verify (پول شما اهمیت دارد)

دکمه بازگشت فقط یک راحتی UX است؛ تنها verify موفق تضمین‌شده است.

1) نمای کلی — بات آماده تلگرام پی‌اکسا چیست

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

ساخت درخواست پرداخت

مثل همیشه payment/request را می‌زنید؛ پاسخ یک فیلد اضافه دارد: telegram_deep_link.

دادن لینک به مشتری

همین لینک را در بات یا سایت خودتان به مشتری نشان دهید — یک دکمه کافی است.

هشدار مبلغ، سپس جزئیات کارت

بات پی‌اکسا اول یک هشدار «مبلغ را دقیق واریز کنید» نشان می‌دهد؛ با تایید کاربر («متوجه شدم»)، شماره کارت و نام صاحب کارت نمایش داده می‌شود.

تشخیص خودکار واریز

به محض تایید پیامکی واریز، همان پیام تلگرام خودش به‌روزرسانی می‌شود — بدون هیچ کاری از سمت مشتری یا شما.

دریافت callback

سرور شما callback را می‌گیرد؛ این فقط یک اطلاع‌رسانی است، نه تایید نهایی.

Verify و نهایی‌سازی

سرور شما payment/verify می‌زند (دوره‌ای و مستقل، نه فقط با کلیک کاربر) و فقط بعد از موفقیتش سفارش را تحویل می‌دهد.

2) ساخت درخواست و گرفتن لینک بات

POST

همان endpoint همیشگی؛ چیز جدیدی لازم نیست بفرستید، فقط یک فیلد جدید در پاسخ می‌گیرید.

https://pay.pexn.ir/v1/payment/request

curl https://pay.pexn.ir/v1/payment/request \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: YOUR_API_KEY" \
  --data '{
    "amount": 250000,
    "callback_url": "https://your-server.example.com/payexa/callback",
    "meta": {"order_ref": "ORDER-8841231"}
  }'

پاسخ موفق (HTTP 201):

{
  "authority": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "order_id": "ORD-AB12CD34EF56",
  "amount_unique": 250170,
  "card_number": "603799******0010",
  "expire_at": "2026-09-25T07:15:00",
  "telegram_deep_link": "https://t.me/payexa_bot?start=pay_A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

همین telegram_deep_link را به مشتری بدهید؛ نیازی به card_number یا amount_unique در این روش نیست چون بات خودش نشانشان می‌دهد.
authority، order_id و amount_unique را همچنان نزد خودتان نگه دارید — برای مرحله verify و دکمه بازگشت (بخش ۵) لازمشان دارید.

3) داخل بات تلگرام چه می‌گذرد (کاملاً خودکار)

این بخش را شما پیاده نمی‌کنید؛ فقط بدانید مشتری چه می‌بیند تا بتوانید پشتیبانی بدهید.

⚠️ هشدار مهم قبل از واریز

مبلغ نمایش داده شده را باید دقیقاً بدون ۱ ریال کم یا زیاد واریز کنید.
مبلغ دقیق قابل واریز: 250170 ریال

⏳ مدت زمان ۱۵ دقیقه است و واریزی بعد از آن تایید نمی‌شود.

[ متوجه شدم ]

بعد از کلیک روی «متوجه شدم»:

💳 اطلاعات پرداخت PAYEXA

🏪 فروشنده: فروشگاه شما
🧾 شماره سفارش: ORD-AB12CD34EF56
📌 وضعیت: در انتظار واریز
💰 مبلغ قابل واریز: 250,170 ریال

🏦 مشخصات کارت مقصد
شماره کارت: 603799******0010
نام دارنده: علی رضایی

⏳ مهلت پرداخت: ۱۵ دقیقه

[ 🔄 بررسی وضعیت پرداخت ]
[ 💳 کپی شماره کارت ] [ 💰 کپی مبلغ ]

دو مرحله‌ای، عمدی

هشدار مبلغ قبل از کارت نشون داده می‌شه تا کاربر قبل از دیدن شماره کارت، اهمیت دقیق‌بودن مبلغ رو متوجه بشه.

تشخیص خودکار

همین که پیامک بانک تراکنش را تایید کند، همین پیام تلگرام خودش به حالت موفق ویرایش می‌شود (هر چند ثانیه یک‌بار sync).

دکمه «بررسی وضعیت پرداخت»

مشتری هر وقت بخواهد می‌تواند دستی هم بررسی کند؛ نتیجه همان لحظه در پیام آپدیت می‌شود.

4) کاری که شما باید انجام دهید — Callback و Verify

POST

نکته مهم

بات تلگرام فقط پرداخت را نشان می‌دهد و رصد می‌کند — سفارش را نهایی نمی‌کند. «callback» صرفاً یک اطلاع‌رسانی HTTP است. برای همین، شما هنوز باید در سرور خودتان verify بزنید و فقط بعد از پاسخ موفقش سفارش را تحویل بدهید. هرگز فقط منتظر کلیک کاربر روی دکمه بازگشت نمانید — بهترین حالت این است که یک بررسی دوره‌ای (چند تلاش با فاصله چند ثانیه/دقیقه) در سرور خودتان زمان‌بندی کنید که مستقل از رفتار کاربر، verify را تکرار کند.

https://pay.pexn.ir/v1/payment/verify

curl https://pay.pexn.ir/v1/payment/verify \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: YOUR_API_KEY" \
  --data '{
    "order_id": "ORD-AB12CD34EF56",
    "token": "250170"
  }'

پاسخ موفق:

{
  "status": "SUCCESS",
  "merchant_verified": true,
  "merchant_verified_at": "2026-09-25T07:03:41"
}

token دقیقاً همان amount_unique است که در مرحله ۲ گرفتید (به‌صورت رشته).
تا وقتی verify نزنید یا مهلت تمام نشده، دوباره verify زدن بی‌خطر است — پاسخ فعلی وضعیت (pending/expired/success) را نشان می‌دهد.

5) دکمه «بازگشت به پذیرنده» — یک نکته فنی مهم

اگر می‌خواهید مشتری بعد از پرداخت با یک دکمه به بات خودتان برگردد، کافی است موقع ساخت درخواست، callback_url را به‌جای یک آدرس HTTPS، لینک بات خودتان بگذارید:

"callback_url": "https://t.me/your_own_bot"

نکته دقیق و اجباری برای طراحی بات شما

وقتی callback_url یک لینک تلگرامی باشد، بات پی‌اکسا دکمه بازگشت را با https://t.me/your_own_bot?start=<authority> می‌سازد — یعنی payload همیشه همان authority خام است (نه چیزی که شما در callback_url گذاشته بودید). پس بات شما باید بتواند با یک /start <authority> خام، تراکنش متناظرش را با همان authorityای که در مرحله ۲ ذخیره کرده بودید پیدا کند.

این دکمه فقط بعد از نهایی‌شدن وضعیت (موفق، ناموفق یا منقضی) نمایش داده می‌شود، نه در حالت در انتظار.
این صرفاً یک راحتی برای کاربر است؛ به‌تنهایی دلیل کافی برای تحویل سفارش نیست — همیشه verify (بخش ۴) ملاک نهایی است.
اگر callback_url یک آدرس HTTPS عادی (نه تلگرامی) باشد، همان آدرس با پارامترهای status و authority به‌عنوان دکمه بازگشت استفاده می‌شود.

6) اطلاع مستقیم به بات خودتان (اختیاری)

اگر می‌خواهید همان لحظه‌ی تایید واریز یک پیام در چت بات خودتان ببینید، کافی است موقع ساخت درخواست این دو مقدار را هم در meta بفرستید — هیچ کد دیگری لازم نیست.

فیلد meta	توضیح
merchant_telegram_bot_token	توکن بات تلگرام خودتان (از BotFather).
merchant_telegram_chat_id	شناسه چتی که پیام تایید باید در آن ارسال شود.

curl https://pay.pexn.ir/v1/payment/request \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: YOUR_API_KEY" \
  --data '{
    "amount": 250000,
    "callback_url": "https://your-server.example.com/payexa/callback",
    "meta": {
      "order_ref": "ORDER-8841231",
      "merchant_telegram_bot_token": "123456:ABC-YourOwnBotToken",
      "merchant_telegram_chat_id": "987654321"
    }
  }'

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

7) نکات امنیتی

Callback ≠ تایید نهایی

هرگز فقط با رسیدن callback یا کلیک دکمه بازگشت سفارش را تحویل ندهید؛ همیشه منتظر پاسخ موفق verify بمانید.

استعلام مستقل و دوره‌ای

درست بعد از ساخت درخواست، یک بررسی خودکار (چند تلاش با فاصله زمانی) در سرور خودتان زمان‌بندی کنید؛ به رفتار کاربر متکی نباشید.

کلید فقط سمت سرور

X-API-KEY و توکن بات تلگرام خودتان را فقط در سرور نگه دارید، نه در کلاینت.

برای جزئیات کامل هدرها، کدهای خطا و rate limitها به مستندات کامل پذیرنده مراجعه کنید.
اگر ترجیح می‌دهید کارت و مبلغ را خودتان داخل ربات‌تان طراحی کنید (به‌جای استفاده از بات آماده)، راه‌حل پیاده‌سازی اختصاصی را ببینید.
معادل همین راه‌حل برای بله هم موجود است: راه‌حل بات آماده بله.