مستندات فنی پارسا پی

بخش ۱

معرفی کلی

پارسا پی (ParsaPay) یک درگاه پرداخت هوشمند و یکپارچه است که به کسب‌وکارها امکان می‌دهد بدون نیاز به اخذ اینماد، کد مالیاتی و ثبت‌نام در شاپرک، از طریق ۸ درگاه پرداخت معتبر، پول دریافت کنند.

مشخصه	توضیح
نام محصول	پارسا پی (ParsaPay)
نوع	درگاه پرداخت یکپارچه (Payment Gateway Aggregator)
پلتفرم	PHP 7.4+
ذخیره‌سازی	JSON (قابل ارتقا به MySQL)
درگاه‌های پشتیبانی	زیبال، زرین‌پال، پاسارگاد، آسان پرداخت، سامان، سپهر، سامان مستقیم، سپهر مستقیم
سقف هر تراکنش	۹۹ میلیون تومان (قابل افزایش با تقسیم خودکار)
زمان فعال‌سازی	۱۰ دقیقه
نیازمندی‌ها	PHP، cURL، دسترسی به API درگاه‌ها
لینک دسترسی	parsapay.parsakart.com

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

بخش ۲

ویژگی‌ها

#	ویژگی	توضیح
۱	بدون اینماد	نیازی به اخذ نماد اعتماد الکترونیکی نیست
۲	بدون کد مالیاتی	عدم نیاز به ثبت‌نام مالیاتی
۳	بدون شاپرک	عدم نیاز به ثبت‌نام در شاپرک
۴	فعال‌سازی ۱۰ دقیقه	راه‌اندازی سریع بدون کاغذبازی
۵	۸ درگاه معتبر	پشتیبانی از درگاه‌های مختلف با سقف ۹۹ میلیون تومان
۶	کارمزد از خریدار	فروشنده هیچ هزینه‌ای پرداخت نمی‌کند
۷	انتخاب هوشمند درگاه	سیستم خودکار بهترین درگاه را انتخاب می‌کند
۸	تقسیم خودکار تراکنش	پرداخت‌های بزرگ به چند مرحله تقسیم می‌شوند
۹	لینک اختصاصی	هر کاربر لینک منحصربه‌فرد دریافت می‌کند
۱۰	داشبورد مدیریت	مشاهده و مدیریت تمام تراکنش‌ها

بخش ۳

معماری سیستم

┌─────────────────────────────────────────────────────────────────┐ │ ParsaPay Core │ ├─────────────────────────────────────────────────────────────────┤ │ لایه‌ی نمایش (Frontend) │ │ ├── index.php - ورود نام کاربری │ │ ├── pay.php - پرداخت اختصاصی هر کاربر │ │ └── dashboard.php - مدیریت تراکنش‌ها │ ├─────────────────────────────────────────────────────────────────┤ │ لایه‌ی منطق کسب‌وکار (Business Logic) │ │ ├── SmartRouter.php - انتخاب هوشمند درگاه │ │ ├── PaymentHandler.php - پردازش پرداخت │ │ └── TransactionManager.php - مدیریت تراکنش‌ها │ ├─────────────────────────────────────────────────────────────────┤ │ لایه‌ی اتصال به درگاه‌ها (Gateway Layer) │ │ ├── Zibal.php - زیبال │ │ ├── Zarinpal.php - زرین‌پال │ │ ├── Pasargad.php - پاسارگاد │ │ ├── AsanPardakht.php - آسان پرداخت │ │ ├── Saman.php - سامان │ │ ├── Sepehr.php - سپهر │ │ ├── SamanDirect.php - سامان مستقیم │ │ └── SepehrDirect.php - سپهر مستقیم │ ├─────────────────────────────────────────────────────────────────┤ │ لایه‌ی ذخیره‌سازی (Storage) │ │ ├── users.json - اطلاعات کاربران │ │ └── transactions.json - اطلاعات تراکنش‌ها │ └─────────────────────────────────────────────────────────────────┘

بخش ۴

ساختار فایل‌ها

parsapay/
├── index.php              # صفحه اصلی (ورود نام کاربری)
├── pay.php                # صفحه پرداخت اختصاصی هر کاربر
├── dashboard.php          # داشبورد مدیریت تراکنش‌ها
├── callback.php           # دریافت پاسخ از درگاه‌ها
├── SmartRouter.php        # انتخاب هوشمند درگاه
├── PaymentHandler.php     # پردازش پرداخت
├── config.php             # تنظیمات درگاه‌ها
├── users.json             # ذخیره اطلاعات کاربران (خودکار ساخته می‌شود)
├── transactions.json      # ذخیره تراکنش‌ها (خودکار ساخته می‌شود)
├── settings.json          # تنظیمات درگاه (merchant, terminal, callback)
├── .htaccess              # تنظیمات مسیرهای کوتاه
└── README.md              # راهنمای نصب و استفاده
        

بخش ۵

پیش‌نیازها و نصب

پیش‌نیازها

نیازمندی	توضیح
PHP 7.4 یا بالاتر	نسخه‌های پایین‌تر ممکن است با خطا مواجه شوند
پسوند cURL	برای اتصال به API درگاه‌ها ضروری است
پسوند JSON	برای پردازش داده‌های JSON
دسترسی نوشتن به پوشه	برای ایجاد فایل‌های users.json و transactions.json
دسترسی به اینترنت	برای اتصال به API درگاه‌ها
دامنه با SSL (HTTPS)	درگاه‌های پرداخت به SSL نیاز دارند

مراحل نصب

# ۱. ایجاد پوشه در ریشه سایت
mkdir /public_html/parsapay

# ۲. کپی فایل‌ها به پوشه
cp *.php /public_html/parsapay/
cp *.json /public_html/parsapay/
cp .htaccess /public_html/parsapay/

# ۳. تنظیم دسترسی‌ها
chmod 755 /public_html/parsapay/*.php
chmod 666 /public_html/parsapay/*.json

# ۴. تنظیم .htaccess برای لینک‌های کوتاه
# (محتوا در بخش بعدی)

# ۵. تست نصب
# باز کردن آدرس: https://parsakart.com/parsapay/
        

تنظیمات .htaccess:

RewriteEngine On
RewriteRule ^p/([a-zA-Z0-9_-]+)$ pay.php?user=$1 [L,QSA]

بخش ۶

تنظیمات درگاه‌ها

فایل config.php

$GATEWAYS = [
    [
        'id'       => 'zibal',
        'name'     => 'زیبال',
        'merchant' => 'YOUR_MERCHANT_ID',
        'terminal' => 'YOUR_TERMINAL_ID',
        'priority' => 1,
        'active'   => true,
        'max_amount' => 99000000,
        'fee_percent' => 0.5
    ],
    // ... سایر درگاه‌ها (۸ عدد)
];

define('CALLBACK_URL', 'https://parsakart.com/parsapay/callback.php');
define('TRANSACTIONS_FILE', __DIR__ . '/transactions.json');
define('USERS_FILE', __DIR__ . '/users.json');
        

فیلدهای تنظیمات درگاه

فیلد	نوع	توضیح
`id`	string	شناسه یکتای درگاه (برای استفاده در کد)
`name`	string	نام نمایشی درگاه
`merchant`	string	مرچنت کد دریافتی از درگاه
`terminal`	string	ترمینال آیدی (برای درگاه‌هایی که نیاز دارند)
`priority`	int	اولویت انتخاب (۱ بالاترین)
`active`	bool	وضعیت فعال/غیرفعال
`max_amount`	int	سقف هر تراکنش به تومان
`fee_percent`	float	درصد کارمزد درگاه

بخش ۷

جریان پرداخت

┌─────────┐ │ کاربر 1 │ (فروشنده) لینک پرداخت را دریافت می‌کند └────┬────┘ │ ▼ ┌─────────┐ │ کاربر 2 │ (مشتری) لینک را باز می‌کند └────┬────┘ │ ▼ ┌─────────┐ │ pay.php │ مبلغ را وارد کرده و پرداخت را شروع می‌کند └────┬────┘ │ ▼ ┌─────────────┐ │ SmartRouter │ بهترین درگاه را انتخاب می‌کند └────┬────────┘ │ ▼ ┌─────────────┐ │ درگاه پرداخت│ کاربر به صفحه درگاه هدایت می‌شود └────┬────────┘ │ ▼ ┌─────────────┐ │ callback │ درگاه پاسخ را به callback.php ارسال می‌کند └────┬────────┘ │ ▼ ┌─────────────┐ │ Verify │ سیستم پرداخت را تأیید می‌کند └────┬────────┘ │ ▼ ┌─────────────┐ │ Dashboard │ وضعیت تراکنش به‌روز می‌شود └─────────────┘

بخش ۸

API‌ها و Endpoints

۱. ایجاد لینک پرداخت

GET https://parsakart.com/parsapay/index.php?user={username}

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

POST https://parsakart.com/parsapay/pay.php?user={username}

// پارامترها (Body - فرم)
amount       = 1000000   // مبلغ به تومان (حداقل ۱۰۰۰)
description   = "توضیحات پرداخت" // اختیاری
        

۳. کالبک پرداخت

GET https://parsakart.com/parsapay/callback.php?transaction={id}

۴. تأیید پرداخت

POST https://parsakart.com/parsapay/verify.php

// پارامترها (JSON)
{
    "trackId": "1234567890",
    "transactionId": "PAY-123456"
}
        

پاسخ موفق:
{"status":"success","refId":"REF-123456","amount":1000000}

پاسخ خطا:
{"status":"error","message":"خطا در اتصال به درگاه"}

بخش ۹

انتخاب هوشمند درگاه

معیارهای انتخاب

معیار	اولویت	توضیح
وضعیت	۱	درگاه باید فعال باشد (active: true)
سقف مبلغ	۲	مبلغ تراکنش نباید از max_amount بیشتر باشد
کارمزد	۳	درگاهی با کمترین کارمزد اولویت دارد
اولویت	۴	در صورت برابری سایر معیارها، priority بالاتر انتخاب می‌شود
پشتیبان	۵	در صورت خطای درگاه اصلی، به‌صورت خودکار به درگاه بعدی سوئیچ می‌شود

function selectGateway($amount) {
    global $GATEWAYS;
    $selected = null;
    $bestScore = -1;

    foreach ($GATEWAYS as $gateway) {
        if (!$gateway['active']) continue;
        if ($amount > $gateway['max_amount']) continue;

        $score = (100 - $gateway['fee_percent']) + $gateway['priority'];

        if ($score > $bestScore) {
            $bestScore = $score;
            $selected = $gateway;
        }
    }

    return $selected;
}
        

بخش ۱۰

تقسیم خودکار تراکنش‌ها

مثال تقسیم

مبلغ کل	تعداد مراحل	توزیع
۵۰,۰۰۰,۰۰۰	۱	۱ × ۵۰ میلیون
۱۵۰,۰۰۰,۰۰۰	۲	۹۹ میلیون + ۵۱ میلیون
۴۵۰,۰۰۰,۰۰۰	۵	۹۹ × ۴ + ۵۴ میلیون

function splitPayment($amount) {
    $maxPerGateway = 99000000;
    $parts = [];
    $remaining = $amount;

    while ($remaining > 0) {
        $partAmount = min($remaining, $maxPerGateway);
        $gateway = selectGateway($partAmount);
        if (!$gateway) return null;
        $parts[] = [
            'gateway' => $gateway,
            'amount'  => $partAmount,
            'step'    => count($parts) + 1
        ];
        $remaining -= $partAmount;
    }

    return $parts;
}
        

بخش ۱۱

امنیت

لایه	روش	توضیح
احراز هویت	توکن یکبارمصرف	هر تراکنش دارای توکن منحصربه‌فرد است
رمزنگاری	AES-256	اطلاعات حساس رمزنگاری می‌شوند
کالبک	امضای دیجیتال	صحت درخواست‌های بازگشت تأیید می‌شود
CSRF	توکن فرم	جلوگیری از حملات CSRF
محدودیت تلاش	قفل ۱۵ دقیقه‌ای	پس از ۵ تلاش ناموفق
SSL	HTTPS	تمام ارتباطات از طریق HTTPS انجام می‌شود

function generateToken($length = 32) {
    return bin2hex(random_bytes($length));
}

function verifyToken($token, $storedToken) {
    return hash_equals($storedToken, $token);
}
        

بخش ۱۲

دیتابیس و ذخیره‌سازی

users.json

[
    {
        "id": "USR-1767890123456",
        "username": "mohammadparsa",
        "name": "محمد پارسا زارع",
        "phone": "09123456789",
        "email": "info@parsakart.com",
        "link": "https://parsakart.com/p/mohammadparsa",
        "created_at": "2026-08-14 10:00:00"
    }
]
        

transactions.json

[
    {
        "id": "PAY-1767890123456-12345",
        "username": "mohammadparsa",
        "amount": 5000000,
        "description": "پرداخت سفارش",
        "gateway": "zibal",
        "trackId": "1234567890",
        "status": "completed",
        "refId": "REF-123456",
        "created_at": "2026-08-14 10:05:00",
        "updated_at": "2026-08-14 10:06:00"
    }
]
        

ارتقا به MySQL

-- جدول users
CREATE TABLE users (
    id VARCHAR(50) PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(100),
    phone VARCHAR(20),
    email VARCHAR(100),
    link VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- جدول transactions
CREATE TABLE transactions (
    id VARCHAR(50) PRIMARY KEY,
    username VARCHAR(50),
    amount INT,
    description TEXT,
    gateway VARCHAR(50),
    trackId VARCHAR(100),
    status ENUM('pending','completed','failed'),
    refId VARCHAR(100),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
        

بخش ۱۳

عیب‌یابی

خطاهای رایج

خطا	علت	راه‌حل
`callBackUrl is required`	آدرس بازگشت ارسال نشده	بررسی callback در config.php و تنظیمات درگاه
`Merchant not found`	مرچنت کد اشتباه	بررسی merchant در config.php
`Transaction not found`	شناسه تراکنش نامعتبر	بررسی transactionId در callback.php
`Amount exceeds limit`	مبلغ بالای ۹۹ میلیون	فعال‌سازی تقسیم خودکار یا استفاده از درگاه دیگر
`Curl error`	مشکل در اتصال به API	بررسی دسترسی اینترنت و فیلتر شدن API
`404 Not Found`	فایل وجود ندارد	بررسی مسیر فایل‌ها و وجود .htaccess
`500 Internal Server Error`	خطای سرور	بررسی لاگ‌های PHP و تنظیمات سرور

چک‌لیست عیب‌یابی

#	چک‌لیست	وضعیت
۱	آیا فایل‌ها در مسیر درست قرار دارند؟	☐
۲	آیا دسترسی نوشتن به پوشه وجود دارد؟	☐
۳	آیا تنظیمات settings.json صحیح است؟	☐
۴	آیا callback_url در درگاه تنظیم شده است؟	☐
۵	آیا مرچنت کد و ترمینال آیدی صحیح است؟	☐
۶	آیا PHP cURL فعال است؟	☐
۷	آیا SSL (HTTPS) فعال است؟	☐
۸	آیا .htaccess به‌درستی تنظیم شده است؟	☐

// فعال‌سازی نمایش خطاها برای دیباگ
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

// لاگ‌گیری
function debugLog($message) {
    file_put_contents(__DIR__ . '/debug.log', date('Y-m-d H:i:s') . ' - ' . $message . "\n", FILE_APPEND);
}
        

بخش ۱۴

سوالات متداول

آیا پارسا پی نیاز به اینماد دارد؟
خیر. پارسا پی از درگاه‌های موجود استفاده می‌کند و نیازی به اخذ اینماد جداگانه ندارد.

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

آیا پارسا پی نیاز به ثبت‌نام در شاپرک دارد؟
خیر. پارسا پی خودش با درگاه‌ها کار می‌کند و نیازی به تنظیمات شاپرک ندارید.

زمان فعال‌سازی پارسا پی چقدر است؟
حداکثر ۱۰ دقیقه. فقط کافی است فایل‌ها را روی هاست خود کپی کنید و تنظیمات درگاه را وارد کنید.

کارمزد پارسا پی چقدر است؟
۱۵٪ از مبلغ خریدار. فروشنده هیچ هزینه‌ای پرداخت نمی‌کند.

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

آیا می‌توانم درگاه‌های جدید اضافه کنم؟
بله. با افزودن یک آرایه جدید به $GATEWAYS در فایل config.php.

آیا پارسا پی از NFC پشتیبانی می‌کند؟
بله. پارسا پی با کارت‌های NFC پارسا کارت یکپارچه شده است.

بخش ۱۵

پشتیبانی

روش	اطلاعات
ایمیل	info@parsakart.com
تلفن	09112655904
وب‌سایت	parsakart.com
پشتیبانی آنلاین	support.parsakart.com

لینک‌های مفید

لینک	توضیح
parsapay.parsakart.com	صفحه معرفی پارسا پی
parsakart.com/parsapay	صفحه اصلی پارسا پی
parsakart.com/parsapay/dashboard.php	داشبورد مدیریت
parsakart.com/parsapay/callback.php	آدرس بازگشت (Callback)

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

ParsaPay – از ایران برای جهان 🌍

پارسا پی

📋 فهرست مطالب