PayPing for PHP & Laravel (API v3)

پکیج PHP برای درگاه پرداخت PayPing API v3 — بدون وابستگی به فریم‌ورک، با پشتیبانی کامل از Laravel.

• ✅ پرداخت و تأیید پرداخت (v3)
• ✅ فاکتور، مشتری، محصول، کوپن، تسهیلات (BNPL)، برداشت، گزارش و ...
• ✅ Facade و Service Provider آماده برای Laravel 9 / 10 / 11 / 12
• ✅ بدون وابستگی HTTP اضافه (cURL خالص)

نصب

composer require swanflutter/payping-master

مستندات کامل

مستندات هر سرویس به صورت جداگانه در پوشه docs/ نوشته شده است:

سرویس	مستندات
پرداخت (v3) — ایجاد، تأیید، تسهیم، برگشت وجه	docs/payment.md
فاکتور (v2) — شامل فاکتور سریع و زمان‌بندی	docs/invoice.md
مشتریان	docs/customer.md
محصولات	docs/product.md
کوپن تخفیف	docs/coupon.md
لینک پرداخت ثابت	docs/permalink.md
برداشت وجه	docs/withdraw.md
گزارش تراکنش‌ها	docs/report.md
استعلام‌های بانکی، هویتی و خدماتی	docs/inquiry.md
خرید اقساطی (BNPL)	docs/bnpl.md
آپلود فایل	docs/upload.md
راهنمای Laravel	docs/laravel.md
مدیریت خطا و تنظیمات پیشرفته	docs/exceptions.md

تاریخچه تغییرات: CHANGELOG.md

استفاده (PHP خالص)

ایجاد پرداخت

use SwanFlutter\PayPing\PayPing;

$payping = new PayPing($_ENV['PAYPING_TOKEN']);

$response = $payping->payment()->create([
    'amount'       => 72000,                                // تومان (حداقل ۱۰۰۰)
    'returnUrl'    => 'https://example.com/callback.php',
    'clientRefId'  => 'ORDER-1234567890',                   // شناسه سفارش شما (اختیاری)
    'description'  => 'خرید اشتراک شش ماهه',                 // اختیاری
    'payerName'    => 'علی محمدی',                           // اختیاری
    'payerIdentity'=> '09123456789',                         // موبایل یا ایمیل (اختیاری)
]);

$paymentCode = $response['paymentCode'];  // ⚠️ در دیتابیس ذخیره کنید

// redirect کاربر به درگاه
header('Location: ' . $payping->payment()->getStartUrl($paymentCode));
exit;

تأیید پرداخت (در callback)

PayPing v3 پس از بازگشت کاربر، اطلاعات پرداخت را به‌صورت POST به returnUrl شما می‌فرستد. طبق فرمت فعلی v3، فیلدهای اصلی status، errorCode و یک فیلد data هستند که جزئیات پرداخت به‌صورت JSON داخل آن قرار می‌گیرد. از CallbackParser استفاده کنید تا هر دو فرمت (جدید و قدیمی) به‌درستی خوانده شوند:

use SwanFlutter\PayPing\CallbackParser;
use SwanFlutter\PayPing\PayPing;
use SwanFlutter\PayPing\PayPingException;

// $_POST نمونه فرمت v3:
// ["status" => "1", "errorCode" => "", "data" => '{"clientRefId":"...","paymentCode":"...","paymentRefId":2166036136,"amount":1000,...}']

$callback = CallbackParser::fromGlobals();

if (!CallbackParser::isSuccessful($callback)) {
    die('پرداخت لغو شد');
}

$clientRefId  = $callback['clientRefId'];   // ✅ درست خوانده می‌شود
$paymentCode  = $callback['paymentCode'];
$paymentRefId = (int)$callback['paymentRefId'];

$payping = new PayPing($_ENV['PAYPING_TOKEN']);

try {
    // مبلغ باید دقیقاً همان مبلغ اولیه باشد
    $result = $payping->payment()->verify([
        'amount'       => 72000,
        'paymentCode'  => $paymentCode,
        'paymentRefId' => $paymentRefId,
    ]);

    // ✅ پرداخت تأیید شد — سفارش را فعال کنید
    echo 'پرداخت موفق! کد پیگیری: ' . $paymentRefId;
} catch (PayPingException $e) {
    echo 'تأیید ناموفق: ' . $e->getMessage();
}

استفاده در Laravel

تنظیمات

php artisan vendor:publish --tag=payping-config

فایل .env:

PAYPING_TOKEN=your-token-here
PAYPING_TEST_MODE=false

ایجاد پرداخت

use SwanFlutter\PayPing\PayPing;

Route::post('/pay', function (Request $request) {
    $response = app(PayPing::class)->payment()->create([
        'amount'      => 72000,
        'returnUrl'   => route('payment.callback'),
        'clientRefId' => (string)$request->order_id,
    ]);

    return redirect()->away(
        app(PayPing::class)->payment()->getStartUrl($response['paymentCode'])
    );
});

تأیید پرداخت

Route::post('/payment/callback', function (Request $request) {
    if ((int)$request->input('status') !== 1) {
        abort(400, 'پرداخت لغو شد');
    }

    $result = app(PayPing::class)->payment()->verify([
        'amount'       => 72000,
        'paymentCode'  => $request->input('paymentCode'),
        'paymentRefId' => (int)$request->input('paymentRefId'),
    ]);

    return 'پرداخت موفق!';
});

استفاده با Facade

use SwanFlutter\PayPing\Laravel\Facades\PayPing;

PayPing::payment()->create([...]);
PayPing::invoice()->create([...]);
PayPing::coupon()->list([...]);

API Reference

PayPing

سرویس‌ها به صورت lazy-load ساخته می‌شوند:

متد	سرویس
$payping->payment()	پرداخت
$payping->invoice()	فاکتور
$payping->customer()	مشتریان
$payping->product()	محصولات
$payping->report()	گزارش‌ها
$payping->inquiry()	استعلام
$payping->withdraw()	برداشت
$payping->bnpl()	خرید اعتباری (BNPL)
$payping->permalink()	لینک پرداخت ثابت
$payping->coupon()	کوپن
$payping->upload()	آپلود فایل

سازنده:

new PayPing(string $token, bool $testMode = false, int $timeout = 45)

PaymentService

متد	توضیح
create(array $data)	ایجاد پرداخت (POST /v3/pay)
verify(array $data)	تأیید پرداخت (POST /v3/pay/verify)
getStartUrl(string $paymentCode)	آدرس درگاه برای redirect
delete(string $paymentCode)	حذف پرداخت
reverse(array $data)	برگشت وجه
share(array $data) / createShared(array $data)	پرداخت اشتراکی
unblock(array $data)	رفع مسدودی
paid($refId, $paymentCode) / paidNotify($refId, $paymentCode)	ارسال اطلاعات پرداخت به پذیرنده (معمولاً به صورت خودکار توسط PayPing فراخوانی می‌شود)

UploadService

$payping->upload()->profilePic('/path/photo.jpg');          // عکس پروفایل (JPG, PNG, JPEG)
$payping->upload()->item('/path/photo.jpg');                // عکس آیتم مالی (JPG, PNG, JPEG)
$payping->upload()->invoiceAttachment('/path/attachment.pdf'); // ضمیمه فاکتور

PayPingException

متد	توضیح
getMessage()	پیام خطا (شامل جزئیات PayPing)
getCode()	کد HTTP
getErrors()	آرایه خطاهای metaData.errors

تست

composer install
composer test

لایسنس

MIT — Swan Flutter