لوگوی پي اكسا

PAYEXA SOLUTIONS

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

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

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

Quick Start

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

Operational Rule

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

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

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

AUTH HEADER

X-API-KEY

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

FINALIZATION

Callback → Verify

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

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

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

01

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

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

02

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

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

03

تجربه کامل داخل بات بله

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

04

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

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

05

دریافت callback

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

06

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 نزنید.

PAYEXA ASSISTANT

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