پرش به مطلب اصلی

Laravel Cashier (OrcaRail)

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

پکیج Composer: orcarail/cashier-orcarail
Namespace: OrcaRail\Cashier
مخزن: github.com/OrcaRail/sdks-laravel-cashier

این پکیج روی SDK رسمی PHP یعنی orcarail/orcarail-php ساخته شده است.

پیش‌نیازها​

  • PHP 8.1+
  • لاراول ۱۰، ۱۱ یا ۱۲

نصب​

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

محیط​

متغیرتوضیح
ORCARAIL_API_KEYکلید API (ak_…)
ORCARAIL_API_SECRETsecret API (sk_…)
ORCARAIL_WEBHOOK_SECRETsecret HMAC وب‌هوک
ORCARAIL_BASE_URLپیش‌فرض https://api.orcarail.com/api/v1
ORCARAIL_PAY_URLپیش‌فرض https://pay.orcarail.com
ORCARAIL_CURRENCYکد ارز پیش‌فرض (usd)
ORCARAIL_WEBHOOK_PATHپیش‌فرض orcarail/webhook

کلیدهای live در برابر sandbox​

در فایل‌های .env محلی و staging از کلیدهای سازمان sandbox (ak_test_… / sk_test_…، فقط شبکه‌های آزمایشی) و در محیط عملیاتی از کلیدهای live (ak_live_…) استفاده کنید. payloadهای وب‌هوک برای رویدادهای sandbox مقدار livemode برابر false دارند.

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

helperهای محلی (مبتنی بر جدول subscriptions که با وب‌هوک‌ها همگام می‌ماند):

  • $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 صفحه پرداخت میزبانی‌شده را بگیرد.

وب‌هوک‌ها​

Cashier مسیر POST /orcarail/webhook را ثبت می‌کند و هدر x-webhook-signature (HMAC-SHA256) را بررسی می‌کند. این آدرس را روی کلید API اورکاریل خود تنظیم کنید.

رویدادهای چرخه عمر اشتراک ردیف‌های محلی را به‌روز می‌کنند. برای اثرهای مخصوص اپ خود به WebhookReceived و WebhookHandled گوش دهید.