با نسخهٔ ۲ همهٔ اطلاعات کارت (حتی نام صاحب کارت) در همان پاسخ ساخت پرداخت می‌آید و دیگر درخواست دوم لازم نیست. ربات‌هایی که با نسخهٔ ۱ ساخته شده‌اند بدون تغییر کار می‌کنند.

PAYEXA SOLUTIONS

راه‌حل اتصال پرداخت پی‌اکسا در ربات تلگرام

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

بدون ریدایرکت نمایش کارت در همان چت اعلان امضاشده یا استعلام Create → Show → Verify

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

Quick Start

یک پرداخت بسازید و کارت، مبلغ دقیق و مهلت را از همان پاسخ در پیام ربات نشان دهید.

Operational Rule

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

Production Safety

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

API VERSION

v2 (پیش‌فرض)

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

FINALIZATION

Verify

سفارش را فقط وقتی تحویل دهید که وریفای سمت سرور تأیید کند.

1) نمای کلی جریان در ربات تلگرام

کل کار همین ۵ قدم است؛ بقیهٔ صفحه هر قدم را با نمونه باز می‌کند.

ساخت پرداخت

وقتی کاربر مبلغ را انتخاب کرد، سرور ربات POST /v2/payments را می‌زند. پاسخ همه‌چیز را دارد: شماره کارت، نام صاحب کارت، مبلغ دقیق و مهلت.

نمایش در چت

همین اطلاعات را در پیام ربات نشان می‌دهید. کاربر کارت به کارت می‌کند و پی‌اکسا واریز را خودکار تشخیص می‌دهد.

فهمیدن پرداخت

اگر ربات وب‌سرور دارد، اعلان امضاشدهٔ پی‌اکسا به‌محض پرداخت می‌رسد. وگرنه (یا در کنارش) وضعیت را خودکار یا با دکمهٔ «پرداخت کردم» بپرسید.

وریفای

وقتی وضعیت paid شد، POST /v2/payments/{payment_id}/verify را بزنید.

تحویل، فقط یک بار

اگر وریفای first_verification: true برگرداند، سفارش را در ربات تحویل دهید؛ اگر false بود، قبلاً تحویل داده‌اید.

2) ساخت پرداخت (همه‌چیز در یک پاسخ)

POST

سرور ربات شما این درخواست را با کلید API می‌فرستد. پاسخ، کارت کامل (با نام صاحب کارت)، مبلغ دقیق و مهلت را دارد.

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

فیلد درخواست	نوع	الزام	توضیح
amount	integer	بله	مبلغ به ریال.
order_id	string	بله	شمارهٔ سفارش خودتان، برای هر سفارش یکتا (مثلاً TG-88-1024). درخواست تکراری با همین شماره همان پرداخت را برمی‌گرداند.
return_url	string	بله*	لینک ربات خودتان، مثل https://t.me/YourBot؛ اگر خریدار از صفحه یا ربات پرداخت پی‌اکسا پرداخت کند، با آن به ربات شما برمی‌گردد.
callback_url	string	اختیاری*	اگر ربات وب‌سرور دارد: آدرس سرور ربات برای اعلان امضاشده (بخش ۴). * از این دو، حداقل یکی لازم است.

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",
    "amount": 2500000,
    "payable_amount": 2499440,
    "payable_amount_toman": 249944,
    "expires_at": "2026-10-01T10:00:00Z",
    "card": { "number": "6037991234560010", "holder_name": "علی رضایی", "bank": "ملی" },
    "payment_url": "https://pay.pexn.ir/payment/start?authority=A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "telegram_url": "https://t.me/payexa_bot?start=pay_A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    ...
  }
}

فقط payment_id را کنار سفارش ذخیره کنید؛ بقیه را هر وقت لازم شد از استعلام (بخش ۵) هم می‌گیرید.
به کاربر payable_amount را نشان دهید، نه amount؛ همین رقم دقیق است که واریز با آن شناسایی می‌شود.
اگر ترجیح دادید کاربر در صفحه یا ربات آمادهٔ پی‌اکسا پرداخت کند، payment_url یا telegram_url همین پاسخ را دکمه کنید (راه‌حل بات آماده).

3) نمایش به کاربر در همان چت

یک پیام با همین چند فیلد کافی است؛ نمونهٔ متن پیام ربات:

💳 شماره کارت: 6037991234560010
👤 به نام: علی رضایی (بانک ملی)
💰 مبلغ دقیق واریزی: 2,499,440 ریال
⏳ مهلت پرداخت: تا 13:30

دقیقاً همین مبلغ را واریز کنید؛ بعد از واریز، چند ثانیه صبر کنید و «پرداخت کردم، بررسی کن» را بزنید.

p = response["data"]
text = (
    f"💳 شماره کارت: {p['card']['number']}\n"
    f"👤 به نام: {p['card']['holder_name']} (بانک {p['card']['bank']})\n"
    f"💰 مبلغ دقیق واریزی: {p['payable_amount']:,} ریال\n"
    f"⏳ مهلت پرداخت: تا {to_local_time(p['expires_at'])}"
)
buttons = [[{"text": "✅ پرداخت کردم، بررسی کن", "callback_data": f"check:{p['payment_id']}"}]]

expires_at به وقت UTC است؛ برای کاربر به ساعت ایران تبدیلش کنید یا شمارش معکوس نشان دهید.
برای پذیرندهٔ آزمایشی (testnet) ممکن است card برابر null باشد؛ در حالت عادی همیشه پر است.

4) اعلان امضاشده (اگر ربات وب‌سرور دارد)

POST

اگر callback_url فرستاده باشید، پی‌اکسا به‌محض تأیید واریز یک POST امضاشده به آن می‌فرستد؛ دیگر لازم نیست مدام استعلام کنید. امضا را با API Key بررسی کنید، payment_id را بخوانید و به بخش ۶ (وریفای) بروید.

POST /payexa/callback
X-Payexa-Event: payment.paid
X-Payexa-Signature: t=1790000000,v1=5f2b9c...e81a

{"event":"payment.paid","payment_id":"A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6","order_id":"TG-88-1024","status":"paid",...}

کد کامل مسیر برگشت در مستندات، کد کامل آماده و بررسی (اختیاری) امضا در بخش امضا آمده است.
تا وریفای نکنید، اعلان payment.paid چند بار تکرار می‌شود؛ اگر پرداخت نشد، یک اعلان payment.expired می‌رسد تا سفارش را آزاد کنید.

5) استعلام خودکار یا دکمهٔ «پرداخت کردم»

GET

برای ربات بدون وب‌سرور، یا در کنار اعلان، وضعیت را با این مسیر بپرسید. این مسیر کلید API نمی‌خواهد و فقط وضعیت همان یک پرداخت را می‌دهد.

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

{
  "ok": true,
  "data": {
    "payment_id": "A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "status": "pending",
    "payable_amount": 2499440,
    "seconds_remaining": 1320,
    "paid_at": null,
    ...
  }
}

status	کار ربات
pending	«هنوز ثبت نشده؛ چند ثانیه دیگر دوباره بزن.» (استعلام خودکار: ۱۰ تا ۱۵ ثانیهٔ دیگر)
paid	برو به بخش ۶ (وریفای).
expired	«مهلت تمام شد»؛ استعلام را متوقف کنید. کاربر می‌تواند با همان order_id دوباره پرداخت بسازد.

نکتهٔ مهم عملیاتی

وقتی seconds_remaining به صفر رسید یا وضعیت expired شد، دیگر استعلام نزنید.
روی دکمهٔ دستی محدودیت بگذارید (مثلاً هر ۵ ثانیه یک بار)؛ حداکثر ۶۰ استعلام در دقیقه برای هر پرداخت پذیرفته می‌شود.
استعلام خودکار، دکمهٔ دستی و اعلان امضاشده با هم تناقضی ندارند؛ هر کدام زودتر paid را دید، وریفای را شروع کند.

6) وریفای و تحویل سفارش

POST

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

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 است محصول یا سرویس را تحویل دهید یا کیف پول کاربر را شارژ کنید؛ حتی اگر دکمه، استعلام و اعلان هم‌زمان وریفای بزنند، فقط یکی true می‌گیرد.
وریفای تکراری بی‌خطر است و همیشه جواب درست می‌دهد؛ لازم نیست جلوی آن را بگیرید.
خطای PAYMENT_NOT_PAID یعنی هنوز پرداخت نشده و PAYMENT_EXPIRED یعنی مهلت تمام شده است.

7) نکات امنیتی و بهینه‌سازی

قبل از رفتن به تولید (production) این چند مورد را بررسی کنید.

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

API Key را فقط در سرور ربات نگه دارید؛ هرگز در پیام‌ها یا کد کلاینت قرار ندهید.

ربات ثبت‌شده

ربات و دامنهٔ سرورش را در پنل، صفحهٔ «درخواست درگاه پرداخت»، ثبت کنید؛ return_url و callback_url باید روی همان‌ها باشند.

تحویل یک‌باره

تحویل را فقط به first_verification=true ببندید تا هر سفارش دقیقاً یک بار تحویل شود.

سقف درخواست برای هر کلید: ساخت پرداخت و وریفای هر کدام ۶۰ در دقیقه؛ استعلام بدون کلید ۶۰ در دقیقه برای هر پرداخت.
برای جزئیات کامل هدرها و کدهای خطا، مستندات کامل پذیرنده را ببینید.

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

1) نمای کلی جریان در ربات تلگرام

کل ماجرا همین ۶ قدم است؛ بقیه صفحه همین‌ها را با نمونه کد باز می‌کند.

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

وقتی کاربر مبلغ را انتخاب کرد، payment/request را بزنید.

دریافت اطلاعات کامل کارت

بلافاصله با همان authority، payment/info را بزنید تا نام صاحب کارت را هم داشته باشید.

نمایش در چت

شماره کارت، نام صاحب کارت، مبلغ یکتا و مهلت پرداخت را در همان پیام ربات نشان دهید.

صبر تا مهلت، با دو ابزار استعلام

در بازه مهلت، یا خودتان دوره‌ای استعلام می‌گیرید (خودکار) یا منتظر کلیک کاربر روی «پرداخت کردم» می‌مانید (دستی).

تشخیص واریز

هر وقت payment/status برابر SUCCESS شد، یعنی پول نشسته.

Verify و نهایی‌سازی سفارش

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

2) ساخت درخواست پرداخت و دریافت اطلاعات کارت

POST

اول درخواست پرداخت را می‌سازید. پاسخ این مرحله شماره کارت (ماسک‌شده)، مبلغ یکتا و مهلت را دارد اما نام صاحب کارت را ندارد — برای آن باید بلافاصله یک درخواست دوم به payment/info بزنید.

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

فیلد درخواست	نوع	الزام	توضیح
amount	number	بله	مبلغ اصلی به ریال.
callback_url	string	بله	آدرس سرور ربات شما برای اطلاع اولیه؛ برای نهایی‌سازی همچنان به verify نیاز دارید.
meta.order_ref	string	پیشنهادی	شناسه سفارش/تراکنش داخلی خودتان (مثلاً 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-bot-server.example.com/payexa/callback",
    "meta": {"order_ref": "TG-CHAT-8841231"}
  }'

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

{
  "authority": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "order_id": "ORD-AB12CD34EF56",
  "amount_unique": 250170,
  "card_number": "603799******0010",
  "expire_at": "2026-09-25T07:15:00"
}

GET

حالا با همان authority، اطلاعات کامل (از جمله نام صاحب کارت) را می‌گیرید — این endpoint نیاز به X-API-KEY ندارد:

https://pay.pexn.ir/v1/payment/info?authority={authority}

{
  "authority": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "order_id": "ORD-AB12CD34EF56",
  "status": "PENDING",
  "amount_unique": 250170.0,
  "card_number": "603799******0010",
  "card_name": "علی رضایی",
  "expire_at": "2026-09-25T07:15:00",
  "paid_at": null,
  "merchant_verified": false
}

مقدار order_id را برای مرحله استعلام (status) نگه دارید و amount_unique را برای مرحله verify.
amount_unique با amount فرق دارد؛ همین رقم دقیق را باید به کاربر نشان دهید تا واریزش قابل تشخیص باشد.

3) نمایش به کاربر در همان چت

یک پیام ساده با همین ۴ فیلد کافی است؛ نمونه متن پیام ربات:

💳 شماره کارت: 603799******0010
👤 به نام: علی رضایی
💰 مبلغ دقیق واریزی: 250,170 تومان
⏳ مهلت پرداخت: تا 15:15

بعد از واریز، چند ثانیه صبر کنید و روی دکمه «پرداخت کردم، بررسی کن» بزنید.

همیشه amount_unique را نشان دهید، نه مبلغ اصلی درخواستی؛ این رقم یکتا همان چیزی است که سیستم برای تطبیق واریز استفاده می‌کند.
expire_at را به‌صورت شمارش معکوس یا ساعت پایان نشان دهید تا کاربر بداند چقدر وقت دارد.

4) استعلام خودکار

GET

اگر می‌خواهید ربات خودش زیر پوست دوره‌ای چک کند، همین endpoint را هر ۱۰ تا ۱۵ ثانیه یک‌بار صدا بزنید — نیازی به کلید API ندارد.

https://pay.pexn.ir/v1/payment/status?order_id={order_id}

{
  "status": "PENDING",
  "paid_at": null
}

نکته مهم عملیاتی

قبل از هر بار صدا زدن status، اول expire_at را که خودتان ذخیره کرده‌اید با ساعت فعلی مقایسه کنید. اگر گذشته، دیگر درخواست نزنید و سفارش را خودتان expired علامت بزنید — وگرنه سفارش‌های رهاشده تا ابد به سرور PAYEXA درخواست می‌فرستند.
وقتی status برابر SUCCESS شد، فوراً به مرحله ۶ (verify) بروید. تا زمانی که verify نکرده‌اید سفارش را نهایی نکنید.
اگر status برابر EXPIRED شد، به کاربر اطلاع دهید و امکان ساخت درخواست جدید (مرحله ۲) را بدهید.

5) استعلام دستی — دکمه «پرداخت کردم، بررسی کن»

GET

این روش وقتی مفید است که نمی‌خواهید ربات مدام در پس‌زمینه poll کند و ترجیح می‌دهید خود کاربر با یک دکمه استعلام را شروع کند.

به کاربر بگویید صبر کند

در همان پیام مرحله ۳ تصریح کنید: «بعد از واریز چند ثانیه صبر کنید، بعد دکمه را بزنید» — ثبت واریز روی سرور بانک/PAYEXA لحظه‌ای نیست.

با کلیک دکمه، یک بار status را صدا بزنید

همان https://pay.pexn.ir/v1/payment/status?order_id={order_id} مرحله قبل، ولی فقط یک‌بار و درست وقتی کاربر دکمه را زد.

بر اساس نتیجه پاسخ بدهید

PENDING → «هنوز ثبت نشده، چند ثانیه دیگر دوباره بزن». SUCCESS → برو به مرحله ۶ (verify). EXPIRED → «مهلت تمام شد، دوباره سفارش بده».

روی این دکمه یک محدودیت ساده بگذارید (مثلاً هر چند ثانیه یک‌بار قابل کلیک باشد) تا کاربر با کلیک پشت‌سرهم سرور را درگیر نکند.
استعلام خودکار و دکمه دستی با هم تناقضی ندارند؛ می‌توانید هر دو را همزمان فعال نگه دارید — هرکدام زودتر SUCCESS را دید، جریان verify را شروع می‌کند.

6) نهایی‌سازی سفارش با Verify

POST

همین که status برابر SUCCESS شد (چه از مسیر خودکار، چه از دکمه دستی)، این endpoint را بزنید. این تنها جایی است که سفارش رسماً برای شما هم verify می‌شود.

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

فیلد	نوع	توضیح
order_id	string	همان order_id دریافتی در مرحله ۲.
token	string	دقیقاً همان مقدار amount_unique مرحله ۲ (به‌صورت رشته). چیز دیگری اینجا لازم نیست تولید کنید.

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"
}

فقط وقتی merchant_verified برابر true برگشت، محصول/سرویس را در ربات تحویل بدهید یا کیف پول کاربر را شارژ کنید.
برای هر order_id فقط یک‌بار verify موفق کافی است؛ نتیجه را در دیتابیس خودتان ذخیره کنید تا اگر کاربر دوباره دکمه را زد، verify تکراری نزنید.

7) نکات امنیتی و بهینه‌سازی

قبل از رفتن به تولید (production) این چند مورد را بررسی کنید.

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

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

جلوگیری از poll بی‌پایان

expire_at را محلی چک کنید و بعد از گذشتن مهلت، دیگر به سرور PAYEXA درخواست نزنید.

جلوگیری از verify تکراری

وضعیت merchant_verified را در دیتابیس خودتان نگه دارید تا هر order_id دقیقاً یک‌بار نهایی شود.

هر دو endpoint ساخت درخواست و verify روی نرخ ۲۰ درخواست در دقیقه محدود هستند؛ برای هر سفارش یک بار request و یک بار verify کافی است.
در صورت بروز خطا در verify (مثلاً هنوز pending یا expired)، همان پیام خطا را برای تصمیم‌گیری بعدی (صبر بیشتر یا سفارش جدید) استفاده کنید.
برای جزئیات کامل هدرها و کدهای خطا، مستندات کامل پذیرنده را ببینید.