hasan-22 / torob_pay

dev-main 2026-10-09 14:08 UTC

Requires

• php: ^8.2

MIT

• HASSAN-22

• payment
• laravel
• torobpay

Published on Packagist.org on 2026-10-09 14:12 UTC

README

💳 درگاه پرداخت ترب‌پی برای Laravel

یکپارچه‌سازی ساده برای ساخت، تأیید، تسویه و لغو پرداخت‌های ترب‌پی در پروژه‌های Laravel

شروع سریع · پیکربندی · جریان پرداخت · مرجع API · امنیت

✨ امکانات

این بسته امکانات موردنیاز برای اتصال فروشگاه Laravel به ترب‌پی را فراهم می‌کند. برای ارتباط HTTP از Laravel HTTP Client و برای نگهداری وضعیت تراکنش از پایگاه‌داده برنامه استفاده می‌شود.

🛒 ساخت پرداخت ارسال جزئیات مشتری و سبد خرید به ترب‌پی

✅ تأیید و تسویه بررسی سمت سرور و ثبت نتیجه پرداخت

↩️ لغو پرداخت لغو از طریق API و به‌روزرسانی وضعیت محلی

پیش‌نیازها

• PHP نسخه 8.2 یا بالاتر.
• برنامه Laravel با پایگاه‌داده پیکربندی‌شده.
• دسترسی شبکه سرور به API ترب‌پی و اعتبارنامه‌های معتبر درگاه.

🚀 نصب و شروع سریع

نصب بسته

composer require hasan-22/torob_pay

Laravel به‌صورت خودکار Service Provider را کشف می‌کند. فایل تنظیمات را در صورت نیاز منتشر کنید و migration بسته را اجرا کنید:

php artisan vendor:publish --tag=torobpay-config
php artisan migrate

در نصب محلی، بسته را به‌عنوان repository از نوع path در Composer برنامه میزبان معرفی کنید. namespace کلاس‌های بسته TorobPay\ است.

⚙️ پیکربندی

مقادیر دسترسی را در فایل .env برنامه Laravel تنظیم کنید:

متغیر محیطی	کلید تنظیمات	پیش‌فرض	توضیح
TOROBPAY_URL	torobpay.url	https://cpg.torobpay.com	آدرس پایه API ترب‌پی
TOROBPAY_CLIENT_ID	torobpay.client_id	خالی	شناسه کلاینت برای Basic Authorization
TOROBPAY_CLIENT_SECRET	torobpay.client_secret	خالی	رمز کلاینت برای Basic Authorization
TOROBPAY_USERNAME	torobpay.username	خالی	نام کاربری endpoint دریافت توکن
TOROBPAY_PASSWORD	torobpay.password	خالی	رمز عبور endpoint دریافت توکن

فایل تنظیمات منتشرشده در config/torobpay.php قرار می‌گیرد. اگر config cache فعال است، پس از تغییر .env آن را مطابق فرایند استقرار برنامه بازسازی کنید.

🔐 مهم: اعتبارنامه‌ها را در مخزن کد، log یا پاسخ HTTP قرار ندهید. از متغیرهای محیطی امن استفاده کنید.

🔄 جریان پرداخت

1. اقلام سبد را با addCartItem() اضافه کنید.
2. اطلاعات کلی سبد را با addList() تنظیم کنید.
3. با request() پرداخت را ایجاد و کاربر را به مقدار data.url هدایت کنید.
4. پارامترهای برگشتی در callback را به verify() بدهید.
5. پس از موفقیت، سفارش و مبلغ را با اطلاعات داخلی فروشگاه تطبیق دهید؛ سپس سفارش را نهایی کنید.

ایجاد پرداخت

use TorobPay\Facades\TorobPay;

// اقلام را از سفارش معتبر سمت سرور تهیه کنید.
$result = TorobPay::addCartItem(
    id: 123,
    name: 'محصول نمونه',
    count: 1,
    amount: 200000,
    category: 'general',
)->addCartItem(
    id: 456,
    name: 'محصول نمونه ۲',
  count: 1,
    amount: 500000,
    category: 'general',
)->addList(
    cartId: 'cart-456',
    amount: 700000,
    tax: 0,
    shippingAmount: 0,
)->request(
    amount: 700000,
    orderId: 456,
    mobile: '09120000000',
    callback: route('torobpay.callback'),
);

if ($result['status'] !== 'success') {
    return back()->withErrors(['payment' => 'ایجاد درخواست پرداخت ناموفق بود.']);
}

return redirect()->away($result['data']['url']);

دریافت callback و تأیید پرداخت

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

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use TorobPay\Facades\TorobPay;

Route::match(['get', 'post'], '/payments/torobpay/callback', function (Request $request) {
    $result = TorobPay::verify($request->all());

    if ($result['status'] !== 'success') {
        return response()->json(['message' => 'تأیید پرداخت ناموفق بود.'], 422);
    }

    $orderId = $result['data']['order_id'];
    $amount = $result['data']['amount'];

    // سفارش را از پایگاه‌داده خود بارگذاری کنید و مبلغ/مالکیت آن را تطبیق دهید.
    // سپس آن را به‌صورت idempotent نهایی کنید.

    return response()->json(['message' => 'پرداخت با موفقیت تأیید شد.']);
})->name('torobpay.callback');

نکته: callback به‌تنهایی مدرک پرداخت موفق نیست. verify() پرداخت را از سمت سرور بررسی می‌کند؛ مبلغ، مالکیت و وضعیت سفارش را نیز با داده‌های داخلی خود تطبیق دهید.

📚 مرجع API

addCartItem(int $id, string $name, int $count, int $amount, string $category = 'other', string $commissionType = '0'): static

یک محصول به سبد جاری اضافه می‌کند و همان نمونه را برای زنجیره‌کردن فراخوانی‌ها برمی‌گرداند.

• id: شناسه محصول در فروشگاه.
• name: نام محصول.
• count: تعداد واحدها.
• amount: مبلغ محصول با واحد مورد انتظار API ترب‌پی.
• category: دسته محصول؛ پیش‌فرض other.
• commissionType: نوع کمیسیون؛ پیش‌فرض رشته 0.

addList(string $cartId, int $amount, int $tax, int $shippingAmount, bool $isTaxIncluded = false, bool $isShipmentIncluded = false): static

خلاصه سبد را از اقلامی که تا آن لحظه با addCartItem() افزوده شده‌اند می‌سازد.

• cartId: شناسه سبد فروشگاه.
• amount: مبلغ کل سبد.
• tax: مبلغ مالیات.
• shippingAmount: مبلغ ارسال.
• isTaxIncluded و isShipmentIncluded: مشخص می‌کنند مالیات و هزینه ارسال در مبلغ کل لحاظ شده‌اند یا خیر.

این متد را پس از افزودن اقلام و پیش از request() فراخوانی کنید. بسته مبلغ را تبدیل نمی‌کند؛ واحد مبلغ باید با قرارداد حساب ترب‌پی و مبالغ برنامه شما یکسان باشد.

request(int $amount, int $orderId, string $mobile, string $callback, string $paymentMethod = 'ONLINE_CREDIT', ?string $address = null, ?string $postalCode = null, ?string $fullName = null, ?string $province = null, ?string $city = null): array

درخواست پرداخت می‌سازد. مبلغ باید مثبت باشد و سبد باید پیش‌تر با addList() تنظیم شده باشد. در صورت موفقیت، توکن پرداخت و توکن دسترسی ذخیره و وضعیت اولیه pending ثبت می‌شود. مقادیر اختیاری مشتری که null باشند به رشته خالی تبدیل می‌شوند.

verify(array $response): array

callback را بررسی و پرداخت pending را از طریق API ترب‌پی verify و settle می‌کند. callback باید state برابر OK و transactionId غیرخالی داشته باشد. در موفقیت وضعیت محلی به completed تغییر می‌کند. پرداخت تکمیل‌شده یا پرداختی با وضعیت غیر از pending دوباره تأیید نمی‌شود.

اگر نتیجه تسویه نامشخص بود، وضعیت را از پنل یا API ترب‌پی بررسی کنید و از تحویل سفارش یا ایجاد پرداخت جایگزین بدون تطبیق خودداری کنید.

cancel(string $paymentToken): array

پرداخت را با payment token لغو و وضعیت محلی را به canceled تغییر می‌دهد. در پیاده‌سازی فعلی فقط پرداختی با وضعیت محلی completed قابل لغو است. این شرط را با قرارداد ترب‌پی و جریان کسب‌وکار خود تطبیق دهید.

📦 قالب کامل پاسخ‌ها

در تمام متدها ابتدا status را بررسی کنید. نمونه‌های زیر، ساختار کامل پاسخ موفق هر متد را نشان می‌دهند؛ مقادیر token، URL و شناسه‌ها صرفاً نمونه هستند.

پاسخ موفق request()

[
  'status' => 'success',
  'data' => [
    'url' => 'https://cpg.torobpay.com/payment/example',
    'payment_token' => 'payment-token-example',
    'order_id' => 456, // شناسه سفارش فروشگاه، به‌صورت integer
    'transaction_id' => '12345678_456', // شناسه داخلی ساخته‌شده برای ترب‌پی
  ],
]

کاربر را به مقدار data.url هدایت کنید. برای پیگیری تراکنش می‌توانید payment_token و transaction_id را از همین پاسخ بخوانید.

پاسخ موفق verify()

[
  'status' => 'success',
  'data' => [
    'order_id' => '456', // شناسه سفارش؛ در این پاسخ string است
    'payment_token' => 'payment-token-example',
    'amount' => 700000, // مقدار callback؛ اگر ارسال نشده باشد null است
    'transaction_id' => 'gateway-transaction-example', // ممکن است null باشد
  ],
]

در این پاسخ، order_id از شناسه تراکنش داخلی استخراج می‌شود؛ مقدار amount از callback و transaction_id از پاسخ تسویه ترب‌پی می‌آید. بسته نوع این مقادیر را تبدیل نمی‌کند.

پاسخ موفق cancel()

[
  'status' => 'success',
  'data' => [
    'order_id' => '12345678_456', // شناسه ذخیره‌شده در رکورد پرداخت
  ],
]

توجه کنید که order_id در پاسخ cancel() شناسه کامل تراکنش ذخیره‌شده است و با شناسه سفارش اصلی که request() برمی‌گرداند تفاوت دارد.

قالب پاسخ خطا

[
  'status' => 'error',
  'data' => [
    'error' => 'شرح خطا',
    'data' => null, // یا پاسخ/داده تشخیصی در دسترس
  ],
]

مقدار data.data در پاسخ خطا ممکن است null یا داده خام پاسخ درگاه باشد. متن خطاها برای نمایش مستقیم به کاربر تضمین نشده است؛ پیام مناسب برنامه خود را نمایش دهید.

🗃️ ذخیره‌سازی و وضعیت‌ها

migration بسته جدول torobpay_payment_tokens را ایجاد می‌کند:

• payment_token: توکن پرداخت ترب‌پی.
• access_token: توکن دسترسی عملیات بعدی.
• order_id: شناسه تراکنش تولیدشده توسط بسته.
• status: یکی از pending، completed، failed یا canceled.
• created_at و updated_at: زمان ایجاد و به‌روزرسانی رکورد.

verify() در صورت ناموفق‌بودن پاسخ endpoint تأیید، وضعیت را failed می‌کند؛ تسویه موفق وضعیت را completed می‌کند. cancel() در صورت موفقیت وضعیت را canceled می‌کند. توکن‌ها در این migration رمزگذاری نشده‌اند؛ دسترسی پایگاه‌داده و نسخه‌های پشتیبان را محدود و سیاست نگهداری مناسبی تعریف کنید.

🩺 خطاها و پایش

• خطاهای HTTP با status: error و جزئیات موجود در data.data بازگردانده می‌شوند.
• خطاهای اتصال و برخی وضعیت‌های نامشخص در Laravel Log ثبت می‌شوند؛ logها را بدون اطلاعات حساس پایش کنید.
• در timeout یا نتیجه نامشخص تأیید/تسویه، تراکنش را از سمت ترب‌پی تطبیق دهید.
• اگر settle سمت درگاه موفق شود اما ثبت وضعیت محلی شکست بخورد، نتیجه درگاه و رکورد پایگاه‌داده را با فرایند تطبیق اصلاح کنید.

🔒 امنیت و ملاحظات عملیاتی

• عملیات verify() را فقط در سرور انجام دهید و به ورودی مرورگر اعتماد نکنید.
• پیش از تحویل کالا یا خدمت، شناسه سفارش، مالکیت و مبلغ را با اطلاعات پایگاه‌داده برنامه تطبیق دهید.
• از شناسه‌های سفارش قابل حدس به‌عنوان مجوز دسترسی استفاده نکنید.
• client_secret، گذرواژه و access token را در خروجی، log یا کد سمت کاربر قرار ندهید.
• اقلام سبد در نمونه کلاس نگهداری می‌شوند و خودکار پاک نمی‌شوند. Facade نمونه singleton برمی‌گرداند؛ در workerهای طولانی‌عمر، استفاده مجدد از همان نمونه می‌تواند اقلام قبلی را به پرداخت بعدی اضافه کند. برای هر پرداخت مستقل، نمونه تازه بسازید.
• مهلت درخواست‌های HTTP بیست ثانیه است و در پیاده‌سازی فعلی retry خودکار وجود ندارد.

📄 مجوز

این بسته تحت مجوز MIT منتشر شده است.