PAYEXA SOLUTIONS

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

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

بدون ریدایرکت نمایش کارت در همان چت استعلام خودکار یا دکمه دستی Request → Info → Status → Verify

Quick Start

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

Operational Rule

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

Production Safety

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

AUTH HEADER

X-API-KEY

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

FINALIZATION

Status → Verify

وقتی status برابر SUCCESS شد، verify بزنید تا سفارش برای شما هم نهایی (merchant_verified) شود.

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