مرکز ابزارها، افزونه ها و مثال های اتصال

در این صفحه بسته های آماده برای اتصال به سرویس پرداخت، افزونه های کمکی و مثال های اجرایی را مثل یک ریپازیتوری مرور می کنید: فایل ها را می بینید، README را می خوانید و کل بسته را با یک دانلود می گیرید.

CONTROLLED RELEASE

انتشار کنترل شده از پنل رسمی

هر بسته از مسیر مدیریتی رسمی پی اکسا منتشر می شود و قبل از دانلود، اطلاعات کلیدی آن به صورت شفاف نمایش داده می شود.

PRE-DOWNLOAD VISIBILITY

شفافیت محتوا پیش از دریافت

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

TRUST PROFILE

نمای رسمی تر برای انتخاب ابزار

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

مرجع حقوقی و هویتی کنار دسترس

ساختار صفحه طوری چیده شده که اطلاعات انتشار، محتوای فایل ها و جزئیات هر بسته بدون شلوغی اضافه در دسترس باشند.

مثال repository / wallet-top-up-web

شارژ كيف پول

متال استفاده از پي اكسا براي شارڑ كيف پول - پايتون/فلسك

دانلود بسته

12 فایل payexa-wallet-demo-install.zip README: README.md

دانلود ثبت شده

آخرین بروزرسانی

2026-09-25

حجم بسته

12.3 KB

منتشرکننده

مدیر ارشد سامانه

وضعیت نمایش

عمومی و فعال

مرورگر فایل

پوشه جاری را انتخاب کنید یا برای فایل های متنی پیش نمایش بگیرید.

ریشه / app

نام	نوع	اندازه
بازگشت به پوشه قبل	پوشه	-
templates	پوشه	-
__init__.py	قابل پیش نمایش	1.3 KB
models.py	قابل پیش نمایش	2.1 KB
payment_gateway.py	قابل پیش نمایش	2.5 KB
routes.py	قابل پیش نمایش	7.9 KB

پیش نمایش فایل

app/routes.py

from __future__ import annotations

import json
from datetime import datetime, timezone
from uuid import uuid4

from flask import Blueprint, current_app, flash, redirect, render_template, request, url_for

from .models import TopupOrder, Wallet, db
from .payment_gateway import PayexaGatewayClient

web_bp = Blueprint("web", __name__)


def _gateway_client() -> PayexaGatewayClient:
    return PayexaGatewayClient(
        base_url=current_app.config["PAYEXA_BASE_URL"],
        api_key=current_app.config["PAYEXA_API_KEY"],
        request_endpoint=current_app.config["PAYEXA_REQUEST_ENDPOINT"],
        verify_endpoint=current_app.config["PAYEXA_VERIFY_ENDPOINT"],
        timeout_seconds=current_app.config["PAYEXA_TIMEOUT_SECONDS"],
    )


def _single_wallet() -> Wallet:
    wallet = Wallet.query.first()
    if wallet is None:
        wallet = Wallet(owner_name="Demo User", balance=0)
        db.session.add(wallet)
        db.session.commit()
    return wallet


@web_bp.get("/")
def index():
    wallet = _single_wallet()
    orders = TopupOrder.query.order_by(TopupOrder.created_at.desc()).limit(15).all()
    return render_template(
        "index.html",
        wallet=wallet,
        orders=orders,
        badge_script_url=current_app.config.get("PAYEXA_BADGE_SCRIPT_URL", ""),
    )


@web_bp.post("/wallet/charge")
def wallet_charge():
    wallet = _single_wallet()

    raw_amount = (request.form.get("amount") or "").strip()
    if not raw_amount.isdigit() or int(raw_amount) <= 0:
        flash("مبلغ نامعتبر است.", "error")
        return redirect(url_for("web.index"))

    amount = int(raw_amount)
    order_ref = f"TOPUP-{uuid4().hex[:12].upper()}"

    order = TopupOrder(
        order_ref=order_ref,
        amount=amount,
        wallet_id=wallet.id,
        status="pending",
    )
    db.session.add(order)
    db.session.commit()

    callback_url = request.url_root.rstrip("/") + current_app.config["PAYEXA_CALLBACK_PATH"]
    gateway = _gateway_client()
    response = gateway.request_payment(amount=amount, callback_url=callback_url, order_ref=order_ref)

    if not response.ok:
        order.status = "request_failed"
        order.verify_response = json.dumps(response.data, ensure_ascii=False)
        db.session.commit()
        flash(
            (
                "خطا در ایجاد پرداخت. "
                f"url={response.request_url} status={response.status_code} "
                f"detail={response.error or response.data}"
            ),
            "error",
        )
        return redirect(url_for("web.index"))

    authority = (response.data.get("authority") or "").strip()
    gateway_order_id = (response.data.get("order_id") or "").strip()
    amount_unique = response.data.get("amount_unique")

    if not authority:
        order.status = "request_invalid_response"
        order.verify_response = json.dumps(response.data, ensure_ascii=False)
        db.session.commit()
        flash("پاسخ درگاه authority نداشت.", "error")
        return redirect(url_for("web.index"))

    order.status = "requested"
    order.authority = authority
    order.gateway_order_id = gateway_order_id or None
    if amount_unique is not None:
        # In this gateway, verify token can be the unique charged amount.
        order.gateway_token = str(amount_unique)
    order.verify_response = json.dumps(response.data, ensure_ascii=False)
    db.session.commit()

    return redirect(gateway.build_start_pay_url(authority, current_app.config["PAYEXA_STARTPAY_PATH"]))


@web_bp.route("/payments/callback", methods=["GET", "POST"])
def payment_callback():
    wallet = _single_wallet()

    payload = _collect_callback_payload()
    callback_status = (payload.get("status") or "").strip().upper()
    authority = (payload.get("authority") or "").strip()
    gateway_order_id = (payload.get("order_id") or "").strip()
    token = str(payload.get("token") or "").strip()

    if callback_status and callback_status != "OK":
        return render_template(
            "payment_result.html",
            ok=False,
            title="پرداخت ناموفق یا لغو شده",
            message=f"وضعیت بازگشتی درگاه: {callback_status}",
            wallet=wallet,
            payload=payload,
        )

    order = None
    if gateway_order_id:
        order = TopupOrder.query.filter_by(gateway_order_id=gateway_order_id).first()
    if order is None and authority:
        order = TopupOrder.query.filter_by(authority=authority).first()

    if order is None:
        return render_template(
            "payment_result.html",
            ok=False,
            title="سفارش پیدا نشد",
            message="سفارش مرتبط با callback یافت نشد.",
            wallet=wallet,
            payload=payload,
        )

    if not gateway_order_id:
        gateway_order_id = (order.gateway_order_id or "").strip()
    if not token:
        token = str(order.gateway_token or "").strip()

    order.callback_payload = json.dumps(payload, ensure_ascii=False)
    if token:
        order.gateway_token = token
    db.session.commit()

    if order.credited:
        return render_template(
            "payment_result.html",
            ok=True,
            title="پرداخت قبلا ثبت شده",
            message="این سفارش قبلا وریفای و به کیف پول اضافه شده است.",
            wallet=wallet,
            payload=payload,
        )

    if not gateway_order_id or not token:
        order.status = "callback_invalid"
        db.session.commit()
        return render_template(
            "payment_result.html",
            ok=False,
            title="callback ناقص",
            message="order_id یا token در callback موجود نیست.",
            wallet=wallet,
            payload=payload,
        )

    verify_response = _gateway_client().verify_payment(order_id=gateway_order_id, token=token)
    order.verify_status_code = verify_response.status_code
    order.verify_response = json.dumps(verify_response.data, ensure_ascii=False)

    if verify_response.status_code == 200 and not order.credited:
        order.status = "verified"
        order.credited = True
        order.paid_at = datetime.now(timezone.utc)
        wallet.balance += order.amount
        db.session.commit()
        return render_template(
            "payment_result.html",
            ok=True,
            title="شارژ موفق کیف پول",
            message=f"مبلغ {order.amount:,} با موفقیت به کیف پول اضافه شد.",
            wallet=wallet,
            payload=verify_response.data,
        )

    if verify_response.status_code == 201:
        order.status = "already_verified"
        db.session.commit()
        return render_template(
            "payment_result.html",
            ok=True,
            title="قبلا وریفای شده",
            message="این پرداخت قبلا وریفای شده است و دوباره افزایش موجودی انجام نشد.",
            wallet=wallet,
            payload=verify_response.data,
        )

    order.status = "verify_failed"
    db.session.commit()
    return render_template(
        "payment_result.html",
        ok=False,
        title="وریفای ناموفق",
        message=f"در وریفای خطا رخ داد. status={verify_response.status_code}",
        wallet=wallet,
        payload=verify_response.data,
    )


@web_bp.get("/orders/<order_ref>")
def order_status(order_ref: str):
    wallet = _single_wallet()
    order = TopupOrder.query.filter_by(order_ref=order_ref).first_or_404()
    return render_template("order_status.html", wallet=wallet, order=order)


def _collect_callback_payload() -> dict:
    if request.is_json:
        body = request.get_json(silent=True)
        if isinstance(body, dict):
            return body

    if request.form:
        return request.form.to_dict(flat=True)

    if request.args:
        return request.args.to_dict(flat=True)

    return {}

README / توضیحات

منبع: README.md

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:

Create top-up order in local database
Request payment from Payexa (/v1/payment/request)
Redirect user to Payexa start pay page
Receive callback in your app
Verify payment with Payexa (/v1/payment/verify)
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:

Do not commit .env or any real API key.
Keep only placeholder values in .env.example.
Set production PAYEXA_BASE_URL to https://pay.pexn.ir.
Use a public HTTPS domain for callback URL.
Disable debug mode in production runtime.
Replace any localhost-only scripts (for example trust badge scripts) with public URL.
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 است.

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

ايجاد سفارش شارژ در پايگاه داده محلي
ارسال درخواست پرداخت به Payexa (/v1/payment/request)
هدايت کاربر به صفحه پرداخت Payexa
دريافت callback در اپليکيشن
وريفاي تراکنش با Payexa (/v1/payment/verify)
افزايش موجودي کيف پول فقط بعد از وريفاي موفق (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، افزايش موجودي مجدد انجام ندهيد.

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

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