در نسخهٔ ۲ لینک بات آماده در telegram_url می‌آید، لینک بات خودتان در return_url می‌رود و نتیجه با اعلان امضاشده می‌رسد؛ دیگر لازم نیست توکن ربات‌تان را بفرستید. اتصال‌های نسخهٔ ۱ بدون تغییر کار می‌کنند.

PAYEXA SOLUTIONS

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

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

صفر خط کد برای نمایش پرداخت فقط یک لینک آماده بازگشت به ربات شما با یک دکمه هنوز به Verify نیاز دارید

آموزش گام‌به‌گام اتصال ربات شما به ربات آمادهٔ پی‌اکسا: آموزش اتصال درگاه پرداخت به ربات تلگرام

Quick Start

یک پرداخت بسازید، لینک آمادهٔ بات را از پاسخ بگیرید و دکمهٔ «پرداخت» کنید.

Operational Rule

دکمهٔ بازگشت فقط راحتی کاربر است؛ سفارش را فقط بعد از وریفای موفق تحویل دهید.

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

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

API VERSION

v2 (پیش‌فرض)

راهنمای نسخهٔ ۱ هم از دکمهٔ «نسخهٔ ۱» بالای صفحه در دسترس است.

FINALIZATION

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

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

DOC MAP · v2

1. نمای کلی Flow 2. ساخت پرداخت و لینک بات POST 3. داخل بات تلگرام چه می‌گذرد Auto 4. برگشت به ربات شما /start 5. کاری که شما باید انجام دهید POST 6. نکات امنیتی Ops

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

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

ساخت پرداخت

POST /v2/payments را با لینک ربات خودتان در return_url می‌زنید؛ پاسخ لینک آمادهٔ بات را در telegram_url دارد.

دکمهٔ «پرداخت»

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

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

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

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

به محض تأیید پیامکی واریز، پیام بات خودش به حالت موفق درمی‌آید و دکمهٔ «بازگشت به پذیرنده» ظاهر می‌شود.

برگشت به ربات شما و اعلان سرور

مشتری با دکمه به ربات شما برمی‌گردد (/start <payment_id>) و اگر callback_url داده باشید، سرور ربات‌تان هم اعلان امضاشده می‌گیرد.

Verify و تحویل

سرور شما وریفای می‌زند و فقط اگر first_verification: true بود سفارش را تحویل می‌دهد.

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

POST

لینک بات خودتان را در return_url بفرستید. اگر ربات وب‌سرور دارد، callback_url را هم روی دامنهٔ سرورش بدهید.

https://pay.pexn.ir/v2/payments

curl -X POST "https://pay.pexn.ir/v2/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "order_id": "TG-88-1024",
    "return_url": "https://t.me/YourBot",
    "callback_url": "https://your-bot-server.example.com/payexa/callback"
  }'

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

{
  "ok": true,
  "data": {
    "payment_id": "A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "order_id": "TG-88-1024",
    "status": "pending",
    "telegram_url": "https://t.me/payexa_bot?start=pay_A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "payment_url": "https://pay.pexn.ir/payment/start?authority=A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    ...
  }
}

دکمهٔ «پرداخت» زیر پیام ربات شما:

{
  "chat_id": 123456789,
  "text": "سفارش شما آماده است؛ برای پرداخت دکمهٔ زیر را بزنید.",
  "reply_markup": { "inline_keyboard": [[ { "text": "💳 پرداخت", "url": "<telegram_url>" } ]] }
}

فقط payment_id را کنار سفارش نگه دارید؛ برای وریفای چیز دیگری لازم نیست.
اگر بات پی‌اکسا در دسترس نباشد، telegram_url برابر null است؛ آن وقت payment_url را بدهید که داخل تلگرام هم باز می‌شود.
ربات شما و دامنهٔ سرورش باید در پنل، صفحهٔ «درخواست درگاه پرداخت»، ثبت و تأیید شده باشند.

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

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

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

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

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

[ متوجه شدم ]

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

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

🏪 فروشنده: فروشگاه شما
🧾 شماره سفارش: TG-88-1024
📌 وضعیت: در انتظار واریز
💰 مبلغ قابل واریز: 2,499,440 ریال

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

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

شمارهٔ سفارش خودتان

در نسخهٔ ۲، بات همان order_id شما را نشان می‌دهد تا مشتری سفارش را بشناسد.

تشخیص خودکار

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

دکمهٔ «بازگشت به پذیرنده»

پس از پرداخت (یا پایان مهلت) ظاهر می‌شود و مشتری را به ربات شما برمی‌گرداند (بخش ۴).

4) برگشت مشتری به ربات شما

دکمهٔ «بازگشت به پذیرنده» ربات شما را با این لینک باز می‌کند؛ یعنی ربات شما دستور /start را همراه با payment_id خام می‌گیرد:

https://t.me/YourBot?start=A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6
→ ربات شما دریافت می‌کند:  /start A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6

def on_start(chat_id, text):
    parts = text.split(maxsplit=1)          # "/start A7F3..."
    if len(parts) != 2:
        return show_menu(chat_id)
    result = verify(parts[1])               # POST /v2/payments/{payment_id}/verify
    if result["ok"] and result["data"]["first_verification"]:
        deliver_order(result["data"]["order_id"])
        send_message(chat_id, "✅ پرداخت شما تأیید شد؛ سفارش تحویل شد.")
    elif result["ok"]:
        send_message(chat_id, "✅ این پرداخت قبلاً تأیید و تحویل شده است.")
    else:
        send_message(chat_id, result["error"]["message"])

لینک ربات را در return_url بگذارید، نه callback_url؛ callback_url آدرس سرور است و لینک t.me آنجا پذیرفته نمی‌شود.
payload همان payment_id خام است (مثل نسخهٔ ۱ که authority خام بود)؛ ربات‌هایی که برای نسخهٔ ۱ ساخته شده‌اند همین را می‌شناسند.
این دکمه فقط راحتی مشتری است؛ اگر مشتری آن را نزند، اعلان امضاشده (بخش ۵) یا استعلام، کار را تمام می‌کند.

5) کاری که شما باید انجام دهید — اعلان و Verify

POST

نکته مهم

بات تلگرام فقط پرداخت را نشان می‌دهد و رصد می‌کند — سفارش را نهایی نمی‌کند. سفارش را فقط با وریفای سمت سرور خودتان تحویل دهید. هر سه راه به همین وریفای می‌رسند: برگشت مشتری با /start، اعلان امضاشده به callback_url، یا (برای ربات بدون وب‌سرور) استعلام دوره‌ای با GET https://pay.pexn.ir/v2/payments/{payment_id}/client تا وقتی وضعیت paid یا expired شود.

https://pay.pexn.ir/v2/payments/{payment_id}/verify

curl -X POST "https://pay.pexn.ir/v2/payments/A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500000}'

پاسخ موفق:

{
  "ok": true,
  "data": {
    "payment_id": "A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "order_id": "TG-88-1024",
    "status": "paid",
    "first_verification": true,
    ...
  }
}

فقط اولین وریفای first_verification: true می‌گیرد؛ حتی اگر /start و اعلان هم‌زمان برسند، سفارش یک بار تحویل می‌شود.
بررسی امضای اعلان اختیاری است (سفارش فقط با وریفای تحویل می‌شود)؛ روش و کد آن در مستندات، بخش امضا است.
توکن ربات‌تان را برای پی‌اکسا نفرستید؛ نسخهٔ ۲ آن را لازم ندارد و پیام موفقیت را خود ربات شما پس از وریفای می‌فرستد.

6) نکات امنیتی

Verify = تنها تأیید

با دکمهٔ بازگشت یا اعلان به‌تنهایی سفارش را تحویل ندهید؛ فقط first_verification=true.

راه جایگزین

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

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

API Key را فقط در سرور ربات نگه دارید و توکن ربات‌تان را به هیچ سرویسی ندهید.

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

راهنمای نسخهٔ ۱ (قدیمی). ربات‌هایی که با این روش وصل شده‌اند بدون هیچ تغییری کار می‌کنند و پشتیبانی می‌شوند. برای اتصال تازه، نسخهٔ ۲ را استفاده کنید: ساده‌تر است (فقط یک شناسه، وریفای بدون توکن مبلغ و اعلان امضاشده).

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

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

مثل همیشه 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ها به مستندات کامل پذیرنده مراجعه کنید.
اگر ترجیح می‌دهید کارت و مبلغ را خودتان داخل ربات‌تان طراحی کنید (به‌جای استفاده از بات آماده)، راه‌حل پیاده‌سازی اختصاصی را ببینید.
معادل همین راه‌حل برای بله هم موجود است: راه‌حل بات آماده بله.