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

PAYEXA SOLUTIONS

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

این ساده‌ترین راه اتصال به پی‌اکساست: بات بله خودِ پی‌اکسا کل تجربه پرداخت (نمایش کارت، مبلغ، تایید) را داخل چت انجام می‌دهد. شما فقط یک لینک می‌سازید و به مشتری می‌دهید؛ هیچ رابط پرداختی نمی‌سازید.

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

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

Quick Start

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

Operational Rule

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

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

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

API VERSION

v2 (پیش‌فرض)

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

FINALIZATION

Verify

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

DOC MAP · v2

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

مرجع کامل API

برای هدرها و کدهای خطا به مستندات پذیرنده مراجعه کنید.

معادل تلگرامی همین راه‌حل

بات آماده تلگرام (@payexa_bot) هم دقیقاً همین‌طور کار می‌کند.

راه‌حل تلگرام اختصاصی

اگر می‌خواهید خودتان کارت و مبلغ را داخل ربات تلگرام نشان دهید، این راهنما را ببینید.

1) نمای کلی — بات بله چیست

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

ساخت پرداخت

POST /v2/payments را با لینک بات بلهٔ خودتان در return_url می‌زنید؛ پاسخ لینک آمادهٔ بات پی‌اکسا را در bale_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": "BALE-88-1024",
    "return_url": "https://ble.ir/YourBot",
    "callback_url": "https://your-bot-server.example.com/payexa/callback"
  }'

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

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

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

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

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

💳 واریز به فروشگاه شما

🔢 مبلغ (دقیقاً همین رقم): 2,499,440 ریال
🏦 6037991234560010 — علی رضایی
⏳ تا 1405/07/09 13:30:00 (تهران) فرصت دارید
🧾 سفارش: BALE-88-1024

بعد از واریز، دکمه «بررسی پرداخت» را بزنید ✅

پس از تأیید واریز:

✅ پرداخت شما تایید شد

🏪 فروشگاه شما — 2,499,440 ریال
🧾 سفارش: BALE-88-1024

با تشکر از خرید شما 🌟

[ بازگشت به پذیرنده ]

تشخیص خودکار

همین که پیامک بانک واریز را تأیید کند، همین پیام بله خودش به حالت موفق ویرایش می‌شود.

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

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

شبکه ایمنی

یک بررسی پس‌زمینه هم هر چند ثانیه اجرا می‌شود تا اگر به‌روزرسانی آنی موفق نشد، خودش جبران کند.

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

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

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

با این payment_id وریفای کنید (بخش ۵) و اگر first_verification برابر true بود، سفارش را تحویل دهید و پیام موفقیت را از بات خودتان بفرستید.
لینک بات را در return_url بگذارید، نه callback_url.
این دکمه فقط راحتی مشتری است؛ اگر آن را نزند، اعلان امضاشده یا استعلام کار را تمام می‌کند.

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

POST

نکته مهم

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

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": "BALE-88-1024",
    "status": "paid",
    "first_verification": true,
    ...
  }
}

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

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

Verify = تنها تأیید

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

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

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

بات ثبت‌شده

بات و دامنهٔ سرورش را در پنل ثبت کنید؛ return_url و callback_url باید روی همان‌ها باشند.

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

DOC MAP · v1

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

مرجع کامل API

برای هدرها و کدهای خطا به مستندات پذیرنده مراجعه کنید.

معادل تلگرامی همین راه‌حل

بات آماده تلگرام (@payexa_bot) هم دقیقاً همین‌طور کار می‌کند.

راه‌حل تلگرام اختصاصی

اگر می‌خواهید خودتان کارت و مبلغ را داخل ربات تلگرام نشان دهید، این راهنما را ببینید.

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

1) نمای کلی — بات بله چیست

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

مثل همیشه payment/request را می‌زنید؛ پاسخ یک فیلد اضافه دارد: bale_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",
  "bale_deep_link": "https://ble.ir/PayexaBot?start=pay_A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

همین bale_deep_link را به مشتری بدهید؛ نیازی به card_number یا amount_unique در این روش نیست چون بات بله خودش نشانشان می‌دهد.
order_id و amount_unique را همچنان نزد خودتان نگه دارید — برای مرحله verify لازمشان دارید.

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

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

💳 واریز به فروشگاه شما

🔢 مبلغ (دقیقاً همین رقم): 250,170 ریال
🏦 603799******0010 — علی رضایی
⏳ تا 15:15 فرصت دارید
🧾 سفارش: ORD-AB12CD34EF56

بعد از واریز، دکمه «بررسی پرداخت» را بزنید ✅

تشخیص خودکار

همین که پیامک بانک تراکنش را تایید کند، همین پیام بله خودش به حالت موفق ادیت می‌شود.

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

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

شبکه ایمنی

یک بررسی پس‌زمینه هم هر چند ثانیه اجرا می‌شود تا اگر به‌روزرسانی آنی موفق نشد، خودش جبران کند.

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

POST

نکته مهم

بات بله فقط پرداخت را نشان می‌دهد و رصد می‌کند — سفارش را نهایی نمی‌کند. «callback» صرفاً یک اطلاع‌رسانی HTTP است؛ هرکسی می‌تواند یک POST جعلی به آدرس callback شما بفرستد. برای همین، شما هنوز باید در سرور خودتان verify بزنید و فقط بعد از پاسخ موفقش سفارش را تحویل بدهید — دقیقاً مثل راه‌حل API مستقیم.

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 نزند، سیستم خودش دوباره callback را برایتان تکرار می‌کند تا فراموش نشود.

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

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

فیلد meta	توضیح
merchant_bale_bot_token	توکن بات بله خودتان (از BotFather بله).
merchant_bale_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_bale_bot_token": "123456:ABC-YourOwnBaleBotToken",
      "merchant_bale_chat_id": "987654321"
    }
  }'

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

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

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

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

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

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

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

نتیجه verify هر order_id را ذخیره کنید تا اگر callback دوباره رسید، دوباره verify نزنید.

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