نسخه:

صندوقدار لاراول (پادل)

معرفی

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

هنگام کار با Cashier، توصیه می‌کنیم راهنمای کاربر Paddle و اسناد API را نیز مرور کنید .

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

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

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

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

composer require laravel/cashier-paddle

برای اطمینان از اینکه Cashier به درستی همه رویدادهای Paddle را مدیریت می کند، به یاد داشته باشید که کنترل وب هوک Cashier را تنظیم کنید .

جعبه شنی دست و پا زدن

در طول توسعه محلی و مرحله‌ای، باید یک حساب Paddle Sandbox ثبت کنید . این حساب به شما یک محیط سندباکس می دهد تا برنامه های خود را بدون پرداخت واقعی آزمایش و توسعه دهید. می‌توانید از شماره‌های کارت تست Paddle برای شبیه‌سازی سناریوهای پرداخت مختلف استفاده کنید.

هنگام استفاده از محیط Paddle Sandbox، باید PADDLE_SANDBOX متغیر محیط را true در فایل برنامه خود تنظیم کنید .env : 

PADDLE_SANDBOX=true

پس از اتمام توسعه برنامه خود، می توانید برای یک حساب فروشنده Paddle درخواست دهید . قبل از اینکه برنامه شما وارد مرحله تولید شود، Paddle باید دامنه برنامه شما را تأیید کند.

مهاجرت های پایگاه داده

ارائه دهنده خدمات Cashier دایرکتوری مهاجرت پایگاه داده خود را ثبت می کند، بنابراین به یاد داشته باشید که پس از نصب بسته، پایگاه داده خود را انتقال دهید. مهاجرت صندوقدار یک customers جدول جدید ایجاد می کند. علاوه بر این، یک subscriptions جدول جدید برای ذخیره تمام اشتراک های مشتری شما ایجاد می شود. در نهایت، یک جدول جدید receipts برای ذخیره تمام اطلاعات رسید برنامه شما ایجاد می شود: 

php artisan migrate

اگر نیاز به بازنویسی مهاجرت‌هایی دارید که با Cashier ارائه شده‌اند، می‌توانید آنها را با استفاده از vendor:publish دستور Artisan منتشر کنید: 

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

اگر می خواهید از اجرای کامل مهاجرت صندوقدار جلوگیری کنید، می توانید از برنامه ignoreMigrations ارائه شده توسط صندوقدار استفاده کنید. به طور معمول، این روش باید در register متد شما فراخوانی شود AppServiceProvider : 

use Laravel\Paddle\Cashier;
 
/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    Cashier::ignoreMigrations();
}

پیکربندی

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

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

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

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

use Illuminate\Database\Eloquent\Model;
use Laravel\Paddle\Billable;
 
class Team extends Model
{
    use Billable;
}

کلیدهای API

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

PADDLE_VENDOR_ID=your-paddle-vendor-id
PADDLE_VENDOR_AUTH_CODE=your-paddle-vendor-auth-code
PADDLE_PUBLIC_KEY="your-paddle-public-key"
PADDLE_SANDBOX=true

وقتی از محیط Sandbox Paddle استفاده می کنید، متغیر محیط PADDLE_SANDBOX باید روی آن تنظیم شود . اگر برنامه خود را برای تولید پیاده سازی می کنید و از محیط فروشنده زنده Paddle استفاده می کنید، باید روی این متغیر تنظیم شود . true PADDLE_SANDBOX false

Paddle JS

Paddle برای راه‌اندازی ویجت پرداخت Paddle به کتابخانه جاوا اسکریپت خود متکی است. می‌توانید کتابخانه جاوا اسکریپت را با قرار دادن @paddleJS دستورالعمل Blade درست قبل از برچسب بسته شدن طرح‌بندی برنامه خود بارگیری کنید </head> : 

<head>
    ...
 
    @paddleJS
</head>

پیکربندی ارز

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

CASHIER_CURRENCY=EUR

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

CASHIER_CURRENCY_LOCALE=nl_BE

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

نادیده گرفتن مدل های پیش فرض

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

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

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

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

مفاهیم اصلی

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

use App\Models\User;
use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $payLink = $request->user()->newSubscription('default', $premium = 34567)
        ->returnTo(route('home'))
        ->create();
 
    return view('billing', ['payLink' => $payLink]);
});

صندوقدار شامل یک paddle-button جزء تیغه است . ما ممکن است URL پیوند پرداخت را به عنوان یک "سرپا" به این مؤلفه ارسال کنیم. هنگامی که این دکمه کلیک می شود، ویجت پرداخت Paddle نمایش داده می شود: 

<x-paddle-button :url="$payLink" class="px-8 py-4">
    Subscribe
</x-paddle-button>

به‌طور پیش‌فرض، این دکمه‌ای را با استایل استاندارد Paddle نمایش می‌دهد. می توانید با افزودن data-theme="none" ویژگی به کامپوننت، تمام استایل های Paddle را حذف کنید: 

<x-paddle-button :url="$payLink" class="px-8 py-4" data-theme="none">
    Subscribe
</x-paddle-button>

ویجت پرداخت Paddle ناهمزمان است. هنگامی که کاربر اشتراکی را در ویجت ایجاد یا به‌روزرسانی کرد، Paddle وب‌قلاب‌های برنامه شما را ارسال می‌کند تا بتوانید وضعیت اشتراک را در پایگاه داده خودمان به‌درستی به‌روزرسانی کنید. بنابراین، مهم است که به درستی وب هوک ها را برای تطبیق تغییرات وضعیت از Paddle تنظیم کنید .

برای اطلاعات بیشتر در مورد پیوندهای پرداخت، می‌توانید مستندات Paddle API را در مورد ایجاد پیوند پرداخت مرور کنید .

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

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

$payLink = $request->user()->newSubscription('default', $premium = 34567)
    ->returnTo(route('home'))
    ->create();

سپس، به سادگی URL پیوند پرداخت را به یک a عنصر در HTML خود پیوست کنید: 

<a href="#!" class="ml-4 paddle_button" data-override="{{ $payLink }}">
    Paddle Checkout
</a>

پرداخت هایی که نیاز به تایید اضافی دارند

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

پرداخت درون خطی

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

برای سهولت در شروع پرداخت درون خطی، Cashier شامل یک paddle-checkout جزء Blade است. برای شروع، باید یک پیوند پرداخت ایجاد کنید و پیوند پرداخت را به ویژگی مؤلفه ارسال کنید override : 

<x-paddle-checkout :override="$payLink" class="w-full" />

برای تنظیم ارتفاع مؤلفه پرداخت درون خطی، می توانید height ویژگی را به مؤلفه Blade منتقل کنید: 

<x-paddle-checkout :override="$payLink" class="w-full" height="500" />

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

@php
$options = [
    'product' => $productId,
    'title' => 'Product Title',
];
@endphp
 
<x-paddle-checkout :options="$options" class="w-full" />

لطفاً برای جزئیات بیشتر در مورد گزینه های موجود پرداخت درون خطی، به راهنمای Paddle در مورد Inline Checkout و همچنین مرجع پارامتر آنها مراجعه کنید.

اگر می‌خواهید passthrough هنگام تعیین گزینه‌های سفارشی نیز از این گزینه استفاده کنید، باید یک آرایه کلید / مقدار به عنوان مقدار آن ارائه کنید. Cashier به طور خودکار تبدیل آرایه به رشته JSON را انجام می دهد. علاوه بر این، customer_id گزینه عبور برای استفاده داخلی صندوقدار رزرو شده است.

ارائه دستی پرداخت درون خطی

همچنین می توانید بدون استفاده از اجزای Blade داخلی لاراول، یک پرداخت درون خطی را به صورت دستی ارائه دهید. برای شروع، URL پیوند پرداخت را همانطور که در مثال های قبلی نشان داده شد ایجاد کنید .

در مرحله بعد، می توانید از Paddle.js برای مقداردهی اولیه پرداخت استفاده کنید. برای ساده نگه داشتن این مثال، این را با استفاده از Alpine.js نشان خواهیم داد . با این حال، شما آزاد هستید که این مثال را به پشته frontend خودتان ترجمه کنید: 

<div class="paddle-checkout" x-data="{}" x-init="
    Paddle.Checkout.open({
        override: {{ $payLink }},
        method: 'inline',
        frameTarget: 'paddle-checkout',
        frameInitialHeight: 366,
        frameStyle: 'width: 100%; background-color: transparent; border: none;'
    });
">
</div>

شناسایی کاربر

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

با توجه به این رفتار، نکات مهمی وجود دارد که باید هنگام استفاده از صندوقدار و پارو در نظر داشته باشید. ابتدا، باید توجه داشته باشید که حتی اگر اشتراک‌ها در Cashier به یک کاربر برنامه مرتبط هستند، می‌توانند به کاربران مختلفی در سیستم‌های داخلی Paddle مرتبط باشند . ثانیاً، هر اشتراک اطلاعات روش پرداخت متصل خود را دارد و همچنین می‌تواند آدرس‌های ایمیل متفاوتی در سیستم‌های داخلی Paddle داشته باشد (بسته به اینکه در هنگام ایجاد اشتراک کدام ایمیل به کاربر اختصاص داده شده است).

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

$subscription = $user->subscription('default');
 
$subscription->paddleEmail();
$subscription->paymentMethod();
$subscription->cardBrand();
$subscription->cardLastFour();
$subscription->cardExpirationDate();

در حال حاضر هیچ راهی برای تغییر آدرس ایمیل کاربر از طریق Paddle API وجود ندارد. هنگامی که کاربر می خواهد آدرس ایمیل خود را در Paddle به روز کند، تنها راه برای انجام این کار تماس با پشتیبانی مشتری Paddle است. هنگام برقراری ارتباط با Paddle، آنها باید paddleEmail مقدار اشتراک را ارائه دهند تا به Paddle در به روز رسانی کاربر صحیح کمک کند.

قیمت

Paddle به شما امکان می‌دهد قیمت‌ها را برای هر ارز سفارشی کنید و اساساً به شما امکان می‌دهد قیمت‌های مختلف را برای کشورهای مختلف پیکربندی کنید. Cashier Paddle به شما امکان می دهد با استفاده از این روش، تمام قیمت های یک محصول معین را بازیابی کنید productPrices . این روش شناسه‌های محصول محصولاتی را که می‌خواهید قیمت‌ها را بازیابی کنید، می‌پذیرد: 

use Laravel\Paddle\Cashier;
 
$prices = Cashier::productPrices([123, 456]);

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

use Laravel\Paddle\Cashier;
 
$prices = Cashier::productPrices([123, 456], ['customer_country' => 'BE']);

پس از بازیابی قیمت ها، می توانید آنها را هر طور که می خواهید نمایش دهید: 

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product_title }} - {{ $price->price()->gross() }}</li>
    @endforeach
</ul>

همچنین می‌توانید قیمت خالص (بدون مالیات) را نمایش دهید و مبلغ مالیات را جداگانه نمایش دهید: 

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product_title }} - {{ $price->price()->net() }} (+ {{ $price->price()->tax() }} tax)</li>
    @endforeach
</ul>

اگر قیمت‌های طرح‌های اشتراک را بازیابی کرده‌اید، می‌توانید قیمت اولیه و تکرارشونده آنها را جداگانه نمایش دهید: 

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product_title }} - Initial: {{ $price->initialPrice()->gross() }} - Recurring: {{ $price->recurringPrice()->gross() }}</li>
    @endforeach
</ul>

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

مشتریان

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

use App\Models\User;
 
$prices = User::find(1)->productPrices([123, 456]);

paddleCountry در داخل، Cashier از روش کاربر برای بازیابی قیمت ها به واحد پول خود استفاده می کند. بنابراین، برای مثال، کاربری که در ایالات متحده زندگی می کند قیمت ها را به دلار آمریکا می بیند در حالی که کاربر در بلژیک قیمت ها را به یورو می بیند. اگر ارز منطبقی پیدا نشد، واحد پول پیش‌فرض محصول استفاده می‌شود. می‌توانید تمام قیمت‌های یک محصول یا طرح اشتراک را در کنترل پنل Paddle سفارشی کنید.

کوپن

همچنین می‌توانید پس از کاهش کوپن، قیمت‌ها را نمایش دهید. هنگام فراخوانی productPrices متد، کوپن ها ممکن است به صورت رشته ای با کاما ارسال شوند: 

use Laravel\Paddle\Cashier;
 
$prices = Cashier::productPrices([123, 456], [
    'coupons' => 'SUMMERSALE,20PERCENTOFF'
]);

سپس قیمت های محاسبه شده را با استفاده از price روش زیر نمایش دهید: 

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product_title }} - {{ $price->price()->gross() }}</li>
    @endforeach
</ul>

می توانید قیمت های اصلی فهرست شده (بدون تخفیف کوپن) را با استفاده از listPrice روش زیر نمایش دهید: 

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product_title }} - {{ $price->listPrice()->gross() }}</li>
    @endforeach
</ul>

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

مشتریان

پیش فرض های مشتری

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

/**
 * Get the customer's email address to associate with Paddle.
 *
 * @return string|null
 */
public function paddleEmail()
{
    return $this->email;
}
 
/**
 * Get the customer's country to associate with Paddle.
 *
 * This needs to be a 2 letter code. See the link below for supported countries.
 *
 * @return string|null
 * @link https://developer.paddle.com/reference/platform-parameters/supported-countries
 */
public function paddleCountry()
{
    //
}
 
/**
 * Get the customer's postal code to associate with Paddle.
 *
 * See the link below for countries which require this.
 *
 * @return string|null
 * @link https://developer.paddle.com/reference/platform-parameters/supported-countries#countries-requiring-postcode
 */
public function paddlePostcode()
{
    //
}

این پیش‌فرض‌ها برای هر اقدامی در Cashier که پیوند پرداخت ایجاد می‌کند استفاده می‌شود .

اشتراک ها

ایجاد اشتراک

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

use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $payLink = $request->user()->newSubscription('default', $premium = 12345)
        ->returnTo(route('home'))
        ->create();
 
    return view('billing', ['payLink' => $payLink]);
});

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

این create روش یک پیوند پرداخت ایجاد می کند که می توانید از آن برای ایجاد دکمه پرداخت استفاده کنید. دکمه پرداخت را می توان با استفاده از paddle-button مولفه Blade که با Cashier Paddle ارائه می شود ایجاد کرد: 

<x-paddle-button :url="$payLink" class="px-8 py-4">
    Subscribe
</x-paddle-button>

پس از اینکه کاربر پرداخت خود را به پایان رساند، یک subscription_created وب هوک از Paddle ارسال می شود. صندوقدار این وب هوک را دریافت می کند و اشتراک را برای مشتری شما تنظیم می کند. برای اطمینان از اینکه همه وبکهک‌ها به درستی دریافت شده و توسط برنامه شما مدیریت می‌شوند، مطمئن شوید که مدیریت وب‌هوک را به‌درستی تنظیم کرده‌اید .

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

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

$payLink = $user->newSubscription('default', $monthly = 12345)
    ->returnTo(route('home'))
    ->create([
        'vat_number' => $vatNumber,
    ]);

کوپن

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

$payLink = $user->newSubscription('default', $monthly = 12345)
    ->returnTo(route('home'))
    ->withCoupon('code')
    ->create();

فراداده

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

$payLink = $user->newSubscription('default', $monthly = 12345)
    ->returnTo(route('home'))
    ->withMetadata(['key' => 'value'])
    ->create();

هنگام ارائه ابرداده، لطفاً از استفاده subscription_name به عنوان کلید فراداده خودداری کنید. این کلید برای استفاده داخلی توسط صندوقدار رزرو شده است.

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

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

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

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

<?php
 
namespace App\Http\Middleware;
 
use Closure;
 
class EnsureUserIsSubscribed
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        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()) {
    //
}

این subscribedToPlan روش ممکن است برای تعیین اینکه آیا کاربر در یک طرح معین بر اساس شناسه طرح Paddle معین مشترک شده است یا خیر استفاده شود. در این مثال، تعیین می کنیم که آیا اشتراک کاربر default به طور فعال در طرح ماهانه مشترک است یا خیر: 

if ($user->subscribedToPlan($monthly = 12345, 'default')) {
    //
}

با ارسال یک آرایه به subscribedToPlan روش، می توانید تعیین کنید که آیا اشتراک کاربر default به طور فعال در برنامه ماهانه یا سالانه مشترک است: 

if ($user->subscribedToPlan([$monthly = 12345, $yearly = 54321], 'default')) {
    //
}

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

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

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

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

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

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

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

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

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

وضعیت سررسید گذشته

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

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

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

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

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

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

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

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

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

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

Subscription::query()->active();
Subscription::query()->onTrial();
Subscription::query()->notOnTrial();
Subscription::query()->pastDue();
Subscription::query()->recurring();
Subscription::query()->ended();
Subscription::query()->paused();
Subscription::query()->notPaused();
Subscription::query()->onPausedGracePeriod();
Subscription::query()->notOnPausedGracePeriod();
Subscription::query()->cancelled();
Subscription::query()->notCancelled();
Subscription::query()->onGracePeriod();
Subscription::query()->notOnGracePeriod();

هزینه های تک اشتراک

هزینه های تک اشتراک به شما این امکان را می دهد که مشترکین را با یک بار هزینه در کنار اشتراک خود شارژ کنید: 

$response = $user->subscription('default')->charge(12.99, 'Support Add-on');

برخلاف هزینه های تکی ، این روش بلافاصله از روش پرداخت ذخیره شده مشتری برای اشتراک هزینه دریافت می کند. مبلغ شارژ همیشه باید به واحد پول اشتراک تعریف شود.

به روز رسانی اطلاعات پرداخت

Paddle همیشه یک روش پرداخت را برای هر اشتراک ذخیره می کند. اگر می‌خواهید روش پرداخت پیش‌فرض برای اشتراک را به‌روزرسانی کنید، ابتدا باید با استفاده از روش موجود updateUrl در مدل اشتراک، یک «URL به‌روزرسانی» اشتراک ایجاد کنید: 

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

سپس، می‌توانید از URL تولید شده در ترکیب با paddle-button مؤلفه Blade ارائه شده توسط Cashier استفاده کنید تا به کاربر اجازه دهید ویجت Paddle را راه‌اندازی کند و اطلاعات پرداخت خود را به‌روزرسانی کند: 

<x-paddle-button :url="$updateUrl" class="px-8 py-4">
    Update Card
</x-paddle-button>

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

تغییر برنامه ها

پس از اینکه کاربر در برنامه شما مشترک شد، ممکن است گهگاه بخواهد به یک طرح اشتراک جدید تغییر کند. برای به روز رسانی طرح اشتراک برای یک کاربر، باید شناسه طرح Paddle را به swap روش اشتراک ارسال کنید: 

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

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

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

وقتی آزمایشی فعال است، نمی‌توان برنامه‌ها را تعویض کرد. برای اطلاعات بیشتر در مورد این محدودیت، لطفاً به مستندات Paddle مراجعه کنید .

تناسب

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

$user->subscription('default')->noProrate()->swap($premium = 34567);

مقدار اشتراک

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

$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);

اصلاح کننده های اشتراک

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

برای مثال، ممکن است بخواهید با اشتراک استاندارد خود یک افزونه «پشتیبانی ممتاز» ارائه دهید. شما می توانید این اصلاح کننده را به صورت زیر ایجاد کنید: 

$modifier = $user->subscription('default')->newModifier(12.99)->create();

مثال بالا یک افزونه 12.99 دلاری به اشتراک اضافه می کند. به طور پیش فرض، این هزینه در هر بازه زمانی که برای اشتراک پیکربندی کرده اید تکرار می شود. در صورت تمایل، می‌توانید با استفاده از description روش اصلاح‌کننده، یک توضیح قابل خواندن به اصلاح‌کننده اضافه کنید: 

$modifier = $user->subscription('default')->newModifier(12.99)
    ->description('Premium Support')
    ->create();

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

$modifier = $user->subscription('default')->newModifier(0.99)
    ->description('New text message')
    ->oneTime()
    ->create();

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

بازیابی اصلاح کننده ها

می‌توانید فهرستی از همه اصلاح‌کننده‌های یک اشتراک را از طریق modifiers روش زیر بازیابی کنید: 

$modifiers = $user->subscription('default')->modifiers();
 
foreach ($modifiers as $modifier) {
    $modifier->amount(); // $0.99
    $modifier->description; // New text message.
}

حذف اصلاح کننده ها

delete اصلاح‌کننده‌ها ممکن است با فراخوانی متد در یک نمونه حذف شوند Laravel\Paddle\Modifier : 

$modifier->delete();

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

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

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

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

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

$user->subscription('swimming')->swap($swimmingYearly = 34567);

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

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

توقف اشتراک ها

برای توقف موقت اشتراک، pause روش موجود در اشتراک کاربر را فراخوانی کنید: 

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

هنگامی که یک اشتراک متوقف می شود، صندوقدار به طور خودکار paused_from ستون را در پایگاه داده شما تنظیم می کند. از این ستون برای دانستن زمان paused شروع بازگشت متد استفاده می شود true . به عنوان مثال، اگر مشتری اشتراک خود را در اول مارس متوقف کند، اما قرار نبود اشتراک تا 5 مارس تکرار شود، این روش تا 5 مارس paused ادامه خواهد داشت . false این کار به این دلیل انجام می شود که کاربر معمولاً مجاز است تا پایان چرخه صورتحساب خود از یک برنامه استفاده کند.

onPausedGracePeriod با استفاده از این روش می‌توانید تعیین کنید که آیا کاربر اشتراک خود را موقتاً متوقف کرده است اما هنوز در "دوره مهلت" خود است : 

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

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

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

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

لغو اشتراک ها

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

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

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

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

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

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

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

اشتراک های Paddle پس از لغو قابل از سرگیری نمی باشد. اگر مشتری شما بخواهد اشتراک خود را از سر بگیرد، باید مشترک اشتراک جدیدی شود.

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

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

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

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

use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $payLink = $request->user()->newSubscription('default', $monthly = 12345)
                ->returnTo(route('home'))
                ->trialDays(10)
                ->create();
 
    return view('billing', ['payLink' => $payLink]);
});

این روش تاریخ پایان دوره آزمایشی را در سابقه اشتراک در پایگاه داده برنامه شما تنظیم می کند، و همچنین به Paddle دستور می دهد که تا بعد از این تاریخ شروع به صدور صورت حساب مشتری نکند.

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

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

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

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

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

تعریف روزهای آزمایشی در دست و پا زدن / صندوقدار

می‌توانید تعیین کنید که برنامه‌تان چند روز آزمایشی در داشبورد Paddle دریافت می‌کند یا همیشه آن‌ها را به‌صراحت با استفاده از Cashier پاس کنید. اگر تصمیم می‌گیرید روزهای آزمایشی طرح خود را در Paddle تعریف کنید، باید توجه داشته باشید که اشتراک‌های جدید، از جمله اشتراک‌های جدید برای مشتری که در گذشته اشتراک داشته‌اند، همیشه یک دوره آزمایشی دریافت می‌کنند، مگر اینکه صریحاً با روش تماس بگیرید trialDays(0) .

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

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

use App\Models\User;
 
$user = User::create([
    // ...
]);
 
$user->createAsCustomer([
    'trial_ends_at' => now()->addDays(10)
]);

صندوقدار به این نوع آزمایش به عنوان یک "آزمایش عمومی" اشاره می کند، زیرا به هیچ اشتراک موجود متصل نیست. اگر تاریخ فعلی از مقدار زیر گذشته نباشد، متد onTrial موجود در User نمونه برمی‌گردد . true trial_ends_at 

if ($user->onTrial()) {
    // User is within their trial period...
}

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

use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $payLink = $user->newSubscription('default', $monthly = 12345)
        ->returnTo(route('home'))
        ->create();
 
    return view('billing', ['payLink' => $payLink]);
});

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

if ($user->onTrial()) {
    $trialEndsAt = $user->trialEndsAt('main');
}

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

if ($user->onGenericTrial()) {
    // User is within their "generic" trial period...
}

هیچ راهی برای تمدید یا تغییر دوره آزمایشی در اشتراک Paddle پس از ایجاد آن وجود ندارد.

رسیدگی به قلاب های وب پارویی

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

به طور پیش‌فرض، این کنترل‌کننده به‌طور خودکار لغو اشتراک‌هایی را که هزینه‌های ناموفق زیادی دارند ( که توسط تنظیمات Paddle dunning شما تعریف شده است )، به‌روزرسانی‌های اشتراک و تغییرات روش پرداخت را کنترل می‌کند. با این حال، همانطور که به زودی متوجه خواهیم شد، می‌توانید این کنترلر را برای مدیریت هر رویداد Paddle webhook که دوست دارید گسترش دهید.

برای اطمینان از اینکه برنامه شما می‌تواند به وبک‌هوک‌های Paddle رسیدگی کند، حتماً URL وب هوک را در پانل کنترل Paddle پیکربندی کنید . به طور پیش فرض، کنترلر وب هوک Cashier به /paddle/webhook مسیر URL پاسخ می دهد. لیست کامل تمام وبی هوک هایی که باید در کنترل پنل Paddle فعال کنید عبارتند از:

  • اشتراک ایجاد شد
  • اشتراک به روز شد
  • اشتراک لغو شد
  • پرداخت با موفقیت انجام شد
  • پرداخت اشتراک با موفقیت انجام شد

مطمئن شوید که از درخواست‌های دریافتی با میان‌افزار تأیید امضای وب‌هوک شامل Cashier محافظت می‌کنید .

Webhooks & CSRF Protection

از آنجایی که وب هوک های Paddle باید حفاظت CSRF لاراول را دور بزنند ، حتماً URI را به عنوان یک استثنا در App\Http\Middleware\VerifyCsrfToken میان افزار خود فهرست کنید یا مسیر خارج از web گروه میان افزار را فهرست کنید: 

protected $except = [
    'paddle/*',
];

وب هوک ها و توسعه محلی

برای اینکه Paddle بتواند وب هوک های برنامه شما را در طول توسعه محلی ارسال کند، باید برنامه خود را از طریق یک سرویس اشتراک گذاری سایت مانند Ngrok یا Expose در معرض دید قرار دهید . اگر برنامه خود را به صورت محلی با استفاده از Laravel Sail توسعه می دهید، می توانید از دستور اشتراک گذاری سایت Sail استفاده کنید .

تعریف مدیریت رویداد Webhook

صندوق دار به طور خودکار لغو اشتراک را در صورت هزینه های ناموفق و سایر وب هوک های رایج Paddle کنترل می کند. با این حال، اگر رویدادهای webhook دیگری دارید که می‌خواهید مدیریت کنید، می‌توانید این کار را با گوش دادن به رویدادهای زیر که توسط Cashier ارسال می‌شود انجام دهید:

  • Laravel\Paddle\Events\WebhookReceived
  • Laravel\Paddle\Events\WebhookHandled

هر دو رویداد حاوی بار کامل وب هوک Paddle هستند. برای مثال، اگر می‌خواهید invoice.payment_succeeded وب هوک را مدیریت کنید، می‌توانید شنونده‌ای را ثبت کنید که رویداد را مدیریت کند: 

<?php
 
namespace App\Listeners;
 
use Laravel\Paddle\Events\WebhookReceived;
 
class PaddleEventListener
{
    /**
     * Handle received Paddle webhooks.
     *
     * @param  \Laravel\Paddle\Events\WebhookReceived  $event
     * @return void
     */
    public function handle(WebhookReceived $event)
    {
        if ($event->payload['alert_name'] === 'payment_succeeded') {
            // Handle the incoming event...
        }
    }
}

هنگامی که شنونده شما تعریف شد، می توانید آن را در برنامه خود ثبت کنید EventServiceProvider : 

<?php
 
namespace App\Providers;
 
use App\Listeners\PaddleEventListener;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Laravel\Paddle\Events\WebhookReceived;
 
class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        WebhookReceived::class => [
            PaddleEventListener::class,
        ],
    ];
}

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

  • Laravel\Paddle\Events\PaymentSucceeded
  • Laravel\Paddle\Events\SubscriptionPaymentSucceeded
  • Laravel\Paddle\Events\SubscriptionCreated
  • Laravel\Paddle\Events\SubscriptionUpdated
  • Laravel\Paddle\Events\SubscriptionCancelled

CASHIER_WEBHOOK همچنین می‌توانید با تعریف متغیر محیطی در فایل برنامه خود، مسیر پیش‌فرض و داخلی هوک را لغو کنید .env . این مقدار باید URL کامل مسیر وب هوک شما باشد و باید با URL تنظیم شده در پانل کنترل Paddle شما مطابقت داشته باشد: 

CASHIER_WEBHOOK=https://example.com/my-paddle-webhook-url

تأیید امضاهای Webhook

برای ایمن سازی وب هوک های خود، می توانید از امضاهای وب هوک Paddle استفاده کنید . برای راحتی کار، Cashier به طور خودکار شامل یک میان افزار می شود که اعتبار درخواست دریافتی Paddle webhook را تأیید می کند.

برای فعال کردن تأیید وب هوک، مطمئن شوید که PADDLE_PUBLIC_KEY متغیر محیط در فایل برنامه شما تعریف شده است .env . ممکن است کلید عمومی از داشبورد حساب Paddle شما بازیابی شود.

شارژ تک

شارژ ساده

اگر می‌خواهید یک بار هزینه از مشتری دریافت کنید، می‌توانید از روش charge نمونه‌ای از مدل قابل پرداخت برای ایجاد پیوند پرداخت برای هزینه استفاده کنید. این charge روش مقدار شارژ (float) را به عنوان اولین آرگومان خود و توضیح شارژ را به عنوان آرگومان دوم خود می پذیرد: 

use Illuminate\Http\Request;
 
Route::get('/store', function (Request $request) {
    return view('store', [
        'payLink' => $user->charge(12.99, 'Action Figure')
    ]);
});

پس از ایجاد پیوند پرداخت، می‌توانید از paddle-button مؤلفه Blade ارائه شده توسط Cashier استفاده کنید تا به کاربر اجازه دهید ویجت Paddle را راه‌اندازی کند و هزینه را تکمیل کند: 

<x-paddle-button :url="$payLink" class="px-8 py-4">
    Buy
</x-paddle-button>

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

$payLink = $user->charge(12.99, 'Action Figure', [
    'custom_option' => $value,
]);

هزینه ها به ارز مشخص شده در cashier.currency گزینه پیکربندی انجام می شود. به طور پیش فرض، این روی USD تنظیم شده است. می توانید با تعریف CASHIER_CURRENCY متغیر محیطی در فایل برنامه خود، ارز پیش فرض را لغو کنید .env : 

CASHIER_CURRENCY=EUR

همچنین می‌توانید با استفاده از سیستم تطبیق قیمت پویا Paddle، قیمت‌های هر ارز را لغو کنید . برای انجام این کار، به جای مقدار ثابت، آرایه ای از قیمت ها را ارسال کنید: 

$payLink = $user->charge([
    'USD:19.99',
    'EUR:15.99',
], 'Action Figure');

شارژ محصولات

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

use Illuminate\Http\Request;
 
Route::get('/store', function (Request $request) {
    return view('store', [
        'payLink' => $request->user()->chargeProduct($productId = 123)
    ]);
});

سپس، می‌توانید پیوند پرداخت را به paddle-button مؤلفه ارائه دهید تا به کاربر اجازه دهید ویجت Paddle را مقداردهی اولیه کند: 

<x-paddle-button :url="$payLink" class="px-8 py-4">
    Buy
</x-paddle-button>

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

$payLink = $user->chargeProduct($productId, [
    'custom_option' => $value,
]);

سفارشات بازپرداخت

اگر نیاز به بازپرداخت سفارش Paddle دارید، می توانید از این refund روش استفاده کنید. این متد شناسه سفارش Paddle را به عنوان اولین آرگومان خود می پذیرد. می توانید رسیدهای یک مدل قابل پرداخت را با استفاده از receipts روش زیر بازیابی کنید: 

use App\Models\User;
 
$user = User::find(1);
 
$receipt = $user->receipts()->first();
 
$refundRequestId = $user->refund($receipt->order_id);

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

$receipt = $user->receipts()->first();
 
$refundRequestId = $user->refund(
    $receipt->order_id, 5.00, 'Unused product time'
);

هنگام تماس با پشتیبانی Paddle می توانید از آن $refundRequestId به عنوان مرجع بازپرداخت استفاده کنید.

رسیدها

می‌توانید به راحتی مجموعه‌ای از رسیدهای یک مدل قابل پرداخت را از طریق receipts دارایی زیر بازیابی کنید: 

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

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

<table>
    @foreach ($receipts as $receipt)
        <tr>
            <td>{{ $receipt->paid_at->toFormattedDateString() }}</td>
            <td>{{ $receipt->amount() }}</td>
            <td><a href="{{ $receipt->receipt_url }}" target="_blank">Download</a></td>
        </tr>
    @endforeach
</table>

پرداخت های گذشته و آینده

می‌توانید از روش‌ها lastPayment و nextPayment روش‌ها برای بازیابی و نمایش پرداخت‌های گذشته یا آتی مشتری برای اشتراک‌های تکراری استفاده کنید: 

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

هر دوی این روش ها نمونه ای از Laravel\Paddle\Payment ; با این حال، پس از پایان چرخه صورت‌حساب (مانند زمانی که اشتراک لغو شده است) nextPayment باز خواهد گشت : null 

Next payment: {{ $nextPayment->amount() }} due on {{ $nextPayment->date()->format('d/m/Y') }}

رسیدگی به پرداخت های ناموفق

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

همچنین، می‌توانید با گوش دادن به subscription_payment_failed رویداد Paddle از طریق WebhookReceived رویداد ارسال شده توسط Cashier، سفارشی‌سازی دقیق‌تری انجام دهید. همچنین باید مطمئن شوید که گزینه «پرداخت اشتراک انجام نشد» در تنظیمات Webhook داشبورد Paddle شما فعال است: 

<?php
 
namespace App\Listeners;
 
use Laravel\Paddle\Events\WebhookReceived;
 
class PaddleEventListener
{
    /**
     * Handle received Paddle webhooks.
     *
     * @param  \Laravel\Paddle\Events\WebhookReceived  $event
     * @return void
     */
    public function handle(WebhookReceived $event)
    {
        if ($event->payload['alert_name'] === 'subscription_payment_failed') {
            // Handle the failed subscription payment...
        }
    }
}

هنگامی که شنونده شما تعریف شد، باید آن را در برنامه خود ثبت کنید EventServiceProvider : 

<?php
 
namespace App\Providers;
 
use App\Listeners\PaddleEventListener;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Laravel\Paddle\Events\WebhookReceived;
 
class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        WebhookReceived::class => [
            PaddleEventListener::class,
        ],
    ];
}

آزمایش کردن

در حین آزمایش، باید به صورت دستی جریان صورتحساب خود را آزمایش کنید تا مطمئن شوید که یکپارچه سازی شما همانطور که انتظار می رود کار می کند.

برای آزمایش‌های خودکار، از جمله آزمایش‌هایی که در محیط CI انجام می‌شوند، می‌توانید از HTTP Client لاراول برای جعل تماس‌های HTTP که با Paddle انجام می‌شود استفاده کنید. اگرچه این پاسخ‌های واقعی Paddle را آزمایش نمی‌کند، اما راهی برای آزمایش برنامه شما بدون فراخوانی API Paddle ارائه می‌کند.