Payexa Wallet Demo (Flask)

An example Flask project for wallet top-up using Payexa payment gateway.

This demo covers the complete server-side payment flow:

1. Create top-up order in local database
2. Request payment from Payexa (/v1/payment/request)
3. Redirect user to Payexa start pay page
4. Receive callback in your app
5. Verify payment with Payexa (/v1/payment/verify)
6. Credit wallet only on successful verify (idempotent)

Features

• Flask + SQLAlchemy (SQLite)
• Wallet and top-up order models
• Full order lifecycle statuses
• Server-side verify before crediting balance
• Idempotent crediting using credited flag
• Stores callback payload and verify response for debugging

Project Structure

• run.py: app entrypoint
• app/__init__.py: app factory and config loading
• app/models.py: database models
• app/payment_gateway.py: Payexa HTTP client
• app/routes.py: web routes and payment flow
• app/templates/: UI templates

Local Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Then set real values in .env:

• PAYEXA_BASE_URL: sandbox or production URL
• PAYEXA_API_KEY: your merchant API key

Run

flask --app run.py --debug run

Open http://127.0.0.1:5000/.

Environment Variables

See .env.example for all options.

Important keys:

• PAYEXA_BASE_URL=https://sandbox.pexn.ir (production: https://pay.pexn.ir)
• PAYEXA_STARTPAY_PATH=/startPay
• PAYEXA_REQUEST_ENDPOINT=/v1/payment/request
• PAYEXA_VERIFY_ENDPOINT=/v1/payment/verify
• PAYEXA_CALLBACK_PATH=/payments/callback
• PAYEXA_BADGE_SCRIPT_URL=https://pexn.ir/merchant-badge.js?token=... (template already renders the required badge <div>)

Publish Checklist

Before publishing this project as an example on your website or GitHub:

1. Do not commit .env or any real API key.
2. Keep only placeholder values in .env.example.
3. Set production PAYEXA_BASE_URL to https://pay.pexn.ir.
4. Use a public HTTPS domain for callback URL.
5. Disable debug mode in production runtime.
6. Replace any localhost-only scripts (for example trust badge scripts) with public URL.
7. Use a production-grade DB (PostgreSQL/MySQL) instead of SQLite if needed.

Payment Safety Notes

• Never credit wallet balance directly from callback status alone.
• Always verify transaction server-to-server with Payexa.
• Handle verify 200 as success and 201 as already-verified.
• Keep idempotency guard to prevent duplicate balance increase.

License

Use this project as an educational example. Add your preferred license before public release.

نسخه رسمي فارسي

معرفي پروژه

اين پروژه يک نمونه عملي براي يکپارچه سازي درگاه پرداخت Payexa در يک وب اپليکيشن Flask است.

جريان کامل پرداخت در اين دمو:

1. ايجاد سفارش شارژ در پايگاه داده محلي
2. ارسال درخواست پرداخت به Payexa (/v1/payment/request)
3. هدايت کاربر به صفحه پرداخت Payexa
4. دريافت callback در اپليکيشن
5. وريفاي تراکنش با Payexa (/v1/payment/verify)
6. افزايش موجودي کيف پول فقط بعد از وريفاي موفق (idempotent)

ويژگي ها

• پياده سازي با Flask و SQLAlchemy
• مدل کيف پول و سفارش شارژ
• مديريت چرخه کامل وضعيت سفارش
• اعتبارسنجي نهايي سمت سرور قبل از افزايش موجودي
• جلوگيري از افزايش تکراري موجودي با credited
• ذخيره payload هاي callback و verify براي تحليل و خطايابي

ساختار پروژه

• run.py: نقطه شروع اجراي برنامه
• app/__init__.py: بارگذاري تنظيمات و ساخت اپ
• app/models.py: مدل هاي پايگاه داده
• app/payment_gateway.py: لايه ارتباط با Payexa
• app/routes.py: مسيرها و منطق جريان پرداخت
• app/templates/: قالب هاي رابط کاربري

راه اندازي محلي

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

سپس مقادير واقعي را در .env قرار دهيد:

• PAYEXA_BASE_URL
• PAYEXA_API_KEY

نمونه تنظيمات مهم:

PAYEXA_BASE_URL=https://sandbox.pexn.ir
PAYEXA_API_KEY=YOUR_API_KEY
PAYEXA_STARTPAY_PATH=/startPay
PAYEXA_REQUEST_ENDPOINT=/v1/payment/request
PAYEXA_VERIFY_ENDPOINT=/v1/payment/verify
PAYEXA_CALLBACK_PATH=/payments/callback
PAYEXA_TIMEOUT_SECONDS=12
PAYEXA_BADGE_SCRIPT_URL=https://pexn.ir/merchant-badge.js?token=YOUR_BADGE_TOKEN

اجرا

flask --app run.py --debug run

آدرس برنامه:

http://127.0.0.1:5000/

نکات امنيتي و عملياتي

• کليد API را فقط در سمت سرور نگه داريد.
• صرف callback را ملاک افزايش موجودي قرار ندهيد.
• افزايش موجودي فقط بعد از verify موفق انجام شود.
• براي verify با کد 201، افزايش موجودي مجدد انجام ندهيد.

چک ليست انتشار عمومي

1. فايل .env و کليدهاي واقعي را commit نکنيد.
2. در .env.example فقط مقادير نمونه نگه داريد.
3. در محيط production از PAYEXA_BASE_URL=https://pay.pexn.ir استفاده کنيد.
4. آدرس callback را روي دامنه عمومي HTTPS تنظيم کنيد.
5. حالت debug را در production خاموش کنيد.
6. اسکریپت هاي وابسته به localhost (مثل badge) را با URL عمومي جايگزين کنيد.
7. در انتشار واقعي، به جاي SQLite از PostgreSQL/MySQL استفاده کنيد.