إنتقل إلى المحتوى الرئيسي

Laravel Cashier (OrcaRail)

Cashier OrcaRail حزمة Laravel توفر API على نمط Cashier لمدفوعات العملات المستقرة في OrcaRail: حالة اشتراكات محلية، وتوجيه إلى صفحة الدفع المستضافة، ومزامنة عبر webhooks موقّعة.

حزمة Composer: orcarail/cashier-orcarail
النطاق (Namespace): OrcaRail\Cashier
المستودع: github.com/OrcaRail/sdks-laravel-cashier

تغلّف الحزمة PHP SDK الرسمية orcarail/orcarail-php.

المتطلبات​

  • PHP 8.1+
  • Laravel 10 أو 11 أو 12

التثبيت​

composer require orcarail/cashier-orcarail
php artisan vendor:publish --tag=orcarail-cashier-config
php artisan migrate

البيئة​

المتغيرالوصف
ORCARAIL_API_KEYمفتاح API (ak_…)
ORCARAIL_API_SECRETسر API (sk_…)
ORCARAIL_WEBHOOK_SECRETسر HMAC للـ webhook
ORCARAIL_BASE_URLالافتراضي https://api.orcarail.com/api/v1
ORCARAIL_PAY_URLالافتراضي https://pay.orcarail.com
ORCARAIL_CURRENCYرمز العملة الافتراضي (usd)
ORCARAIL_WEBHOOK_PATHالافتراضي orcarail/webhook

مفاتيح الإنتاج مقابل مفاتيح الـ sandbox​

استخدم مفاتيح مؤسسة sandbox (ak_test_… / sk_test_…، شبكات تجريبية فقط) في ملفات .env المحلية وبيئة الاختبار المرحلي، والمفاتيح الحية (ak_live_…) في الإنتاج. تحمل حمولات الـ webhook قيمة livemode: false لأحداث الـ sandbox.

الـ trait المسمى Billable​

use OrcaRail\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

الاشتراكات​

$checkout = $user->newSubscription('default', 'price_xxx')
    ->trialDays(14)
    ->create(['payer_email' => $user->email]);

return $checkout; // redirects to latest_payment_link.link when present

أدوات مساعدة محلية (مدعومة بجدول subscriptions الذي تبقيه الـ webhooks متزامنًا):

  • $user->subscribed()
  • $user->onTrial()
  • $user->subscription()
  • $subscription->cancel() / resume() / pastDue() / paused()

تستخدم الفترات التجريبية معاملات الإنشاء trial_period_days (أو trial_end) في OrcaRail.

المدفوعات الفردية​

return $user->checkout('price_xxx', [
    'return_url' => url('/orders/return'),
]);

تنشئ Cashier ‏Payment Intent، وعند الحاجة تؤكده للحصول على next_action.redirect_to_url.url لصفحة الدفع المستضافة.

الـ webhooks​

تسجّل Cashier المسار POST /orcarail/webhook وتتحقق من ترويسة x-webhook-signature (HMAC-SHA256). اضبط هذا الرابط على مفتاح API الخاص بك في OrcaRail.

تحدّث أحداث دورة حياة الاشتراك الصفوف المحلية. استمع إلى WebhookReceived وWebhookHandled للتأثيرات الخاصة بتطبيقك.