صندوقدار لاراول (استریپ)

• معرفی
• ارتقاء صندوقدار
• نصب و راه اندازی
• پیکربندی
  • مدل قابل پرداخت
  • کلیدهای API
  • پیکربندی ارز
  • پیکربندی مالیاتی
  • ورود به سیستم
  • استفاده از مدل های سفارشی
• شروع سریع
  • فروش محصولات
  • فروش اشتراک
• مشتریان
  • بازیابی مشتریان
  • ایجاد مشتریان
  • به روز رسانی مشتریان
  • موازنه
  • شناسه های مالیاتی
  • همگام سازی داده های مشتری با Stripe
  • پورتال صورتحساب
• روش های پرداخت
  • ذخیره سازی روش های پرداخت
  • بازیابی روش های پرداخت
  • وجود روش پرداخت
  • به روز رسانی روش پرداخت پیش فرض
  • اضافه کردن روش های پرداخت
  • حذف روش های پرداخت
• اشتراک ها
  • ایجاد اشتراک
  • بررسی وضعیت اشتراک
  • تغییر قیمت ها
  • مقدار اشتراک
  • اشتراک با چندین محصول
  • اشتراک های متعدد
  • صورتحساب اندازه گیری شده
  • مالیات اشتراک
  • تاریخ لنگر اشتراک
  • لغو اشتراک ها
  • از سرگیری اشتراک ها
• آزمایشات اشتراک
  • با روش پرداخت از قبل
  • بدون روش پرداخت از قبل
  • تمدید آزمایشات
• رسیدگی به قلاب های راه راه
  • تعریف مدیریت رویداد Webhook
  • تأیید امضاهای Webhook
• شارژ تک
  • شارژ ساده
  • شارژ با فاکتور
  • ایجاد اهداف پرداخت
  • هزینه های بازپرداخت
• وارسی
  • بررسی های محصول
  • تسویه حساب تک شارژ
  • پرداخت های اشتراک
  • جمع آوری شناسه های مالیاتی
  • تسویه حساب مهمان
• فاکتورها
  • بازیابی فاکتورها
  • فاکتورهای آینده
  • پیش نمایش فاکتورهای اشتراک
  • تولید پی دی اف فاکتور
• رسیدگی به پرداخت های ناموفق
  • تایید پرداخت ها
• احراز هویت قوی مشتری (SCA)
  • پرداخت هایی که نیاز به تایید اضافی دارند
  • اطلاعیه های پرداخت خارج از جلسه
• Stripe SDK
• آزمایش کردن

معرفی

Laravel Cashier Stripe یک رابط رسا و روان برای خدمات صورتحساب اشتراک Stripe فراهم می کند. تقریباً تمام کدهای صورت‌حساب اشتراک دیگ بخار را که از نوشتن آن می‌ترسید مدیریت می‌کند. علاوه بر مدیریت اشتراک اولیه، Cashier می‌تواند کوپن‌ها، تعویض اشتراک، «مقدار» اشتراک، دوره‌های مهلت لغو، و حتی فایل‌های PDF فاکتور تولید کند.

ارتقاء صندوقدار

هنگام ارتقاء به نسخه جدید Cashier، مهم است که راهنمای ارتقا را به دقت مرور کنید .

برای جلوگیری از شکستن تغییرات، Cashier از یک نسخه API ثابت Stripe استفاده می کند. Cashier 15 از نسخه Stripe API استفاده می کند 2023-10-16 . نسخه Stripe API در نسخه‌های کوچک به‌روزرسانی می‌شود تا از ویژگی‌ها و بهبودهای جدید Stripe استفاده کند.

نصب و راه اندازی

ابتدا بسته Cashier را برای Stripe با استفاده از مدیریت بسته Composer نصب کنید:

composer require laravel/cashier

پس از نصب بسته، مهاجرت های Cashier را با استفاده از vendor:publish دستور Artisan منتشر کنید:

php artisan vendor:publish --tag="cashier-migrations"

سپس پایگاه داده خود را انتقال دهید:

php artisan migrate

مهاجرت صندوقدار چندین ستون به users جدول شما اضافه می کند. آنها همچنین یک subscriptions جدول جدید برای نگهداری تمام اشتراک های مشتری شما و یک subscription_items جدول برای اشتراک ها با چند قیمت ایجاد می کنند.

در صورت تمایل می توانید فایل پیکربندی Cashier را نیز با استفاده از vendor:publish دستور Artisan منتشر کنید:

php artisan vendor:publish --tag="cashier-config"

در نهایت، برای اطمینان از اینکه Cashier به درستی همه رویدادهای Stripe را مدیریت می‌کند، به یاد داشته باشید که کنترل وب‌هوک Cashier را پیکربندی کنید .

Stripe توصیه می کند که هر ستونی که برای ذخیره شناسه های Stripe استفاده می شود باید به حروف بزرگ و کوچک حساس باشد. بنابراین، باید اطمینان حاصل کنید که هنگام استفاده از MySQL، ترکیب ستون برای stripe_id ستون تنظیم شده است utf8_bin . اطلاعات بیشتر در مورد این را می توان در مستندات Stripe یافت .

پیکربندی

مدل قابل پرداخت

قبل از استفاده از Cashier، این Billable ویژگی را به تعریف مدل قابل پرداخت خود اضافه کنید. به طور معمول، این مدل خواهد بود App\Models\User . این ویژگی روش‌های مختلفی را ارائه می‌کند تا به شما امکان می‌دهد کارهای رایج صورت‌حساب را انجام دهید، مانند ایجاد اشتراک، اعمال کوپن، و به‌روزرسانی اطلاعات روش پرداخت:

use Laravel\Cashier\Billable;
 
class User extends Authenticatable
{
    use Billable;
}

صندوقدار فرض می کند مدل قابل پرداخت شما همان کلاسی است App\Models\User که با لاراول ارسال می شود. اگر می خواهید این را تغییر دهید، می توانید مدل دیگری را از طریق useCustomerModel روش مشخص کنید. این متد معمولاً باید در boot متد کلاس شما فراخوانی شود AppServiceProvider :

use App\Models\Cashier\User;
use Laravel\Cashier\Cashier;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Cashier::useCustomerModel(User::class);
}

اگر از مدلی غیر از مدل ارائه شده لاراول استفاده می‌کنید App\Models\User ، باید مهاجرت‌های Cashier ارائه شده را منتشر کرده و تغییر دهید تا با نام جدول مدل جایگزین شما مطابقت داشته باشد.

کلیدهای API

در مرحله بعد، باید کلیدهای Stripe API خود را در .env فایل برنامه خود پیکربندی کنید. می توانید کلیدهای Stripe API خود را از کنترل پنل Stripe بازیابی کنید:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret

باید اطمینان حاصل کنید که STRIPE_WEBHOOK_SECRET متغیر محیطی در فایل برنامه شما تعریف شده است .env ، زیرا این متغیر برای اطمینان از اینکه وب هوک های ورودی واقعاً از Stripe هستند استفاده می شود.

پیکربندی ارز

واحد پول نقد پیش فرض دلار آمریکا (USD) است. می‌توانید با تنظیم CASHIER_CURRENCY متغیر محیطی در فایل برنامه، واحد پول پیش‌فرض را تغییر دهید .env :

CASHIER_CURRENCY=eur

علاوه بر پیکربندی واحد پول Cashier، می‌توانید محلی را نیز تعیین کنید که هنگام قالب‌بندی مقادیر پول برای نمایش در فاکتورها استفاده شود. در داخل، Cashier از کلاس PHP NumberFormatter برای تنظیم محلی ارز استفاده می کند:

CASHIER_CURRENCY_LOCALE=nl_BE

به منظور استفاده از زبان‌های محلی به غیر از en ، مطمئن شوید که ext-intl پسوند PHP روی سرور شما نصب و پیکربندی شده است.

پیکربندی مالیاتی

به لطف Stripe Tax ، امکان محاسبه خودکار مالیات برای همه فاکتورهای تولید شده توسط Stripe وجود دارد. می توانید محاسبه خودکار مالیات را با فراخوانی calculateTaxes روش موجود در boot متد کلاس برنامه خود فعال کنید App\Providers\AppServiceProvider :

use Laravel\Cashier\Cashier;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Cashier::calculateTaxes();
}

هنگامی که محاسبه مالیات فعال شد، هر اشتراک جدید و هر فاکتور یکباره ای که ایجاد می شود، محاسبه مالیات خودکار دریافت می کند.

برای اینکه این ویژگی به درستی کار کند، جزئیات صورت‌حساب مشتری، مانند نام، آدرس و شناسه مالیاتی مشتری، باید با Stripe همگام‌سازی شود. برای انجام این کار می‌توانید از روش‌های همگام‌سازی داده‌های مشتری و شناسه مالیاتی ارائه شده توسط Cashier استفاده کنید.

هیچ مالیاتی برای شارژ تک یا پرداخت تک شارژ محاسبه نمی شود .

ورود به سیستم

Cashier به شما امکان می دهد کانال ورود به سیستم را برای استفاده در هنگام ثبت خطاهای کشنده Stripe مشخص کنید. می‌توانید کانال گزارش را با تعریف CASHIER_LOGGER متغیر محیطی در فایل برنامه خود مشخص کنید .env :

CASHIER_LOGGER=stack

استثناهایی که توسط فراخوانی های API به Stripe ایجاد می شوند از طریق کانال گزارش پیش فرض برنامه شما ثبت می شوند.

استفاده از مدل های سفارشی

شما آزاد هستید که مدل های مورد استفاده داخلی توسط صندوقدار را با تعریف مدل خود و گسترش مدل صندوقدار مربوطه گسترش دهید:

use Laravel\Cashier\Subscription as CashierSubscription;
 
class Subscription extends CashierSubscription
{
    // ...
}

پس از تعریف مدل خود، ممکن است به Cashier دستور دهید که از مدل سفارشی شما از طریق Laravel\Cashier\Cashier کلاس استفاده کند. به طور معمول، شما باید مدل های سفارشی خود را در boot روش کلاس برنامه خود به Cashier اطلاع دهید App\Providers\AppServiceProvider :

use App\Models\Cashier\Subscription;
use App\Models\Cashier\SubscriptionItem;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useSubscriptionItemModel(SubscriptionItem::class);
}

شروع سریع

فروش محصولات

قبل از استفاده از Stripe Checkout، باید محصولاتی را با قیمت های ثابت در داشبورد Stripe خود تعریف کنید. علاوه بر این، باید مدیریت وب هوک Cashier را پیکربندی کنید .

ارائه صورتحساب محصول و اشتراک از طریق برنامه شما می تواند ترسناک باشد. با این حال، به لطف Cashier و Stripe Checkout ، می توانید به راحتی یکپارچه سازی پرداخت مدرن و قوی ایجاد کنید.

برای دریافت هزینه از مشتریان برای محصولات غیر تکراری و تک شارژ، از Cashier استفاده می کنیم تا مشتریان را به Stripe Checkout هدایت کنیم، جایی که آنها جزئیات پرداخت خود را ارائه می دهند و خرید خود را تأیید می کنند. هنگامی که پرداخت از طریق Checkout انجام شد، مشتری به آدرس اینترنتی موفقیت آمیز مورد نظر شما در برنامه شما هدایت می شود:

use Illuminate\Http\Request;
 
Route::get('/checkout', function (Request $request) {
    $stripePriceId = 'price_deluxe_album';
 
    $quantity = 1;
 
    return $request->user()->checkout([$stripePriceId => $quantity], [
        'success_url' => route('checkout-success'),
        'cancel_url' => route('checkout-cancel'),
    ]);
})->name('checkout');
 
Route::view('checkout.success')->name('checkout-success');
Route::view('checkout.cancel')->name('checkout-cancel');

همانطور که در مثال بالا می بینید، ما از checkout روش ارائه شده توسط Cashier برای هدایت مشتری به Stripe Checkout برای یک "شناسه قیمت" استفاده می کنیم. هنگام استفاده از Stripe، "قیمت ها" به قیمت های تعریف شده برای محصولات خاص اشاره دارد .

در صورت لزوم، این checkout روش به طور خودکار یک مشتری در Stripe ایجاد می کند و رکورد مشتری Stripe را به کاربر مربوطه در پایگاه داده برنامه شما متصل می کند. پس از اتمام جلسه تسویه حساب، مشتری به صفحه موفقیت یا لغو اختصاصی هدایت می شود که در آن می توانید یک پیام اطلاعاتی برای مشتری نمایش دهید.

ارائه متا داده به Stripe Checkout

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

برای انجام این کار، ممکن است آرایه ای از متد ارائه metadata دهید checkout . بیایید تصور کنیم Order زمانی که کاربر فرآیند پرداخت را شروع می‌کند، در برنامه ما یک معلق ایجاد می‌شود. به یاد داشته باشید، مدل‌های Cart و Order در این مثال گویا هستند و توسط Cashier ارائه نشده‌اند. شما آزاد هستید که این مفاهیم را بر اساس نیازهای برنامه خود پیاده سازی کنید:

use App\Models\Cart;
use App\Models\Order;
use Illuminate\Http\Request;
 
Route::get('/cart/{cart}/checkout', function (Request $request, Cart $cart) {
    $order = Order::create([
        'cart_id' => $cart->id,
        'price_ids' => $cart->price_ids,
        'status' => 'incomplete',
    ]);
 
    return $request->user()->checkout($order->price_ids, [
        'success_url' => route('checkout-success').'?session_id={CHECKOUT_SESSION_ID}',
        'cancel_url' => route('checkout-cancel'),
        'metadata' => ['order_id' => $order->id],
    ]);
})->name('checkout');

همانطور که در مثال بالا می بینید، زمانی که کاربر فرآیند پرداخت را شروع می کند، ما همه شناسه های قیمت Stripe مربوط به سبد خرید/سفارش را به روش ارائه می دهیم checkout . البته، اپلیکیشن شما مسئول مرتبط کردن این موارد با «سبد خرید» یا سفارشی است که مشتری آنها را اضافه می‌کند. همچنین شناسه سفارش را از طریق metadata آرایه به جلسه Stripe Checkout ارائه می کنیم. در نهایت CHECKOUT_SESSION_ID متغیر قالب را به مسیر موفقیت Checkout اضافه کرده ایم . هنگامی که Stripe مشتریان را به برنامه شما هدایت می کند، این متغیر الگو به طور خودکار با شناسه جلسه Checkout پر می شود.

در مرحله بعد، بیایید مسیر موفقیت Checkout را بسازیم. این مسیری است که کاربران پس از تکمیل خرید از طریق Stripe Checkout به آن هدایت خواهند شد. در این مسیر، می‌توانیم شناسه جلسه Stripe Checkout و نمونه مربوط به Stripe Checkout را بازیابی کنیم تا بتوانیم به داده‌های متا ارائه شده خود دسترسی داشته باشیم و سفارش مشتری خود را بر این اساس به‌روزرسانی کنیم:

use App\Models\Order;
use Illuminate\Http\Request;
use Laravel\Cashier\Cashier;
 
Route::get('/checkout/success', function (Request $request) {
    $sessionId = $request->get('session_id');
 
    if ($sessionId === null) {
        return;
    }
 
    $session = Cashier::stripe()->checkout->sessions->retrieve($sessionId);
 
    if ($session->payment_status !== 'paid') {
        return;
    }
 
    $orderId = $session['metadata']['order_id'] ?? null;
 
    $order = Order::findOrFail($orderId);
 
    $order->update(['status' => 'completed']);
 
    return view('checkout-success', ['order' => $order]);
})->name('checkout-success');

لطفاً برای اطلاعات بیشتر در مورد داده های موجود در شی جلسه Checkout به مستندات Stripe مراجعه کنید .

فروش اشتراک

قبل از استفاده از Stripe Checkout، باید محصولاتی را با قیمت های ثابت در داشبورد Stripe خود تعریف کنید. علاوه بر این، باید مدیریت وب هوک Cashier را پیکربندی کنید .

ارائه صورتحساب محصول و اشتراک از طریق برنامه شما می تواند ترسناک باشد. با این حال، به لطف Cashier و Stripe Checkout ، می توانید به راحتی یکپارچه سازی پرداخت مدرن و قوی ایجاد کنید.

برای یادگیری نحوه فروش اشتراک با استفاده از Cashier و Stripe Checkout، اجازه دهید سناریوی ساده یک سرویس اشتراک با یک برنامه اولیه ماهانه ( price_basic_monthly ) و سالانه ( price_basic_yearly ) را در نظر بگیریم. این دو قیمت را می توان تحت یک محصول "پایه" ( pro_basic ) در داشبورد Stripe ما گروه بندی کرد. علاوه بر این، خدمات اشتراک ما ممکن است یک طرح متخصص به عنوان ارائه دهد pro_expert .

ابتدا، بیایید کشف کنیم که چگونه یک مشتری می تواند در خدمات ما مشترک شود. البته، می توانید تصور کنید که مشتری ممکن است روی دکمه "اشتراک" برای طرح پایه در صفحه قیمت برنامه ما کلیک کند. این دکمه یا پیوند باید کاربر را به مسیر لاراول هدایت کند که جلسه Stripe Checkout را برای برنامه انتخابی او ایجاد می کند:

use Illuminate\Http\Request;
 
Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_basic_monthly')
        ->trialDays(5)
        ->allowPromotionCodes()
        ->checkout([
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

همانطور که در مثال بالا می بینید، ما مشتری را به جلسه Stripe Checkout هدایت می کنیم که به آنها امکان می دهد در طرح اولیه ما مشترک شوند. پس از تسویه حساب یا لغو موفقیت آمیز، مشتری به آدرس اینترنتی که به روش ارائه کرده ایم هدایت می شود checkout . برای اینکه بدانیم اشتراک آنها واقعاً چه زمانی شروع شده است (از آنجایی که پردازش برخی از روش های پرداخت به چند ثانیه نیاز دارد)، همچنین باید مدیریت وب هوک Cashier را نیز پیکربندی کنیم .

اکنون که مشتریان می توانند اشتراک را شروع کنند، باید بخش های خاصی از برنامه خود را محدود کنیم تا فقط کاربران مشترک بتوانند به آنها دسترسی داشته باشند. البته، ما همیشه می‌توانیم وضعیت اشتراک فعلی کاربر را از طریق subscribed روش ارائه شده توسط ویژگی Cashier تعیین کنیم Billable :

@if ($user->subscribed())
    <p>You are subscribed.</p>
@endif

ما حتی می توانیم به راحتی تعیین کنیم که آیا کاربر مشترک محصول یا قیمت خاصی است یا خیر:

@if ($user->subscribedToProduct('pro_basic'))
    <p>You are subscribed to our Basic product.</p>
@endif
 
@if ($user->subscribedToPrice('price_basic_monthly'))
    <p>You are subscribed to our monthly Basic plan.</p>
@endif

ساخت میان افزار مشترک

برای راحتی، ممکن است بخواهید یک میان افزار ایجاد کنید که تعیین می کند آیا درخواست دریافتی از یک کاربر مشترک است یا خیر. هنگامی که این میان افزار تعریف شد، می توانید به راحتی آن را به مسیری اختصاص دهید تا از دسترسی کاربرانی که مشترک نیستند به مسیر جلوگیری کنید:

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
 
class Subscribed
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()?->subscribed()) {
            // Redirect user to billing page and ask them to subscribe...
            return redirect('/billing');
        }
 
        return $next($request);
    }
}

هنگامی که میان افزار تعریف شد، می توانید آن را به یک مسیر اختصاص دهید:

use App\Http\Middleware\Subscribed;
 
Route::get('/dashboard', function () {
    // ...
})->middleware([Subscribed::class]);

به مشتریان اجازه می دهد تا برنامه صورتحساب خود را مدیریت کنند

البته ممکن است مشتریان بخواهند طرح اشتراک خود را به محصول یا «سطح» دیگری تغییر دهند. ساده‌ترین راه برای اجازه دادن به این امر، هدایت مشتریان به پورتال صورت‌حساب مشتری Stripe است که یک رابط کاربری میزبانی شده را ارائه می‌دهد که به مشتریان امکان می‌دهد فاکتورها را دانلود کنند، روش پرداخت خود را به‌روزرسانی کنند، و طرح‌های اشتراک را تغییر دهند.

ابتدا پیوند یا دکمه ای را در برنامه خود تعریف کنید که کاربران را به مسیر لاراول هدایت می کند و ما از آن برای راه اندازی جلسه پورتال صورتحساب استفاده خواهیم کرد:

<a href="{{ route('billing') }}">
    Billing
</a>

در مرحله بعد، بیایید مسیری را تعریف کنیم که جلسه پورتال صورت‌حساب مشتری Stripe را آغاز می‌کند و کاربر را به پورتال هدایت می‌کند. این redirectToBillingPortal روش نشانی اینترنتی را می‌پذیرد که کاربران باید هنگام خروج از پورتال به آن بازگردانده شوند:

use Illuminate\Http\Request;
 
Route::get('/billing', function (Request $request) {
    return $request->user()->redirectToBillingPortal(route('dashboard'));
})->middleware(['auth'])->name('billing');

تا زمانی که مدیریت وب هوک Cashier را پیکربندی کرده باشید، Cashier به طور خودکار جداول پایگاه داده مربوط به Cashier برنامه شما را با بازرسی وبکهک های ورودی از Stripe همگام نگه می دارد. بنابراین، برای مثال، هنگامی که کاربر اشتراک خود را از طریق پورتال صورت‌حساب مشتری Stripe لغو می‌کند، Cashier وب هوک مربوطه را دریافت می‌کند و اشتراک را به عنوان "لغو شده" در پایگاه داده برنامه شما علامت‌گذاری می‌کند.

مشتریان

بازیابی مشتریان

با استفاده از این روش می‌توانید یک مشتری را با شناسه Stripe او بازیابی کنید Cashier::findBillable . این روش نمونه ای از مدل قابل پرداخت را برمی گرداند:

use Laravel\Cashier\Cashier;
 
$user = Cashier::findBillable($stripeId);

ایجاد مشتریان

گاهی اوقات، ممکن است بخواهید بدون شروع اشتراک، یک مشتری Stripe ایجاد کنید. شما می توانید این کار را با استفاده از createAsStripeCustomer روش زیر انجام دهید:

$stripeCustomer = $user->createAsStripeCustomer();

هنگامی که مشتری در Stripe ایجاد شد، می توانید در تاریخ بعد اشتراک خود را شروع کنید. می‌توانید یک $options آرایه اختیاری برای ارسال هر پارامتر ایجاد مشتری اضافی که توسط Stripe API پشتیبانی می‌شود ارائه کنید :

$stripeCustomer = $user->createAsStripeCustomer($options);

asStripeCustomer اگر می‌خواهید شی مشتری Stripe را برای یک مدل قابل صورت‌حساب برگردانید، می‌توانید از روش استفاده کنید :

$stripeCustomer = $user->asStripeCustomer();

createOrGetStripeCustomer اگر بخواهید شی مشتری Stripe را برای یک مدل قابل صورت‌حساب معین بازیابی کنید، اما مطمئن نیستید که آیا مدل قابل صورت‌حساب قبلاً یک مشتری در Stripe است، این روش ممکن است استفاده شود. اگر مشتری از قبل وجود نداشته باشد، این روش یک مشتری جدید در Stripe ایجاد می کند:

$stripeCustomer = $user->createOrGetStripeCustomer();

به روز رسانی مشتریان

گاهی اوقات، ممکن است بخواهید مشتری Stripe را مستقیماً با اطلاعات اضافی به روز کنید. شما می توانید این کار را با استفاده از updateStripeCustomer روش انجام دهید. این روش آرایه ای از گزینه های به روز رسانی مشتری را می پذیرد که توسط Stripe API پشتیبانی می شوند :

$stripeCustomer = $user->updateStripeCustomer($options);

موازنه

Stripe به شما این امکان را می دهد که "موجودی" مشتری را اعتبار یا بدهی کنید. بعداً این موجودی در فاکتورهای جدید بستانکار یا بدهکار خواهد شد. برای بررسی موجودی کل مشتری می توانید از روشی استفاده کنید balance که در مدل قابل پرداخت شما موجود است. این balance روش یک نمایش رشته فرمت شده از موجودی در واحد پول مشتری را برمی گرداند:

$balance = $user->balance();

برای اعتبار دادن به موجودی مشتری، ممکن است مقداری برای creditBalance روش ارائه دهید. در صورت تمایل می توانید توضیحاتی نیز ارائه دهید:

$user->creditBalance(500, 'Premium customer top-up.');

ارائه یک مقدار به debitBalance روش، موجودی مشتری را بدهکار می کند:

$user->debitBalance(300, 'Bad usage penalty.');

این applyBalance روش تراکنش های موجودی جدید مشتری را برای مشتری ایجاد می کند. می توانید این سوابق تراکنش را با استفاده از balanceTransactions روشی که ممکن است برای ارائه گزارشی از اعتبارات و بدهی ها برای بررسی مشتری مفید باشد، بازیابی کنید:

// Retrieve all transactions...
$transactions = $user->balanceTransactions();
 
foreach ($transactions as $transaction) {
    // Transaction amount...
    $amount = $transaction->amount(); // $2.31
 
    // Retrieve the related invoice when available...
    $invoice = $transaction->invoice();
}

شناسه های مالیاتی

صندوقدار یک راه آسان برای مدیریت شناسه مالیاتی مشتری ارائه می دهد. برای مثال، این taxIds روش ممکن است برای بازیابی همه شناسه‌های مالیاتی که به‌عنوان مجموعه به مشتری اختصاص داده شده‌اند استفاده شود:

$taxIds = $user->taxIds();

همچنین می‌توانید یک شناسه مالیاتی خاص را برای یک مشتری با شناسه آن بازیابی کنید:

$taxId = $user->findTaxId('txi_belgium');

می توانید با ارائه یک نوع و مقدار معتبر برای createTaxId روش، یک شناسه مالیاتی جدید ایجاد کنید:

$taxId = $user->createTaxId('eu_vat', 'BE0123456789');

این createTaxId روش بلافاصله شناسه مالیات بر ارزش افزوده را به حساب مشتری اضافه می کند. تایید شناسه های مالیات بر ارزش افزوده نیز توسط Stripe انجام می شود . با این حال، این یک فرآیند ناهمزمان است. می‌توانید با اشتراک در customer.tax_id.updated رویداد webhook و بررسی پارامتر VAT IDها verification از به‌روزرسانی‌های تأیید مطلع شوید . برای اطلاعات بیشتر در مورد مدیریت وب هوک، لطفاً به مستندات مربوط به تعریف کنترل کننده های وب هوک مراجعه کنید .

می توانید شناسه مالیاتی را با استفاده از deleteTaxId روش زیر حذف کنید:

$user->deleteTaxId('txi_belgium');

همگام سازی داده های مشتری با Stripe

به طور معمول، زمانی که کاربران برنامه شما نام، آدرس ایمیل یا سایر اطلاعاتی را که توسط Stripe نیز ذخیره شده است به روز می کنند، باید Stripe را از به روز رسانی ها مطلع کنید. با انجام این کار، کپی Stripe از اطلاعات با برنامه شما همگام خواهد شد.

برای خودکارسازی این کار، ممکن است شنونده رویدادی را در مدل قابل پرداخت خود تعریف کنید که به رویداد مدل واکنش نشان می‌دهد updated . سپس، در شنونده رویداد خود، می توانید syncStripeCustomerDetails متد را در مدل فراخوانی کنید:

use App\Models\User;
use function Illuminate\Events\queueable;
 
/**
 * The "booted" method of the model.
 */
protected static function booted(): void
{
    static::updated(queueable(function (User $customer) {
        if ($customer->hasStripeId()) {
            $customer->syncStripeCustomerDetails();
        }
    }));
}

اکنون، هر بار که مدل مشتری شما به‌روزرسانی می‌شود، اطلاعات آن با Stripe همگام‌سازی می‌شود. برای راحتی، Cashier به طور خودکار اطلاعات مشتری شما را با Stripe در ایجاد اولیه مشتری همگام می کند.

می‌توانید ستون‌هایی را که برای همگام‌سازی اطلاعات مشتری با Stripe استفاده می‌شوند، با نادیده گرفتن انواع روش‌های ارائه شده توسط Cashier سفارشی کنید. برای مثال، می‌توانید stripeName روش سفارشی‌سازی ویژگی‌ای را که باید به‌عنوان «نام» مشتری در نظر گرفته شود، در زمانی که Cashier اطلاعات مشتری را با Stripe همگام‌سازی می‌کند، لغو کنید:

/**
 * Get the customer name that should be synced to Stripe.
 */
public function stripeName(): string|null
{
    return $this->company_name;
}

به طور مشابه، می‌توانید روش‌های stripeEmail ، stripePhone و stripeAddress ، و را لغو کنید stripePreferredLocales . این روش‌ها هنگام به‌روزرسانی شی مشتری Stripe، اطلاعات را با پارامترهای مشتری مربوطه همگام‌سازی می‌کنند . اگر می‌خواهید کنترل کاملی بر فرآیند همگام‌سازی اطلاعات مشتری در دست بگیرید، ممکن است این syncStripeCustomerDetails روش را لغو کنید.

پورتال صورتحساب

Stripe یک راه آسان برای راه اندازی یک پورتال صورتحساب ارائه می دهد تا مشتری شما بتواند اشتراک، روش های پرداخت خود را مدیریت کند و سابقه صورتحساب خود را مشاهده کند. می‌توانید با فراخوانی redirectToBillingPortal روش روی مدل قابل پرداخت از یک کنترل‌کننده یا مسیر، کاربران خود را به درگاه صورت‌حساب هدایت کنید :

use Illuminate\Http\Request;
 
Route::get('/billing-portal', function (Request $request) {
    return $request->user()->redirectToBillingPortal();
});

به طور پیش فرض، زمانی که کاربر مدیریت اشتراک خود را به پایان رساند، می تواند home از طریق پیوندی در پورتال صورتحساب Stripe به مسیر برنامه شما بازگردد. شما می توانید یک URL سفارشی ارائه کنید که کاربر باید با ارسال URL به عنوان آرگومان به redirectToBillingPortal روش، به آن بازگردد:

use Illuminate\Http\Request;
 
Route::get('/billing-portal', function (Request $request) {
    return $request->user()->redirectToBillingPortal(route('billing'));
});

اگر می خواهید URL را به درگاه صورتحساب بدون ایجاد پاسخ تغییر مسیر HTTP ایجاد کنید، می توانید billingPortalUrl روش زیر را فراخوانی کنید:

$url = $request->user()->billingPortalUrl(route('billing'));

روش های پرداخت

ذخیره سازی روش های پرداخت

برای ایجاد اشتراک یا انجام هزینه‌های «یکباره» با Stripe، باید یک روش پرداخت را ذخیره کرده و شناسه آن را از Stripe بازیابی کنید. رویکرد مورد استفاده برای انجام این کار بسته به اینکه قصد دارید از روش پرداخت برای اشتراک یا هزینه تکی استفاده کنید متفاوت است، بنابراین در زیر هر دو را بررسی خواهیم کرد.

روش های پرداخت برای اشتراک

هنگام ذخیره اطلاعات کارت اعتباری مشتری برای استفاده در آینده توسط یک اشتراک، باید از Stripe "Setup Intents" API برای جمع آوری ایمن جزئیات روش پرداخت مشتری استفاده شود. یک "نیت راه اندازی" به Stripe نشان می دهد که قصد دارد از روش پرداخت مشتری هزینه کند. ویژگی Cashier Billable شامل createSetupIntent روش ایجاد آسان Setup Intent است. شما باید این روش را از مسیر یا کنترل‌کننده‌ای فراخوانی کنید که فرمی را که جزئیات روش پرداخت مشتری شما را جمع‌آوری می‌کند ارائه می‌کند:

return view('update-payment-method', [
    'intent' => $user->createSetupIntent()
]);

پس از ایجاد Setup Intent و ارسال آن به view، باید راز آن را به عنصری متصل کنید که روش پرداخت را جمع آوری می کند. به عنوان مثال، این فرم "به روز رسانی روش پرداخت" را در نظر بگیرید:

<input id="card-holder-name" type="text">
 
<!-- Stripe Elements Placeholder -->
<div id="card-element"></div>
 
<button id="card-button" data-secret="{{ $intent->client_secret }}">
    Update Payment Method
</button>

در مرحله بعد، کتابخانه Stripe.js ممکن است برای پیوست کردن یک عنصر Stripe به فرم و جمع‌آوری ایمن جزئیات پرداخت مشتری استفاده شود:

<script src="https://js.stripe.com/v3/"></script>
 
<script>
    const stripe = Stripe('stripe-public-key');
 
    const elements = stripe.elements();
    const cardElement = elements.create('card');
 
    cardElement.mount('#card-element');
</script>

در مرحله بعد، کارت را می توان تأیید کرد و یک "شناسه روش پرداخت" ایمن را می توان با استفاده از روش Stripe confirmCardSetup از Stripe بازیابی کرد :

const cardHolderName = document.getElementById('card-holder-name');
const cardButton = document.getElementById('card-button');
const clientSecret = cardButton.dataset.secret;
 
cardButton.addEventListener('click', async (e) => {
    const { setupIntent, error } = await stripe.confirmCardSetup(
        clientSecret, {
            payment_method: {
                card: cardElement,
                billing_details: { name: cardHolderName.value }
            }
        }
    );
 
    if (error) {
        // Display "error.message" to the user...
    } else {
        // The card has been verified successfully...
    }
});

پس از تأیید کارت توسط Stripe، می توانید setupIntent.payment_method شناسه حاصل را به برنامه Laravel خود منتقل کنید، جایی که می توان آن را به مشتری متصل کرد. روش پرداخت را می توان به عنوان یک روش پرداخت جدید اضافه کرد یا برای به روز رسانی روش پرداخت پیش فرض استفاده کرد . همچنین می‌توانید بلافاصله از شناسه روش پرداخت برای ایجاد اشتراک جدید استفاده کنید .

اگر می‌خواهید اطلاعات بیشتری درباره اهداف راه‌اندازی و جمع‌آوری جزئیات پرداخت مشتری داشته باشید، لطفاً این نمای کلی ارائه‌شده توسط Stripe را مرور کنید .

روش های پرداخت هزینه های تکی

البته، زمانی که هزینه‌ای را از روش پرداخت مشتری دریافت می‌کنیم، فقط یک بار باید از شناسه روش پرداخت استفاده کنیم. به دلیل محدودیت‌های Stripe، نمی‌توانید از روش پرداخت پیش‌فرض ذخیره‌شده مشتری برای هزینه‌های تکی استفاده کنید. باید به مشتری اجازه دهید جزئیات روش پرداخت خود را با استفاده از کتابخانه Stripe.js وارد کند. به عنوان مثال، فرم زیر را در نظر بگیرید:

<input id="card-holder-name" type="text">
 
<!-- Stripe Elements Placeholder -->
<div id="card-element"></div>
 
<button id="card-button">
    Process Payment
</button>

پس از تعریف چنین فرمی، کتابخانه Stripe.js ممکن است برای پیوست کردن یک عنصر Stripe به فرم و جمع آوری ایمن جزئیات پرداخت مشتری استفاده شود:

<script src="https://js.stripe.com/v3/"></script>
 
<script>
    const stripe = Stripe('stripe-public-key');
 
    const elements = stripe.elements();
    const cardElement = elements.create('card');
 
    cardElement.mount('#card-element');
</script>

در مرحله بعد، کارت را می توان تأیید کرد و یک "شناسه روش پرداخت" ایمن را می توان با استفاده از روش Stripe createPaymentMethod از Stripe بازیابی کرد :

const cardHolderName = document.getElementById('card-holder-name');
const cardButton = document.getElementById('card-button');
 
cardButton.addEventListener('click', async (e) => {
    const { paymentMethod, error } = await stripe.createPaymentMethod(
        'card', cardElement, {
            billing_details: { name: cardHolderName.value }
        }
    );
 
    if (error) {
        // Display "error.message" to the user...
    } else {
        // The card has been verified successfully...
    }
});

اگر کارت با موفقیت تأیید شود، می‌توانید آن را paymentMethod.id به برنامه لاراول خود منتقل کنید و یک بار شارژ را پردازش کنید .

بازیابی روش های پرداخت

روش paymentMethods موجود در نمونه مدل قابل صورت‌حساب مجموعه‌ای از Laravel\Cashier\PaymentMethod نمونه‌ها را برمی‌گرداند:

$paymentMethods = $user->paymentMethods();

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

$paymentMethods = $user->paymentMethods('sepa_debit');

برای بازیابی روش پرداخت پیش‌فرض مشتری، defaultPaymentMethod ممکن است از روش زیر استفاده شود:

$paymentMethod = $user->defaultPaymentMethod();

می‌توانید روش پرداخت خاصی را که به مدل قابل صورت‌حساب پیوست شده است، با استفاده از این findPaymentMethod روش بازیابی کنید:

$paymentMethod = $user->findPaymentMethod($paymentMethodId);

وجود روش پرداخت

برای تعیین اینکه آیا یک مدل قابل صورت‌حساب یک روش پرداخت پیش‌فرض به حساب خود دارد یا خیر، hasDefaultPaymentMethod روش را فراخوانی کنید:

if ($user->hasDefaultPaymentMethod()) {
    // ...
}

می‌توانید از این hasPaymentMethod روش برای تعیین اینکه آیا یک مدل قابل صورت‌حساب حداقل یک روش پرداخت به حسابش متصل است یا خیر، استفاده کنید:

if ($user->hasPaymentMethod()) {
    // ...
}

این روش تعیین می کند که آیا مدل قابل صورتحساب اصلاً روش پرداختی دارد یا خیر. برای تعیین اینکه آیا یک روش پرداخت از یک نوع خاص برای مدل وجود دارد یا خیر، می‌توانید type آرگومان را به روش ارسال کنید:

if ($user->hasPaymentMethod('sepa_debit')) {
    // ...
}

به روز رسانی روش پرداخت پیش فرض

این updateDefaultPaymentMethod روش ممکن است برای به‌روزرسانی اطلاعات روش پرداخت پیش‌فرض مشتری استفاده شود. این روش یک شناسه روش پرداخت Stripe را می‌پذیرد و روش پرداخت جدید را به عنوان روش پرداخت صورت‌حساب پیش‌فرض اختصاص می‌دهد:

$user->updateDefaultPaymentMethod($paymentMethod);

برای همگام‌سازی اطلاعات روش پرداخت پیش‌فرض خود با اطلاعات روش پرداخت پیش‌فرض مشتری در Stripe، می‌توانید از این updateDefaultPaymentMethodFromStripe روش استفاده کنید:

$user->updateDefaultPaymentMethodFromStripe();

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

اضافه کردن روش های پرداخت

برای افزودن روش پرداخت جدید، می‌توانید addPaymentMethod با عبور از شناسه روش پرداخت، روش موجود در مدل قابل صورت‌حساب را فراخوانی کنید:

$user->addPaymentMethod($paymentMethod);

برای یادگیری نحوه بازیابی شناسه‌های روش پرداخت، لطفاً اسناد ذخیره‌سازی روش پرداخت را مرور کنید .

حذف روش های پرداخت

برای حذف یک روش پرداخت، می‌توانید delete روشی را که Laravel\Cashier\PaymentMethod می‌خواهید حذف کنید تماس بگیرید:

$paymentMethod->delete();

این deletePaymentMethod روش یک روش پرداخت خاص را از مدل قابل صورت‌حساب حذف می‌کند:

$user->deletePaymentMethod('pm_visa');

این deletePaymentMethods روش همه اطلاعات روش پرداخت را برای مدل قابل صورت‌حساب حذف می‌کند:

$user->deletePaymentMethods();

به طور پیش فرض، این روش هر نوع روش پرداخت را حذف می کند. برای حذف روش‌های پرداخت از یک نوع خاص، می‌توانید type آرگومان را به روش ارسال کنید:

$user->deletePaymentMethods('sepa_debit');

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

اشتراک ها

اشتراک ها راهی برای تنظیم پرداخت های مکرر برای مشتریان شما فراهم می کند. اشتراک‌های Stripe که توسط Cashier مدیریت می‌شوند، از قیمت‌های اشتراک چندگانه، مقادیر اشتراک، آزمایش‌ها و موارد دیگر پشتیبانی می‌کنند.

ایجاد اشتراک

برای ایجاد اشتراک، ابتدا نمونه ای از مدل قابل پرداخت خود را بازیابی کنید که معمولاً نمونه ای از App\Models\User . هنگامی که نمونه مدل را بازیابی کردید، می توانید از newSubscription روش برای ایجاد اشتراک مدل استفاده کنید:

use Illuminate\Http\Request;
 
Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription(
        'default', 'price_monthly'
    )->create($request->paymentMethodId);
 
    // ...
});

اولین آرگومان ارسال شده به newSubscription روش باید نوع داخلی اشتراک باشد. اگر برنامه شما فقط یک اشتراک ارائه می دهد، می توانید با این default یا تماس بگیرید primary . این نوع اشتراک فقط برای استفاده داخلی برنامه است و قرار نیست به کاربران نشان داده شود. علاوه بر این، نباید دارای فاصله باشد و هرگز نباید پس از ایجاد اشتراک تغییر کند. آرگومان دوم، قیمت خاصی است که کاربر در آن مشترک است. این مقدار باید با شناسه قیمت در Stripe مطابقت داشته باشد.

این create روش که شناسه روش پرداخت Stripe یا PaymentMethod شی Stripe را می پذیرد، اشتراک را آغاز می کند و همچنین پایگاه داده شما را با شناسه مشتری Stripe مدل قابل پرداخت و سایر اطلاعات صورتحساب مرتبط به روز می کند.

ارسال شناسه روش پرداخت به طور مستقیم به create روش اشتراک نیز به طور خودکار آن را به روش های پرداخت ذخیره شده کاربر اضافه می کند.

جمع آوری پرداخت های مکرر از طریق ایمیل فاکتور

به‌جای جمع‌آوری خودکار پرداخت‌های مکرر مشتری، می‌توانید به Stripe دستور دهید هر بار که پرداخت مکرر مشتری سررسید می‌شود، یک فاکتور برای مشتری ایمیل کند. سپس، مشتری ممکن است پس از دریافت فاکتور، آن را به صورت دستی پرداخت کند. مشتری هنگام جمع آوری پرداخت های مکرر از طریق فاکتورها نیازی به ارائه روش پرداخت از قبل ندارد:

$user->newSubscription('default', 'price_monthly')->createAndSendInvoice();

مدت زمانی که مشتری باید صورتحساب خود را قبل از لغو اشتراک خود بپردازد توسط این days_until_due گزینه تعیین می شود. به طور پیش فرض، این 30 روز است. با این حال، در صورت تمایل می توانید مقدار خاصی برای این گزینه ارائه دهید:

$user->newSubscription('default', 'price_monthly')->createAndSendInvoice([], [
    'days_until_due' => 30
]);

مقادیر

اگر می‌خواهید هنگام ایجاد اشتراک، مقدار خاصی را برای قیمت تعیین کنید، باید quantity قبل از ایجاد اشتراک، روش را در سازنده اشتراک فراخوانی کنید:

$user->newSubscription('default', 'price_monthly')
     ->quantity(5)
     ->create($paymentMethod);

توضیحات بیشتر

اگر می‌خواهید گزینه‌های مشتری یا اشتراک دیگری را که توسط Stripe پشتیبانی می‌شوند مشخص کنید ، می‌توانید این کار را با ارسال آن‌ها به عنوان آرگومان‌های دوم و سوم به create روش انجام دهید:

$user->newSubscription('default', 'price_monthly')->create($paymentMethod, [
    'email' => $email,
], [
    'metadata' => ['note' => 'Some extra information.'],
]);

کوپن

اگر می خواهید هنگام ایجاد اشتراک کوپن اعمال کنید، می توانید از withCoupon روش زیر استفاده کنید:

$user->newSubscription('default', 'price_monthly')
     ->withCoupon('code')
     ->create($paymentMethod);

یا اگر می‌خواهید کد تبلیغاتی Stripe را اعمال کنید ، می‌توانید از withPromotionCode روش زیر استفاده کنید:

$user->newSubscription('default', 'price_monthly')
     ->withPromotionCode('promo_code_id')
     ->create($paymentMethod);

شناسه کد تبلیغاتی داده شده باید شناسه Stripe API اختصاص داده شده به کد تبلیغاتی باشد و نه مشتری که با کد تبلیغاتی روبروست. اگر نیاز به یافتن شناسه کد تبلیغاتی بر اساس کد تبلیغاتی خاص مشتری دارید، می‌توانید از findPromotionCode روش زیر استفاده کنید:

// Find a promotion code ID by its customer facing code...
$promotionCode = $user->findPromotionCode('SUMMERSALE');
 
// Find an active promotion code ID by its customer facing code...
$promotionCode = $user->findActivePromotionCode('SUMMERSALE');

در مثال بالا، $promotionCode شیء برگشتی یک نمونه از Laravel\Cashier\PromotionCode . این کلاس یک Stripe\PromotionCode شی زیرین را تزئین می کند. می توانید کوپن مربوط به کد تبلیغاتی را با فراخوانی coupon روش بازیابی کنید:

$coupon = $user->findPromotionCode('SUMMERSALE')->coupon();

نمونه کوپن به شما امکان می دهد میزان تخفیف را تعیین کنید و اینکه آیا کوپن نشان دهنده یک تخفیف ثابت است یا بر اساس درصد:

if ($coupon->isPercentage()) {
    return $coupon->percentOff().'%'; // 21.5%
} else {
    return $coupon->amountOff(); // $5.99
}

همچنین می‌توانید تخفیف‌هایی را که در حال حاضر برای یک مشتری یا اشتراک اعمال می‌شود، بازیابی کنید:

$discount = $billable->discount();
 
$discount = $subscription->discount();

نمونه های برگشتی Laravel\Cashier\Discount یک نمونه شی زیرین را تزئین می کنند Stripe\Discount . می توانید کوپن مربوط به این تخفیف را با استفاده از coupon روش زیر بازیابی کنید:

$coupon = $subscription->discount()->coupon();

اگر می‌خواهید یک کوپن یا کد تبلیغاتی جدید برای مشتری یا اشتراک اعمال کنید، می‌توانید این کار را از طریق applyCoupon یا applyPromotionCode روش‌های زیر انجام دهید:

$billable->applyCoupon('coupon_id');
$billable->applyPromotionCode('promotion_code_id');
 
$subscription->applyCoupon('coupon_id');
$subscription->applyPromotionCode('promotion_code_id');

به یاد داشته باشید، شما باید از Stripe API ID اختصاص داده شده به کد تبلیغاتی استفاده کنید نه مشتری که با کد تبلیغاتی روبروست. فقط یک کوپن یا کد تبلیغاتی را می توان در یک زمان معین برای مشتری یا اشتراک اعمال کرد.

برای اطلاعات بیشتر در مورد این موضوع، لطفاً به مستندات Stripe در مورد کوپن ها و کدهای تبلیغاتی مراجعه کنید .

اضافه کردن اشتراک ها

اگر می‌خواهید اشتراکی را به مشتری اضافه کنید که از قبل یک روش پرداخت پیش‌فرض دارد، می‌توانید از این add روش در سازنده اشتراک استفاده کنید:

use App\Models\User;
 
$user = User::find(1);
 
$user->newSubscription('default', 'price_monthly')->add();

ایجاد اشتراک از داشبورد Stripe

همچنین می توانید از خود داشبورد Stripe اشتراک ایجاد کنید. هنگام انجام این کار، Cashier اشتراک‌های تازه اضافه شده را همگام‌سازی می‌کند و به آنها یک نوع اختصاص می‌دهد default . برای سفارشی کردن نوع اشتراکی که به اشتراک‌های ایجاد شده داشبورد اختصاص داده می‌شود، کنترل‌کننده‌های رویداد webhook را تعریف کنید .

علاوه بر این، می‌توانید فقط یک نوع اشتراک را از طریق داشبورد Stripe ایجاد کنید. اگر برنامه شما چندین اشتراک را ارائه می دهد که از انواع مختلف استفاده می کنند، ممکن است فقط یک نوع اشتراک از طریق داشبورد Stripe اضافه شود.

در نهایت، همیشه باید مطمئن شوید که به ازای هر نوع اشتراکی که توسط برنامه شما ارائه می‌شود، فقط یک اشتراک فعال اضافه کنید. اگر مشتری دو default اشتراک داشته باشد، فقط آخرین اشتراک اضافه شده توسط Cashier استفاده می شود، حتی اگر هر دو با پایگاه داده برنامه شما همگام شوند.

بررسی وضعیت اشتراک

هنگامی که مشتری در برنامه شما مشترک شد، می توانید به راحتی وضعیت اشتراک او را با استفاده از روش های مختلف مناسب بررسی کنید. ابتدا، اگر مشتری اشتراک فعال داشته باشد، subscribed روش برمی گردد ، حتی اگر اشتراک در حال حاضر در دوره آزمایشی خود باشد. true متد subscribed نوع اشتراک را به عنوان اولین آرگومان خود می پذیرد:

if ($user->subscribed('default')) {
    // ...
}

این subscribed روش همچنین یک کاندیدای عالی برای میان‌افزار مسیر است که به شما امکان می‌دهد دسترسی به مسیرها و کنترل‌کننده‌ها را بر اساس وضعیت اشتراک کاربر فیلتر کنید:

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
 
class EnsureUserIsSubscribed
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->user() && ! $request->user()->subscribed('default')) {
            // This user is not a paying customer...
            return redirect('billing');
        }
 
        return $next($request);
    }
}

اگر می خواهید تعیین کنید که آیا کاربر هنوز در دوره آزمایشی خود است، می توانید از این onTrial روش استفاده کنید. این روش می تواند برای تعیین اینکه آیا باید هشداری را به کاربر نشان دهید که هنوز در دوره آزمایشی خود است مفید باشد:

if ($user->subscription('default')->onTrial()) {
    // ...
}

این subscribedToProduct روش ممکن است برای تعیین اینکه آیا کاربر در یک محصول معین بر اساس شناسه محصول Stripe مشترک شده است یا خیر، استفاده شود. در استرایپ، محصولات مجموعه ای از قیمت ها هستند. در این مثال، تعیین خواهیم کرد که آیا اشتراک کاربر default به طور فعال در محصول "حق بیمه" برنامه مشترک است یا خیر. شناسه محصول Stripe داده شده باید با یکی از شناسه های محصول شما در داشبورد Stripe مطابقت داشته باشد:

if ($user->subscribedToProduct('prod_premium', 'default')) {
    // ...
}

با ارسال یک آرایه به subscribedToProduct روش، می توانید تعیین کنید که آیا اشتراک کاربر default به طور فعال در محصول "پایه" یا "حق بیمه" برنامه مشترک است یا خیر:

if ($user->subscribedToProduct(['prod_basic', 'prod_premium'], 'default')) {
    // ...
}

این subscribedToPrice روش ممکن است برای تعیین اینکه آیا اشتراک مشتری با یک شناسه قیمت معین مطابقت دارد یا خیر استفاده شود:

if ($user->subscribedToPrice('price_basic_monthly', 'default')) {
    // ...
}

این recurring روش ممکن است برای تعیین اینکه آیا کاربر در حال حاضر مشترک است و دیگر در دوره آزمایشی خود نیست استفاده می شود:

if ($user->subscription('default')->recurring()) {
    // ...
}

اگر کاربر دو اشتراک با یک نوع داشته باشد، آخرین اشتراک همیشه با subscription روش برگردانده می شود. به عنوان مثال، یک کاربر ممکن است دو رکورد اشتراک با نوع default ; با این حال، یکی از اشتراک ها ممکن است یک اشتراک قدیمی و منقضی شده باشد، در حالی که دیگری اشتراک فعلی و فعال باشد. آخرین اشتراک همیشه برگردانده می شود در حالی که اشتراک های قدیمی برای بررسی تاریخی در پایگاه داده نگهداری می شوند.

وضعیت اشتراک لغو شده

برای تعیین اینکه آیا کاربر زمانی مشترک فعال بوده است اما اشتراک خود را لغو کرده است، می توانید از canceled روش زیر استفاده کنید:

if ($user->subscription('default')->canceled()) {
    // ...
}

همچنین می‌توانید تعیین کنید که آیا کاربر اشتراک خود را لغو کرده است، اما هنوز در «دوره مهلت» خود است تا زمانی که اشتراک به طور کامل منقضی شود. به عنوان مثال، اگر کاربر اشتراکی را در تاریخ 5 مارس لغو کند که در ابتدا قرار بود در 10 مارس منقضی شود، کاربر تا 10 مارس در "مهلت مهلت" خود است. توجه داشته باشید که subscribed روش همچنان true در این مدت باز می گردد:

if ($user->subscription('default')->onGracePeriod()) {
    // ...
}

برای تعیین اینکه آیا کاربر اشتراک خود را لغو کرده است و دیگر در "دوره مهلت" خود نیست، می توانید از ended روش زیر استفاده کنید:

if ($user->subscription('default')->ended()) {
    // ...
}

وضعیت ناقص و سررسید گذشته

اگر یک اشتراک پس از ایجاد به یک اقدام پرداخت ثانویه نیاز داشته باشد، اشتراک به عنوان علامت گذاری می شود incomplete . وضعیت اشتراک در stripe_status ستون جدول پایگاه داده صندوقدار ذخیره می شود subscriptions .

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

if ($user->hasIncompletePayment('default')) {
    // ...
}
 
if ($user->subscription('default')->hasIncompletePayment()) {
    // ...
}

هنگامی که یک اشتراک پرداخت ناقص دارد، باید کاربر را به صفحه تأیید پرداخت صندوقدار هدایت کنید و latestPayment شناسه را ارسال کنید. می توانید از latestPayment روش موجود در نمونه اشتراک برای بازیابی این شناسه استفاده کنید:

<a href="{{ route('cashier.payment', $subscription->latestPayment()->id) }}">
    Please confirm your payment.
</a>

اگر می‌خواهید اشتراک زمانی که در یک past_due یا incomplete ایالت است همچنان فعال تلقی شود، می‌توانید از روش‌های ارائه شده توسط Cashier استفاده keepPastDueSubscriptionsActive کنید keepIncompleteSubscriptionsActive . به طور معمول، این متدها باید در register متد شما فراخوانی شوند App\Providers\AppServiceProvider :

use Laravel\Cashier\Cashier;
 
/**
 * Register any application services.
 */
public function register(): void
{
    Cashier::keepPastDueSubscriptionsActive();
    Cashier::keepIncompleteSubscriptionsActive();
}

هنگامی که یک اشتراک در incomplete وضعیتی است، تا زمانی که پرداخت تأیید نشده است، نمی توان آن را تغییر داد. بنابراین، متدهای swap و updateQuantity زمانی که اشتراک در یک وضعیت باشد، استثنا ایجاد می‌کند incomplete .

محدوده های اشتراک

اکثر حالت های اشتراک نیز به عنوان محدوده پرس و جو در دسترس هستند، به طوری که می توانید به راحتی پایگاه داده خود را برای اشتراک هایی که در یک وضعیت خاص هستند پرس و جو کنید:

// Get all active subscriptions...
$subscriptions = Subscription::query()->active()->get();
 
// Get all of the canceled subscriptions for a user...
$subscriptions = $user->subscriptions()->canceled()->get();

لیست کاملی از دامنه های موجود در زیر موجود است:

Subscription::query()->active();
Subscription::query()->canceled();
Subscription::query()->ended();
Subscription::query()->incomplete();
Subscription::query()->notCanceled();
Subscription::query()->notOnGracePeriod();
Subscription::query()->notOnTrial();
Subscription::query()->onGracePeriod();
Subscription::query()->onTrial();
Subscription::query()->pastDue();
Subscription::query()->recurring();

تغییر قیمت ها

پس از اینکه مشتری در برنامه شما مشترک شد، ممکن است گهگاه بخواهد قیمت اشتراک جدیدی را تغییر دهد. برای تعویض مشتری با قیمت جدید، شناسه Stripe price را به swap روش ارسال کنید. هنگام مبادله قیمت ها، فرض بر این است که کاربر می خواهد اشتراک خود را در صورتی که قبلا لغو شده بود، دوباره فعال کند. شناسه قیمت داده شده باید با یک شناسه قیمت Stripe موجود در داشبورد Stripe مطابقت داشته باشد:

use App\Models\User;
 
$user = App\Models\User::find(1);
 
$user->subscription('default')->swap('price_yearly');

اگر مشتری در حال آزمایش باشد، دوره آزمایشی حفظ خواهد شد. علاوه بر این، اگر یک "مقدار" برای اشتراک وجود داشته باشد، آن مقدار نیز حفظ خواهد شد.

اگر می‌خواهید قیمت‌ها را مبادله کنید و هر دوره آزمایشی را که مشتری در حال حاضر در آن است لغو کنید، می‌توانید از skipTrial روش زیر استفاده کنید:

$user->subscription('default')
        ->skipTrial()
        ->swap('price_yearly');

اگر می‌خواهید به جای منتظر ماندن برای چرخه صورت‌حساب بعدی مشتری، قیمت‌ها را مبادله کنید و فوراً فاکتور بگیرید، می‌توانید از swapAndInvoice روش زیر استفاده کنید:

$user = User::find(1);
 
$user->subscription('default')->swapAndInvoice('price_yearly');

تناسب

به‌طور پیش‌فرض، Stripe هزینه‌ها را هنگام مبادله بین قیمت‌ها نسبت می‌دهد. این noProrate روش ممکن است برای به‌روزرسانی قیمت اشتراک بدون نسبت هزینه‌ها استفاده شود:

$user->subscription('default')->noProrate()->swap('price_yearly');

برای اطلاعات بیشتر در مورد میزان اشتراک، به مستندات Stripe مراجعه کنید .

اجرای noProrate متد قبل از swapAndInvoice متد تاثیری در proration نخواهد داشت. همیشه فاکتور صادر می شود.

مقدار اشتراک

گاهی اوقات اشتراک ها تحت تأثیر "کمیت" قرار می گیرند. به عنوان مثال، یک برنامه مدیریت پروژه ممکن است 10 دلار در ماه برای هر پروژه هزینه کند. می‌توانید از روش‌ها incrementQuantity و decrementQuantity روش‌ها برای افزایش یا کاهش آسان تعداد اشتراک خود استفاده کنید:

use App\Models\User;
 
$user = User::find(1);
 
$user->subscription('default')->incrementQuantity();
 
// Add five to the subscription's current quantity...
$user->subscription('default')->incrementQuantity(5);
 
$user->subscription('default')->decrementQuantity();
 
// Subtract five from the subscription's current quantity...
$user->subscription('default')->decrementQuantity(5);

از طرف دیگر، می‌توانید مقدار خاصی را با استفاده از updateQuantity روش زیر تنظیم کنید:

$user->subscription('default')->updateQuantity(10);

این noProrate روش ممکن است برای به روز رسانی مقدار اشتراک بدون نسبت هزینه ها استفاده شود:

$user->subscription('default')->noProrate()->updateQuantity(10);

برای اطلاعات بیشتر در مورد مقدار اشتراک، به مستندات Stripe مراجعه کنید .

مقادیر برای اشتراک با چندین محصول

اگر اشتراک شما اشتراکی با چندین محصول است ، باید شناسه قیمتی را که می‌خواهید مقدار آن را افزایش یا کاهش دهید، به عنوان آرگومان دوم برای روش‌های افزایش/کاهش ارسال کنید:

$user->subscription('default')->incrementQuantity(1, 'price_chat');

اشتراک با چندین محصول

اشتراک با چندین محصول به شما امکان می دهد چندین محصول صورتحساب را به یک اشتراک اختصاص دهید. به عنوان مثال، تصور کنید که در حال ساختن یک برنامه «خدمات راهنمایی» برای خدمات مشتری هستید که قیمت اشتراک پایه آن 10 دلار در ماه است اما یک محصول افزودنی چت زنده را با 15 دلار اضافی در ماه ارائه می دهد. اطلاعات مربوط به اشتراک با چندین محصول در جدول پایگاه داده صندوقدار ذخیره می شود subscription_items .

شما می توانید چندین محصول را برای یک اشتراک مشخص با ارسال آرایه ای از قیمت ها به عنوان آرگومان دوم به newSubscription روش مشخص کنید:

use Illuminate\Http\Request;
 
Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription('default', [
        'price_monthly',
        'price_chat',
    ])->create($request->paymentMethodId);
 
    // ...
});

در مثال بالا، مشتری دو قیمت به default اشتراک خود خواهد داشت. هر دو قیمت در فواصل صورتحساب مربوطه محاسبه می شوند. در صورت لزوم، می توانید از quantity روش برای نشان دادن مقدار خاصی برای هر قیمت استفاده کنید:

$user = User::find(1);
 
$user->newSubscription('default', ['price_monthly', 'price_chat'])
    ->quantity(5, 'price_chat')
    ->create($paymentMethod);

اگر می‌خواهید قیمت دیگری به اشتراک موجود اضافه کنید، می‌توانید از addPrice روش اشتراک استفاده کنید:

$user = User::find(1);
 
$user->subscription('default')->addPrice('price_chat');

مثال بالا قیمت جدید را اضافه می کند و مشتری برای آن در چرخه صورتحساب بعدی خود صورتحساب دریافت می کند. اگر می خواهید بلافاصله صورتحساب مشتری را دریافت کنید، می توانید از addPriceAndInvoice روش زیر استفاده کنید:

$user->subscription('default')->addPriceAndInvoice('price_chat');

اگر می‌خواهید قیمتی را با یک مقدار مشخص اضافه کنید، می‌توانید مقدار را به عنوان آرگومان دوم متدهای addPrice یا ارسال کنید addPriceAndInvoice :

$user = User::find(1);
 
$user->subscription('default')->addPrice('price_chat', 5);

می توانید با استفاده از removePrice روش زیر قیمت ها را از اشتراک ها حذف کنید:

$user->subscription('default')->removePrice('price_chat');

نمی توانید آخرین قیمت اشتراک را حذف کنید. در عوض، شما باید به سادگی اشتراک را لغو کنید.

معاوضه قیمت ها

همچنین می‌توانید قیمت‌های پیوست شده به اشتراکی را با چندین محصول تغییر دهید. به عنوان مثال، تصور کنید یک مشتری price_basic با یک price_chat محصول افزودنی اشتراک دارد و شما می خواهید مشتری را از قیمت price_basic به قیمت ارتقا دهید price_pro :

use App\Models\User;
 
$user = User::find(1);
 
$user->subscription('default')->swap(['price_pro', 'price_chat']);

هنگام اجرای مثال بالا، آیتم اشتراک زیرین با علامت price_basic حذف می شود و موردی که دارای the price_chat است حفظ می شود. علاوه بر این، یک آیتم اشتراک جدید برای آن price_pro ایجاد می شود.

همچنین می‌توانید با ارسال آرایه‌ای از جفت‌های کلید/مقدار به swap روش، گزینه‌های آیتم اشتراک را مشخص کنید. برای مثال، ممکن است لازم باشد مقادیر قیمت اشتراک را مشخص کنید:

$user = User::find(1);
 
$user->subscription('default')->swap([
    'price_pro' => ['quantity' => 5],
    'price_chat'
]);

اگر می‌خواهید یک قیمت واحد را با اشتراک عوض کنید، می‌توانید این کار را با استفاده از swap روش موجود در خود مورد اشتراک انجام دهید. این رویکرد به ویژه در صورتی مفید است که می‌خواهید تمام ابرداده‌های موجود را در قیمت‌های دیگر اشتراک حفظ کنید:

$user = User::find(1);
 
$user->subscription('default')
        ->findItemOrFail('price_basic')
        ->swap('price_pro');

تناسب

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

$user->subscription('default')->noProrate()->removePrice('price_chat');

مقادیر

اگر می‌خواهید مقادیر را در قیمت‌های اشتراک فردی به‌روزرسانی کنید، می‌توانید این کار را با استفاده از روش‌های کمیت موجود با ارسال شناسه قیمت به عنوان یک آرگومان اضافی برای روش انجام دهید:

$user = User::find(1);
 
$user->subscription('default')->incrementQuantity(5, 'price_chat');
 
$user->subscription('default')->decrementQuantity(3, 'price_chat');
 
$user->subscription('default')->updateQuantity(10, 'price_chat');

هنگامی که یک اشتراک چند قیمت داشته باشد، ویژگی ها stripe_price و quantity ویژگی های مدل Subscription خواهد بود null . برای دسترسی به ویژگی‌های قیمت جداگانه، باید از items رابطه موجود در Subscription مدل استفاده کنید.

اقلام اشتراک

هنگامی که یک اشتراک چندین قیمت دارد، چندین "اقلام" اشتراک در جدول پایگاه داده شما ذخیره می شود subscription_items . می توانید از طریق items رابطه موجود در اشتراک به این موارد دسترسی داشته باشید:

use App\Models\User;
 
$user = User::find(1);
 
$subscriptionItem = $user->subscription('default')->items->first();
 
// Retrieve the Stripe price and quantity for a specific item...
$stripePrice = $subscriptionItem->stripe_price;
$quantity = $subscriptionItem->quantity;

همچنین می توانید با استفاده از findItemOrFail روش زیر قیمت خاصی را بازیابی کنید:

$user = User::find(1);
 
$subscriptionItem = $user->subscription('default')->findItemOrFail('price_chat');

اشتراک های متعدد

Stripe به مشتریان شما اجازه می دهد تا چندین اشتراک را به طور همزمان داشته باشند. به عنوان مثال، شما ممکن است باشگاهی را اداره کنید که اشتراک شنا و وزنه برداری را ارائه می دهد و هر اشتراک ممکن است قیمت متفاوتی داشته باشد. البته، مشتریان باید بتوانند در یکی یا هر دو طرح مشترک شوند.

هنگامی که برنامه شما اشتراک ایجاد می کند، می توانید نوع اشتراک را در newSubscription روش ارائه دهید. نوع ممکن است هر رشته ای باشد که نشان دهنده نوع اشتراکی است که کاربر شروع می کند:

use Illuminate\Http\Request;
 
Route::post('/swimming/subscribe', function (Request $request) {
    $request->user()->newSubscription('swimming')
        ->price('price_swimming_monthly')
        ->create($request->paymentMethodId);
 
    // ...
});

در این مثال، ما اشتراک ماهیانه شنا را برای مشتری آغاز کردیم. با این حال، آنها ممکن است بخواهند در زمان دیگری به اشتراک سالانه مبادله کنند. هنگام تنظیم اشتراک مشتری، می توانیم به سادگی قیمت swimming اشتراک را تعویض کنیم:

$user->subscription('swimming')->swap('price_swimming_yearly');

البته، شما همچنین می توانید اشتراک را به طور کامل لغو کنید:

$user->subscription('swimming')->cancel();

صورتحساب اندازه گیری شده

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

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

use Illuminate\Http\Request;
 
Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription('default')
        ->meteredPrice('price_metered')
        ->create($request->paymentMethodId);
 
    // ...
});

همچنین می‌توانید از طریق Stripe Checkout یک اشتراک اندازه‌گیری شده شروع کنید :

$checkout = Auth::user()
        ->newSubscription('default', [])
        ->meteredPrice('price_metered')
        ->checkout();
 
return view('your-checkout-view', [
    'checkout' => $checkout,
]);

گزارش استفاده

همانطور که مشتری شما از برنامه شما استفاده می کند، استفاده از آنها را به Stripe گزارش می دهید تا به طور دقیق صورتحساب آنها دریافت شود. برای افزایش استفاده از اشتراک اندازه‌گیری شده، می‌توانید از reportUsage روش زیر استفاده کنید:

$user = User::find(1);
 
$user->subscription('default')->reportUsage();

به طور پیش فرض، یک "مقدار استفاده" 1 به دوره صورتحساب اضافه می شود. از طرف دیگر، می‌توانید مقدار خاصی از «استفاده» را برای افزودن به میزان استفاده مشتری برای دوره صورت‌حساب ارسال کنید:

$user = User::find(1);
 
$user->subscription('default')->reportUsage(15);

اگر برنامه شما چندین قیمت را در یک اشتراک ارائه می دهد، باید از روشی reportUsageFor برای تعیین قیمت اندازه گیری شده ای که می خواهید استفاده را برای آن گزارش دهید استفاده کنید:

$user = User::find(1);
 
$user->subscription('default')->reportUsageFor('price_metered', 15);

گاهی اوقات، ممکن است لازم باشد استفاده ای را که قبلاً گزارش کرده اید به روز کنید. برای انجام این کار، می توانید یک مهر زمانی یا یک DateTimeInterface نمونه را به عنوان پارامتر دوم به reportUsage . هنگام انجام این کار، Stripe استفاده ای را که در آن زمان گزارش شده بود به روز می کند. می‌توانید به به‌روزرسانی سوابق استفاده قبلی ادامه دهید زیرا تاریخ و زمان معین هنوز در دوره صورت‌حساب فعلی است:

$user = User::find(1);
 
$user->subscription('default')->reportUsage(5, $timestamp);

بازیابی سوابق استفاده

برای بازیابی استفاده قبلی مشتری، می توانید از usageRecords روش نمونه اشتراک استفاده کنید:

$user = User::find(1);
 
$usageRecords = $user->subscription('default')->usageRecords();

اگر برنامه شما چندین قیمت را برای یک اشتراک ارائه می دهد، می توانید از روشی usageRecordsFor برای تعیین قیمت اندازه گیری شده استفاده کنید که می خواهید سوابق استفاده را برای آن بازیابی کنید:

$user = User::find(1);
 
$usageRecords = $user->subscription('default')->usageRecordsFor('price_metered');

و متدها یک نمونه Collection حاوی یک آرایه انجمنی از سوابق استفاده را برمی‌گردانند usageRecords . usageRecordsFor برای نمایش کل مصرف مشتری، می‌توانید روی این آرایه تکرار کنید:

@foreach ($usageRecords as $usageRecord)
    - Period Starting: {{ $usageRecord['period']['start'] }}
    - Period Ending: {{ $usageRecord['period']['end'] }}
    - Total Usage: {{ $usageRecord['total_usage'] }}
@endforeach

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

مالیات اشتراک

به‌جای محاسبه دستی نرخ‌های مالیات، می‌توانید به‌طور خودکار مالیات‌ها را با استفاده از Stripe Tax محاسبه کنید

برای تعیین نرخ مالیاتی که کاربر برای اشتراک می پردازد، باید این taxRates روش را در مدل قابل پرداخت خود پیاده کنید و آرایه ای حاوی شناسه های نرخ مالیاتی Stripe را برگردانید. می توانید این نرخ های مالیاتی را در داشبورد Stripe خود تعریف کنید :

/**
 * The tax rates that should apply to the customer's subscriptions.
 *
 * @return array<int, string>
 */
public function taxRates(): array
{
    return ['txr_id'];
}

این taxRates روش به شما امکان می دهد نرخ مالیات را بر اساس مشتری به مشتری اعمال کنید، که ممکن است برای یک پایگاه کاربری که چندین کشور و نرخ مالیات را در بر می گیرد مفید باشد.

اگر اشتراک‌هایی با چندین محصول ارائه می‌دهید، می‌توانید با اجرای روشی priceTaxRates در مدل قابل پرداخت خود، نرخ‌های مالیات متفاوتی را برای هر قیمت تعریف کنید:

/**
 * The tax rates that should apply to the customer's subscriptions.
 *
 * @return array<string, array<int, string>>
 */
public function priceTaxRates(): array
{
    return [
        'price_monthly' => ['txr_id'],
    ];
}

این taxRates روش فقط برای هزینه های اشتراک اعمال می شود. اگر از Cashier برای ایجاد هزینه های "یک بار" استفاده می کنید، باید نرخ مالیات را در آن زمان به صورت دستی مشخص کنید.

همگام سازی نرخ های مالیاتی

هنگام تغییر شناسه‌های نرخ مالیاتی کدگذاری‌شده‌ای که با این taxRates روش بازگردانده می‌شوند، تنظیمات مالیاتی روی هر اشتراک موجود برای کاربر یکسان باقی می‌ماند. اگر می‌خواهید ارزش مالیات اشتراک‌های موجود را با taxRates مقادیر جدید به‌روزرسانی کنید، باید syncTaxRates روش موجود در نمونه اشتراک کاربر را فراخوانی کنید:

$user->subscription('default')->syncTaxRates();

این همچنین نرخ مالیات موردی را برای یک اشتراک با چندین محصول همگام می‌کند. اگر برنامه شما اشتراک هایی با چندین محصول ارائه می دهد، باید مطمئن شوید که مدل قابل پرداخت شما priceTaxRates روشی را که در بالا توضیح داده شد اجرا می کند .

معافیت مالیاتی

صندوقدار همچنین روش های , و را برای تعیین معافیت مالیاتی مشتری ارائه isNotTaxExempt می isTaxExempt دهد reverseChargeApplies . این روش‌ها برای تعیین وضعیت معافیت مالیاتی مشتری، Stripe API را فراخوانی می‌کنند:

use App\Models\User;
 
$user = User::find(1);
 
$user->isTaxExempt();
$user->isNotTaxExempt();
$user->reverseChargeApplies();

این روش ها بر روی هر شی نیز موجود است Laravel\Cashier\Invoice . با این حال، هنگامی که روی یک Invoice شیء فراخوانی می شود، متدها وضعیت معافیت را در زمان ایجاد فاکتور تعیین می کنند.

تاریخ لنگر اشتراک

به‌طور پیش‌فرض، لنگر چرخه صورت‌حساب، تاریخی است که اشتراک ایجاد شده است یا، در صورت استفاده از دوره آزمایشی، تاریخی است که دوره آزمایشی به پایان می‌رسد. اگر می‌خواهید تاریخ لنگر صورت‌حساب را تغییر دهید، می‌توانید از anchorBillingCycleOn روش زیر استفاده کنید:

use Illuminate\Http\Request;
 
Route::post('/user/subscribe', function (Request $request) {
    $anchor = Carbon::parse('first day of next month');
 
    $request->user()->newSubscription('default', 'price_monthly')
                ->anchorBillingCycleOn($anchor->startOfDay())
                ->create($request->paymentMethodId);
 
    // ...
});

برای اطلاعات بیشتر در مورد مدیریت چرخه‌های صورت‌حساب اشتراک، به مستندات چرخه صورت‌حساب Stripe مراجعه کنید

لغو اشتراک ها

برای لغو اشتراک، با cancel روش موجود در اشتراک کاربر تماس بگیرید:

$user->subscription('default')->cancel();

هنگامی که یک اشتراک لغو می شود، صندوقدار به طور خودکار ends_at ستون را در جدول پایگاه داده شما تنظیم می کند subscriptions . از این ستون برای دانستن زمان subscribed شروع بازگشت متد استفاده می شود false .

به عنوان مثال، اگر مشتری در تاریخ 1 مارس اشتراک خود را لغو کند، اما قرار نبود اشتراک تا 5 مارس پایان یابد، این روش تا 5 مارس subscribed ادامه خواهد داشت . true این کار به این دلیل انجام می شود که کاربر معمولاً مجاز است تا پایان چرخه صورتحساب خود از یک برنامه استفاده کند.

onGracePeriod با استفاده از این روش می‌توانید تعیین کنید که آیا کاربر اشتراک خود را لغو کرده است اما هنوز در «دوره مهلت» خود است :

if ($user->subscription('default')->onGracePeriod()) {
    // ...
}

اگر می خواهید اشتراک را فوراً لغو کنید، با cancelNow روش موجود در اشتراک کاربر تماس بگیرید:

$user->subscription('default')->cancelNow();

اگر می‌خواهید اشتراک را فوراً لغو کنید و هرگونه استفاده اندازه‌گیری‌شده بدون صورت‌حساب باقی‌مانده یا موارد جدید/درانتظار صورت‌حساب فاکتور را فاکتور کنید، با cancelNowAndInvoice روش روی اشتراک کاربر تماس بگیرید:

$user->subscription('default')->cancelNowAndInvoice();

همچنین می توانید انتخاب کنید که اشتراک در یک لحظه خاص لغو شود:

$user->subscription('default')->cancelAt(
    now()->addDays(10)
);

در نهایت، همیشه باید قبل از حذف مدل کاربر مرتبط، اشتراک کاربر را لغو کنید:

$user->subscription('default')->cancelNow();
 
$user->delete();

از سرگیری اشتراک ها

اگر مشتری اشتراک خود را لغو کرده است و شما می خواهید آن را از سر بگیرید، می توانید از resume روش موجود در اشتراک استفاده کنید. مشتری برای ازسرگیری اشتراک باید همچنان در "دوره مهلت" خود باشد:

$user->subscription('default')->resume();

اگر مشتری یک اشتراک را لغو کند و سپس آن اشتراک را قبل از اتمام کامل اشتراک از سر بگیرد، بلافاصله صورتحساب مشتری دریافت نخواهد شد. در عوض، اشتراک آنها مجدداً فعال می شود و در چرخه صورتحساب اصلی صورتحساب دریافت می شود.

آزمایشات اشتراک

با روش پرداخت از قبل

اگر می‌خواهید در حین جمع‌آوری اطلاعات روش پرداخت، دوره‌های آزمایشی را به مشتریان خود ارائه دهید، trialDays هنگام ایجاد اشتراک‌های خود باید از این روش استفاده کنید:

use Illuminate\Http\Request;
 
Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription('default', 'price_monthly')
                ->trialDays(10)
                ->create($request->paymentMethodId);
 
    // ...
});

این روش تاریخ پایان دوره آزمایشی را در سابقه اشتراک در پایگاه داده تنظیم می کند و به Stripe دستور می دهد که تا بعد از این تاریخ شروع به صدور صورت حساب مشتری نکند. هنگام استفاده از trialDays روش، Cashier هر دوره آزمایشی پیش‌فرضی را که برای قیمت در Stripe پیکربندی شده است، بازنویسی می‌کند.

اگر اشتراک مشتری قبل از تاریخ پایان دوره آزمایشی لغو نشود، به محض انقضای دوره آزمایشی هزینه از آنها کسر می شود، بنابراین باید حتماً کاربران خود را از تاریخ پایان دوره آزمایشی مطلع کنید.

این trialUntil روش به شما امکان می دهد نمونه ای را ارائه دهید DateTime که مشخص می کند دوره آزمایشی چه زمانی باید به پایان برسد:

use Carbon\Carbon;
 
$user->newSubscription('default', 'price_monthly')
            ->trialUntil(Carbon::now()->addDays(10))
            ->create($paymentMethod);