Laravel Cashier (Paddle)

簡介
升級 Cashier
安裝
- Paddle 沙箱
組態設定
快速入門
- 銷售產品
- 銷售訂閱
結帳工作階段
價格預覽
- 客戶價格預覽
- 折扣
客戶
訂閱
訂閱試用
處理 Paddle Webhooks
- 定義 Webhook 事件處理程序
- 驗證 Webhook 簽名
單一收費
交易
- 過去和即將到來的付款
測試

簡介

Warning

本文件是關於 Cashier Paddle 2.x 與 Paddle Billing 整合的。如果您仍在使用 Paddle Classic，應該使用 Cashier Paddle 1.x。

Laravel Cashier Paddle 提供了一個表達豐富、流暢的介面，用於Paddle的訂閱計費服務。它處理了幾乎所有您所擔心的樣板訂閱計費代碼。除了基本的訂閱管理外，Cashier 還可以處理：更換訂閱、訂閱“數量”、訂閱暫停、取消寬限期等。

在深入研究 Cashier Paddle 之前，我們建議您也查看 Paddle 的概念指南和API 文件。

升級 Cashier

當升級到 Cashier 的新版本時，重要的是您仔細查看升級指南。

安裝

首先，使用 Composer 套件管理器安裝 Paddle 的 Cashier 套件：

composer require laravel/cashier-paddle

接下來，您應該使用 vendor:publish Artisan 命令發布 Cashier 遷移文件：

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

然後，您應運行應用程式的資料庫遷移。Cashier 遷移將創建一個新的 customers 表。此外，將創建新的 subscriptions 和 subscription_items 表來存儲所有客戶的訂閱。最後，將創建一個新的 transactions 表來存儲與您的客戶相關的所有 Paddle 交易：

php artisan migrate

Warning

為確保 Cashier 正確處理所有 Paddle 事件，請記得設置 Cashier 的 webhook 處理。

Paddle 測試環境

在本地和階段性開發期間，您應該註冊 Paddle 測試帳戶。此帳戶將為您提供一個隔離的環境，以測試和開發應用程式，而不會進行實際付款。您可以使用 Paddle 的測試卡號來模擬各種付款情境。

在使用 Paddle 測試環境時，您應該在應用程式的 .env 檔案中將 PADDLE_SANDBOX 環境變數設置為 true：

PADDLE_SANDBOX=true

當您完成應用程式的開發後，您可以申請 Paddle 供應商帳戶。在將您的應用程式投入生產之前，Paddle 需要核准您的應用程式域名。

組態設定

可計費模型

在使用 Cashier 之前，您必須將 Billable Trait 添加到您的使用者模型定義中。此 Trait 提供各種方法，讓您可以執行常見的計費任務，例如建立訂閱和更新付款方式資訊：

use Laravel\Paddle\Billable;

class User extends Authenticatable
{
    use Billable;
}

如果您有不是使用者的可計費實體，您也可以將 Trait 添加到這些類別中：

use Illuminate\Database\Eloquent\Model;
use Laravel\Paddle\Billable;

class Team extends Model
{
    use Billable;
}

API 金鑰

接下來，您應該在應用程式的 .env 檔案中配置您的 Paddle 金鑰。您可以從 Paddle 控制面板檢索您的 Paddle API 金鑰：

PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
PADDLE_API_KEY=your-paddle-api-key
PADDLE_RETAIN_KEY=your-paddle-retain-key
PADDLE_WEBHOOK_SECRET="your-paddle-webhook-secret"
PADDLE_SANDBOX=true

當您使用Paddle 測試環境時，PADDLE_SANDBOX 環境變數應該設置為 true。如果您將應用程式部署到生產環境並使用 Paddle 的實際供應商環境，則 PADDLE_SANDBOX 變數應設置為 false。

PADDLE_RETAIN_KEY 是可選的，只有在您使用 Paddle 與 Retain 時才應設置。

Paddle JS

Paddle 依賴其自己的 JavaScript 函式庫來啟動 Paddle 結帳小工具。您可以通過將 @paddleJS Blade 指示詞放置在應用程式佈局的結尾 </head> 標籤之前來載入 JavaScript 函式庫：

<head>
    ...

    @paddleJS
</head>

貨幣設定

您可以指定在發票上顯示金錢值時使用的語言環境。在內部，Cashier 利用 PHP 的 NumberFormatter 類來設定貨幣語言環境：

CASHIER_CURRENCY_LOCALE=nl_BE

Warning

為了使用除 en 以外的語言環境，請確保您的伺服器已安裝並配置了 ext-intl PHP 擴充功能。

覆寫預設模型

您可以通過定義自己的模型並擴展相應的 Cashier 模型來自由擴展 Cashier 內部使用的模型：

use Laravel\Paddle\Subscription as CashierSubscription;

class Subscription extends CashierSubscription
{
    // ...
}

定義完您的模型後，您可以通過 Laravel\Paddle\Cashier 類指示 Cashier 使用您的自訂模型。通常，您應該在應用程式的 App\Providers\AppServiceProvider 類的 boot 方法中告知 Cashier 有關您的自訂模型：

use App\Models\Cashier\Subscription;
use App\Models\Cashier\Transaction;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useTransactionModel(Transaction::class);
}

快速入門

銷售產品

Note

在使用 Paddle 結帳之前，您應在 Paddle 控制台中定義具有固定價格的產品。此外，您應該配置 Paddle 的 Webhooks 處理。

透過您的應用程式提供產品和訂閱計費可能會讓人感到害怕。但是，感謝 Cashier 和 Paddle 的結帳覆蓋層，您可以輕鬆建立現代、強大的付款整合。

為了向客戶收取非循環、單次收費的產品，我們將利用 Cashier 來使用 Paddle 的結帳覆蓋層向客戶收費，他們將在此提供他們的付款詳細資料並確認購買。一旦通過結帳覆蓋層進行付款，客戶將被重新導向到您在應用程式中選擇的成功 URL：

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $request->user()->checkout('pri_deluxe_album')
        ->returnTo(route('dashboard'));

    return view('buy', ['checkout' => $checkout]);
})->name('checkout');

如上例所示，我們將利用 Cashier 提供的 checkout 方法來創建一個結帳物件，以向客戶展示 Paddle 結帳覆蓋層，以供應特定的 "價格識別碼"。在使用 Paddle 時，"價格" 指的是特定產品的定義價格。

如果需要，checkout 方法將自動在 Paddle 中創建一個客戶，並將該 Paddle 客戶記錄連接到您應用程式資料庫中對應的使用者。完成結帳會話後，客戶將被重新導向到專用的成功頁面，您可以在該頁面向客戶顯示資訊訊息。

在 buy 視圖中，我們將包含一個按鈕以顯示結帳覆蓋層。paddle-button Blade 元件隨 Cashier Paddle 一起提供；但是，您也可以手動呈現覆蓋層結帳：

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    購買產品
</x-paddle-button>

提供給 Paddle 結帳的元資料

在銷售產品時，通常會透過您自己應用程式定義的 Cart 和 Order 模型來追蹤完成的訂單和已購買的產品。當將客戶重新導向到 Paddle 的結帳覆蓋層以完成購買時，您可能需要提供現有的訂單識別碼，以便在客戶重新導向回您的應用程式時將完成的購買與相應的訂單關聯起來。

為了完成這個任務，您可以向 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',
    ]);

    $checkout = $request->user()->checkout($order->price_ids)
        ->customData(['order_id' => $order->id]);

    return view('billing', ['checkout' => $checkout]);
})->name('checkout');

如上例所示，當用戶開始結帳流程時，我們將提供所有購物車/訂單相關的 Paddle 價格識別符給 checkout 方法。當然，您的應用程序負責將這些項目與“購物車”或訂單關聯起來，就像客戶添加它們一樣。我們還通過 customData 方法向 Paddle Checkout Overlay 提供訂單的 ID。

當然，一旦客戶完成結帳流程，您可能希望將訂單標記為“完成”。為了實現這一點，您可以監聽由 Paddle 發送的 Webhooks 並通過 Cashier 引發的事件來將訂單信息存儲在您的數據庫中。

要開始，請監聽 Cashier 引發的 TransactionCompleted 事件。通常，您應該在應用程序的 AppServiceProvider 的 boot 方法中註冊事件監聽器：

use App\Listeners\CompleteOrder;
use Illuminate\Support\Facades\Event;
use Laravel\Paddle\Events\TransactionCompleted;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Event::listen(TransactionCompleted::class, CompleteOrder::class);
}

在這個例子中，CompleteOrder 監聽器可能如下所示：

namespace App\Listeners;

use App\Models\Order;
use Laravel\Paddle\Cashier;
use Laravel\Paddle\Events\TransactionCompleted;

class CompleteOrder
{
    /**
     * 處理傳入的 Cashier webhook 事件。
     */
    public function handle(TransactionCompleted $event): void
    {
        $orderId = $event->payload['data']['custom_data']['order_id'] ?? null;

        $order = Order::findOrFail($orderId);

        $order->update(['status' => 'completed']);
    }
}

請參考 Paddle 的文件以獲取有關 transaction.completed 事件中包含的資料的更多信息。

銷售訂閱

Note

在使用 Paddle Checkout 之前，您應該在 Paddle 控制台中定義具有固定價格的產品。此外，您應該配置 Paddle 的 webhook 處理。

通過您的應用程序提供產品和訂閱計費可能會讓人感到害怕。但是，由於 Cashier 和 Paddle 的 Checkout Overlay，您可以輕鬆構建現代、強大的支付集成。

要了解如何使用 Cashier 和 Paddle 的 Checkout Overlay 銷售訂閱，讓我們考慮一個簡單的情境，即具有基本月費（price_basic_monthly）和年費（price_basic_yearly）計劃的訂閱服務。這兩個價格可以在我們的 Paddle 控制台中分組為“基本”產品（pro_basic）。此外，我們的訂閱服務可能提供專家計劃作為 pro_expert。

首先，讓我們了解客戶如何訂閱我們的服務。當然，您可以想像客戶可能會在我們應用程式的定價頁面上為基本計劃點擊“訂閱”按鈕。此按鈕將為他們選擇的計劃調用 Paddle Checkout Overlay。要開始，讓我們通過 checkout 方法啟動結帳會話：

use Illuminate\Http\Request;

Route::get('/subscribe', function (Request $request) {
    $checkout = $request->user()->checkout('price_basic_monthly')
        ->returnTo(route('dashboard'));

    return view('subscribe', ['checkout' => $checkout]);
})->name('subscribe');

在 subscribe 視圖中，我們將包含一個按鈕來顯示結帳覆蓋層。paddle-button Blade 元件與 Cashier Paddle 一起提供；但是，您也可以手動呈現一個覆蓋層結帳：

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    訂閱
</x-paddle-button>

現在，當用戶點擊訂閱按鈕時，他們將能夠輸入其付款詳細信息並啟動他們的訂閱。為了知道他們的訂閱實際開始了（因為某些付款方式需要幾秒鐘來處理），您還應該配置 Cashier 的 webhook 處理。

現在用戶可以開始訂閱了，我們需要限制應用程序的某些部分，以便只有訂閱用戶可以訪問它們。當然，我們總是可以通過 Cashier 的 Billable 特性提供的 subscribed 方法來確定用戶當前的訂閱狀態：

@if ($user->subscribed())
    <p>您已訂閱。</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
{
    /**
     * 處理傳入的請求。
     */
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()?->subscribed()) {
            // 將用戶重定向到結帳頁面並要求他們訂閱...
            return redirect('/subscribe');
        }

            return $next($request);
        }
    }

一旦定義了中介層，您可以將其分配給一個路由：

    use App\Http\Middleware\Subscribed;

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

允許客戶管理其計費計劃

當然，客戶可能希望將他們的訂閱計劃更改為另一個產品或“層級”。在上面的示例中，我們希望允許客戶將他們的計劃從每月訂閱更改為每年訂閱。為此，您需要實現類似以下路由的按鈕：

    use Illuminate\Http\Request;

    Route::put('/subscription/{price}/swap', function (Request $request, $price) {
        $user->subscription()->swap($price); // With "$price" being "price_basic_yearly" for this example.

        return redirect()->route('dashboard');
    })->name('subscription.swap');

除了更換計劃外，您還需要允許客戶取消他們的訂閱。與更換計劃一樣，提供一個按鈕，導致以下路由：

    use Illuminate\Http\Request;

    Route::put('/subscription/cancel', function (Request $request, $price) {
        $user->subscription()->cancel();

        return redirect()->route('dashboard');
    })->name('subscription.cancel');

現在，您的訂閱將在其計費週期結束時被取消。

Note

只要您配置了 Cashier 的 Webhook 處理，Cashier 將通過檢查來自 Paddle 的傳入 Webhook，自動保持應用程序的 Cashier 相關數據表同步。因此，例如，當您通過 Paddle 的儀表板取消客戶的訂閱時，Cashier 將接收相應的 Webhook，並在應用程序的數據庫中將訂閱標記為“已取消”。

結帳會話

大多數向客戶收費的操作都是使用 Paddle 的結帳覆蓋窗口小部件或利用內嵌結帳來執行的。

在使用 Paddle 進行結帳付款之前，您應該在 Paddle 結帳設定儀表板中定義您應用程式的預設付款連結。

疊加式結帳

在顯示結帳疊加式小工具之前，您必須使用 Cashier 生成一個結帳會話。結帳會話將通知結帳小工具應執行的結帳操作：

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

Cashier 包含一個 paddle-button Blade 元件。您可以將結帳會話作為 "prop" 傳遞給此元件。然後，當點擊此按鈕時，Paddle 的結帳小工具將顯示：

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    訂閱
</x-paddle-button>

默認情況下，這將使用 Paddle 的預設樣式顯示小工具。您可以通過向元件添加Paddle 支持的屬性，如 data-theme='light' 屬性，來自定義小工具：

<x-paddle-button :checkout="$checkout" class="px-8 py-4" data-theme="light">
    訂閱
</x-paddle-button>

Paddle 的結帳小工具是異步的。一旦用戶在小工具內創建訂閱，Paddle 將向您的應用程式發送一個 Webhook，以便您可以適當地更新應用程式數據庫中的訂閱狀態。因此，重要的是您正確地設置 Webhooks以應對來自 Paddle 的狀態變化。

Warning

在訂閱狀態更改後，接收相應 Webhook 的延遲通常很小，但您應該在應用程式中考慮這一點，因為完成結帳後，您的用戶訂閱可能不會立即可用。

手動呈現疊加結帳

您也可以手動呈現疊加結帳，而不使用 Laravel 內建的 Blade 元件。要開始，請生成結帳工作階段如前面的範例所示：

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

接下來，您可以使用 Paddle.js 來初始化結帳。在此範例中，我們將建立一個分配了 paddle_button 類別的連結。Paddle.js 將檢測到此類別並在點擊連結時顯示疊加結帳：

<?php
$items = $checkout->getItems();
$customer = $checkout->getCustomer();
$custom = $checkout->getCustomData();
?>

<a
    href='#!'
    class='paddle_button'
    data-items='{!! json_encode($items) !!}'
    @if ($customer) data-customer-id='{{ $customer->paddle_id }}' @endif
    @if ($custom) data-custom-data='{{ json_encode($custom) }}' @endif
    @if ($returnUrl = $checkout->getReturnUrl()) data-success-url='{{ $returnUrl }}' @endif
>
    Buy Product
</a>

內嵌式結帳

如果您不想使用 Paddle 的 "疊加" 樣式結帳小工具，Paddle 也提供了在內嵌式中顯示小工具的選項。雖然這種方法不允許您調整任何結帳的 HTML 欄位，但它允許您將小工具嵌入應用程式中。

為了讓您輕鬆開始使用內嵌式結帳，Cashier 包含了一個 paddle-checkout Blade 元件。要開始，您應該生成一個結帳工作階段：

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

然後，您可以將結帳工作階段傳遞給元件的 checkout 屬性：

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

要調整內嵌式結帳元件的高度，您可以將 height 屬性傳遞給 Blade 元件：

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

請參考 Paddle 的內嵌式結帳指南和可用的結帳設定以獲得有關內嵌式結帳自訂選項的更多詳細資訊。

手動渲染內嵌結帳

您也可以手動渲染內嵌結帳，而不使用 Laravel 內建的 Blade 元件。要開始，生成結帳會話如前面的示例所示：

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

接下來，您可以使用 Paddle.js 來初始化結帳。在這個示例中，我們將使用 Alpine.js 來演示；但您可以自由修改此示例以符合您自己的前端堆疊：

<?php
$options = $checkout->options();

$options['settings']['frameTarget'] = 'paddle-checkout';
$options['settings']['frameInitialHeight'] = 366;
?>

<div class="paddle-checkout" x-data="{}" x-init="
    Paddle.Checkout.open(@json($options));
">
</div>

訪客結帳

有時，您可能需要為不需要在您的應用程式中設立帳戶的使用者創建一個結帳會話。為此，您可以使用 guest 方法：

use Illuminate\Http\Request;
use Laravel\Paddle\Checkout;

Route::get('/buy', function (Request $request) {
    $checkout = Checkout::guest(['pri_34567'])
        ->returnTo(route('home'));

    return view('billing', ['checkout' => $checkout]);
});

然後，您可以將結帳會話提供給 Paddle 按鈕或內嵌結帳 Blade 元件。

價格預覽

Paddle 允許您根據貨幣自訂價格，基本上允許您為不同國家配置不同的價格。Cashier Paddle 允許您使用 previewPrices 方法檢索所有這些價格。此方法接受您希望檢索價格的價格 ID：

use Laravel\Paddle\Cashier;

$prices = Cashier::previewPrices(['pri_123', 'pri_456']);

貨幣將根據請求的 IP 地址來確定；但您也可以選擇性地提供特定國家以檢索價格：

use Laravel\Paddle\Cashier;```

```blade
<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    @endforeach
</ul>

你可以按照自己的喜好顯示這些價格。

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->subtotal() }} (+ {{ $price->tax() }} tax)</li>
    @endforeach
</ul>

欲瞭解更多資訊，請參閱 Paddle 有關價格預覽的 API 文件。

顧客價格預覽

如果用戶已經是客戶，並且您想顯示適用於該客戶的價格，您可以通過直接從客戶實例檢索價格來實現：

use App\Models\User;

$prices = User::find(1)->previewPrices(['pri_123', 'pri_456']);

在內部，Cashier 將使用用戶的客戶 ID 來檢索其貨幣中的價格。例如，居住在美國的用戶將看到美元價格，而居住在比利時的用戶將看到歐元價格。如果找不到匹配的貨幣，將使用產品的默認貨幣。您可以在 Paddle 控制面板中自定義產品或訂閱計劃的所有價格。

折扣

您也可以選擇在折扣後顯示價格。調用 previewPrices 方法時，通過 discount_id 選項提供折扣 ID：

use Laravel\Paddle\Cashier;

$prices = Cashier::previewPrices(['pri_123', 'pri_456'], [
    'discount_id' => 'dsc_123'
]);

然後，顯示計算後的價格：

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    @endforeach
</ul>

顧客

顧客默認值

Cashier 允許您在創建結帳會話時為您的客戶定義一些有用的默認值。設置這些默認值可以讓您預先填寫客戶的電子郵件地址和姓名，以便他們可以立即進入結帳小部件的付款部分。您可以通過覆蓋您的可計費模型上的以下方法來設置這些默認值：

    /**
     * 獲取與 Paddle 關聯的客戶姓名。
     */
    public function paddleName(): string|null
    {
        return $this->name;
    }

    /**
     * 獲取與 Paddle 關聯的客戶電子郵件地址。
     */
    public function paddleEmail(): string|null
    {
        return $this->email;
    }

這些預設將用於 Cashier 中生成 [結帳工作階段](#checkout-sessions) 的每個操作。

<a name="retrieving-customers"></a>
### 檢索客戶

您可以使用 `Cashier::findBillable` 方法通過其 Paddle 客戶 ID 檢索客戶。此方法將返回一個可計費模型的實例：

    use Laravel\Paddle\Cashier;

    $user = Cashier::findBillable($customerId);

<a name="creating-customers"></a>
### 創建客戶

偶爾，您可能希望創建一個 Paddle 客戶，而不開始訂閱。您可以使用 `createAsCustomer` 方法來實現此目的：

    $customer = $user->createAsCustomer();

將返回一個 `Laravel\Paddle\Customer` 的實例。一旦在 Paddle 中創建了客戶，您可以在以後的某個日期開始訂閱。您可以提供一個可選的 `$options` 陣列，以傳遞任何 Paddle API 支持的其他 [客戶創建參數](https://developer.paddle.com/api-reference/customers/create-customer)：

    $customer = $user->createAsCustomer($options);

<a name="subscriptions"></a>
## 訂閱

<a name="creating-subscriptions"></a>
### 創建訂閱

要創建訂閱，首先從數據庫中檢索您的可計費模型的實例，這通常將是 `App\Models\User` 的實例。檢索模型實例後，您可以使用 `subscribe` 方法來創建模型的結帳工作階段：

    use Illuminate\Http\Request;

    Route::get('/user/subscribe', function (Request $request) {
        $checkout = $request->user()->subscribe($premium = 12345, 'default')
            ->returnTo(route('home'));

        return view('billing', ['checkout' => $checkout]);
    });

subscribe 方法的第一個引數是用戶正在訂閱的具體價格。此值應對應於 Paddle 中價格的識別符。returnTo 方法接受一個 URL，在用戶成功完成結帳後將重定向到該 URL。傳遞給 subscribe 方法的第二個引數應該是訂閱的內部“類型”。如果您的應用程序僅提供單一訂閱，您可以將其稱為 default 或 primary。此訂閱類型僅供內部應用程序使用，不應顯示給用戶。此外，它不應包含空格，並且在創建訂閱後永遠不應更改。

您還可以使用 customData 方法提供有關訂閱的自定義元數據的數組：

$checkout = $request->user()->subscribe($premium = 12345, 'default')
    ->customData(['key' => 'value'])
    ->returnTo(route('home'));

一旦創建了訂閱結帳會話，可以將該結帳會話提供給 Cashier Paddle 包含的 paddle-button Blade 組件：

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    訂閱
</x-paddle-button>

用戶完成結帳後，Paddle 將發送 subscription_created Webhook。Cashier 將接收此 Webhook 並為您的客戶設置訂閱。為確保應用程序正確接收並處理所有 Webhook，請確保您已正確設置 Webhook 處理。

檢查訂閱狀態

一旦用戶訂閱了您的應用程序，您可以使用各種方便的方法檢查其訂閱狀態。首先，subscribed 方法在用戶有有效訂閱時返回 true，即使訂閱目前處於試用期內：

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

如果您的應用程序提供多個訂閱，您可以在調用 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()) {
            // This user is not a paying customer...
            return redirect('/billing');
        }

        return $next($request);
    }
}

如果您想確定用戶是否仍在試用期內，您可以使用 onTrial 方法。此方法可用於確定是否應向用戶顯示警告，指出他們仍在試用期內：

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

subscribedToPrice 方法可用於確定用戶是否根據給定的 Paddle 價格 ID 訂閱了給定計劃。在此示例中，我們將確定用戶的 default 訂閱是否已訂閱月度價格：

if ($user->subscribedToPrice($monthly = 'pri_123', 'default')) {
    // ...
}

recurring 方法可用於確定用戶當前是否處於活動訂閱狀態，並且不再處於試用期或寬限期內：

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

取消訂閱狀態

要確定用戶曾經是活躍訂閱者但已取消訂閱，您可以使用 canceled 方法：


```php
if ($user->subscription()->canceled()) {
    // ...
}

您也可以確定用戶是否已取消訂閱，但仍處於“寬限期”，直到訂閱完全到期。例如，如果用戶在3月5日取消了原定於3月10日到期的訂閱，則用戶在3月10日之前處於“寬限期”。此外，在此期間，subscribed 方法仍將返回 true：

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

逾期狀態

如果訂閱的付款失敗，它將被標記為 past_due。當您的訂閱處於此狀態時，直到客戶更新其付款信息為止，訂閱將不活動。您可以使用訂閱實例上的 pastDue 方法來確定訂閱是否逾期：

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

當訂閱逾期時，您應該指示用戶更新其付款信息。

如果您希望在訂閱處於 past_due 狀態時仍將其視為有效，則可以使用 Cashier 提供的 keepPastDueSubscriptionsActive 方法。通常，此方法應該在您的 AppServiceProvider 的 register 方法中調用：

use Laravel\Paddle\Cashier;

/**
 * 註冊任何應用程式服務。
 */
public function register(): void
{
    Cashier::keepPastDueSubscriptionsActive();
}

Warning

當訂閱處於 past_due 狀態時，直到付款信息已更新為止，它將無法更改。因此，當訂閱處於 past_due 狀態時，swap 和 updateQuantity 方法將拋出異常。

訂閱範圍

大多數訂閱狀態也可用作查詢範圍，以便您可以輕鬆查詢處於特定狀態的訂閱：

// 獲取所有有效訂閱...
$subscriptions = Subscription::query()->valid()->get();

以下是可用範圍的完整清單：

Subscription::query()->valid();
Subscription::query()->onTrial();
Subscription::query()->expiredTrial();
Subscription::query()->notOnTrial();
Subscription::query()->active();
Subscription::query()->recurring();
Subscription::query()->pastDue();
Subscription::query()->paused();
Subscription::query()->notPaused();
Subscription::query()->onPausedGracePeriod();
Subscription::query()->notOnPausedGracePeriod();
Subscription::query()->canceled();
Subscription::query()->notCanceled();
Subscription::query()->onGracePeriod();
Subscription::query()->notOnGracePeriod();

訂閱單次收費

訂閱單次收費允許您對訂閱者進行一次性收費，除了他們的訂閱費用之外。在調用 charge 方法時，您必須提供一個或多個價格 ID：

// 收取單一價格...
$response = $user->subscription()->charge('pri_123');

// 同時收取多個價格...
$response = $user->subscription()->charge(['pri_123', 'pri_456']);

charge 方法實際上不會在訂閱的下一個計費間隔之前向客戶收費。如果您想立即向客戶收費，您可以改用 chargeAndInvoice 方法：

$response = $user->subscription()->chargeAndInvoice('pri_123');

更新付款資訊

Paddle 始終為每個訂閱保存一個付款方式。如果您想要更新訂閱的默認付款方式，您應該將客戶重定向到 Paddle 的託管付款方式更新頁面，使用訂閱模型上的 redirectToUpdatePaymentMethod 方法：

use Illuminate\Http\Request;

Route::get('/update-payment-method', function (Request $request) {
    $user = $request->user();

return $user->subscription()->redirectToUpdatePaymentMethod();
});

當使用者完成更新其資訊後，Paddle 將發送 subscription_updated Webhooks 並更新訂閱詳細資料至您應用程式的資料庫。

變更方案

當使用者訂閱您的應用程式後，他們可能偶爾想要切換至新的訂閱方案。要為使用者更新訂閱方案，您應該將 Paddle 價格識別碼傳遞給訂閱的 swap 方法：

use App\Models\User;

$user = User::find(1);

$user->subscription()->swap($premium = 'pri_456');

如果您想要切換方案並立即向使用者開立發票，而不是等待他們的下一個結算週期，您可以使用 swapAndInvoice 方法：

$user = User::find(1);

$user->subscription()->swapAndInvoice($premium = 'pri_456');

部分計費

預設情況下，Paddle 在不同方案之間切換時會按比例計費。可以使用 noProrate 方法來更新訂閱而不按比例計費：

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

如果您想要停用按比例計費並立即向客戶開立發票，您可以結合 noProrate 使用 swapAndInvoice 方法：

$user->subscription('default')->noProrate()->swapAndInvoice($premium = 'pri_456');

或者，若要在不向客戶收取訂閱更改費用時，您可以使用 doNotBill 方法：

$user->subscription('default')->doNotBill()->swap($premium = 'pri_456');

有關 Paddle 部分計費政策的更多資訊，請參閱 Paddle 的部分計費文件。

訂閱數量

有時訂閱會受到「數量」的影響。例如，專案管理應用程式可能會按每專案每月 $10 收費。要輕鬆增加或減少訂閱的數量，請使用 incrementQuantity 和 decrementQuantity 方法：```

$user = User::find(1);

$user->subscription()->incrementQuantity();

// 將訂閱的當前數量增加五個...
$user->subscription()->incrementQuantity(5);

$user->subscription()->decrementQuantity();

// 將訂閱的當前數量減少五個...
$user->subscription()->decrementQuantity(5);

或者，您可以使用 `updateQuantity` 方法設置特定數量：

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

使用 `noProrate` 方法可在不按比例計算費用的情況下更新訂閱的數量：

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

多產品訂閱的數量

如果您的訂閱是具有多個產品的訂閱，您應將希望增加或減少數量的價格的 ID 作為第二個參數傳遞給增加/減少方法：

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

具有多個產品的訂閱

具有多個產品的訂閱允許您將多個計費產品分配給單個訂閱。例如，假設您正在構建一個每月基本訂閱價格為 $10 的客戶服務“幫助台”應用程序，但提供額外的每月 $15 的即時聊天附加產品。

在創建訂閱結帳會話時，您可以通過將價格數組作為 subscribe 方法的第一個參數傳遞來為給定訂閱指定多個產品：

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe([
        'price_monthly',
        'price_chat',
    ]);

    return view('billing', ['checkout' => $checkout]);
});

在上面的示例中，客戶的 default 訂閱將附有兩個價格。這兩個價格將按其各自的計費間隔收費。如有必要，您可以傳遞一個鍵/值對的關聯數組，以指示每個價格的特定數量：```

$user = User::find(1);

$checkout = $user->subscribe('default', ['price_monthly', 'price_chat' => 5]);

如果您想要將另一個價格添加到現有訂閱中，您必須使用訂閱的 swap 方法。在調用 swap 方法時，您還應包括訂閱的當前價格和數量：

$user = User::find(1);

$user->subscription()->swap(['price_chat', 'price_original' => 2]);

上面的示例將添加新價格，但客戶直到下一個計費週期才會被收費。如果您想立即向客戶收費，您可以使用 swapAndInvoice 方法：

$user->subscription()->swapAndInvoice(['price_chat', 'price_original' => 2]);

您可以使用 swap 方法從訂閱中刪除價格，並省略您想要刪除的價格：

$user->subscription()->swap(['price_original' => 2]);

Warning

您不應該從訂閱中刪除最後一個價格。相反，您應該簡單地取消訂閱。

多個訂閱

Paddle 允許您的客戶同時擁有多個訂閱。例如，您可能經營一家提供游泳訂閱和舉重訂閱的健身房，每個訂閱可能有不同的定價。當然，客戶應該能夠訂閱其中一個或兩個計劃。

當您的應用程序創建訂閱時，您可以將訂閱的類型作為第二個參數提供給 subscribe 方法。類型可以是表示用戶啟動的訂閱類型的任何字符串：

use Illuminate\Http\Request;

Route::post('/swimming/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe($swimmingMonthly = 'pri_123', 'swimming');

    return view('billing', ['checkout' => $checkout]);
});

在此示例中，我們為客戶啟動了一個每月的游泳訂閱。但是，他們可能希望稍後切換到年度訂閱。在調整客戶的訂閱時，我們可以簡單地切換 swimming 訂閱上的價格：```

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

當然，您也可以完全取消訂閱：

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

暫停訂閱

要暫停訂閱，請在用戶的訂閱上調用 pause 方法：

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

當訂閱被暫停時，Cashier 將自動在您的資料庫中設置 paused_at 欄位。此欄位用於確定 paused 方法應何時開始返回 true。例如，如果客戶在3月1日暫停了訂閱，但訂閱原定於3月5日才會再次發生，paused 方法將繼續返回 false，直到3月5日。這是因為通常允許用戶在其計費週期結束前繼續使用應用程式。

默認情況下，暫停將在下一個計費間隔發生，以便客戶可以使用他們支付的剩餘時間。如果您想立即暫停訂閱，可以使用 pauseNow 方法：

$user->subscription()->pauseNow();

使用 pauseUntil 方法，您可以將訂閱暫停到特定時間：

$user->subscription()->pauseUntil(now()->addMonth());

或者，您可以使用 pauseNowUntil 方法立即暫停訂閱，直到給定的時間點：

$user->subscription()->pauseNowUntil(now()->addMonth());

您可以使用 onPausedGracePeriod 方法來確定用戶是否已暫停他們的訂閱，但仍處於「寬限期」：

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

要恢復暫停的訂閱，您可以在訂閱上調用 resume 方法：

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

Warning

在訂閱暫停時無法修改訂閱。如果您想切換到不同的計劃或更新數量，您必須先恢復訂閱。

取消訂閱

要取消訂閱，請在用戶的訂閱上調用 cancel 方法：


```php
$user->subscription()->cancel();

當訂閱被取消時，Cashier 將自動在您的資料庫中設置 ends_at 欄位。此欄位用於確定 subscribed 方法應何時開始返回 false。例如，如果客戶在 3 月 1 日取消訂閱，但訂閱原定於 3 月 5 日結束，subscribed 方法將繼續返回 true 直到 3 月 5 日。這是因為通常允許用戶在其計費週期結束前繼續使用應用程式。

您可以使用 onGracePeriod 方法來確定用戶是否已取消訂閱但仍處於「寬限期」：

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

如果您希望立即取消訂閱，可以在訂閱上調用 cancelNow 方法：

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

要阻止處於寬限期的訂閱取消，可以調用 stopCancelation 方法：

$user->subscription()->stopCancelation();

Warning

Paddle 的訂閱在取消後無法恢復。如果您的客戶希望恢復他們的訂閱，他們將需要創建一個新的訂閱。

訂閱試用

預先提供付款方式

如果您希望為客戶提供試用期，同時仍然在一開始收集付款方式信息，您應該在 Paddle 控制台上為客戶訂閱的價格設置試用時間。然後，像平常一樣啟動結帳會話：

use Illuminate\Http\Request;

Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()
        ->subscribe('pri_monthly')
        ->returnTo(route('home'));

    return view('billing', ['checkout' => $checkout]);
});

當您的應用程式接收到 subscription_created 事件時，Cashier 將在您應用程式的資料庫中的訂閱記錄上設置試用期結束日期，並指示 Paddle 在此日期之後開始向客戶收費。

Warning

如果客戶的訂閱在試用結束日期之前沒有取消，他們將在試用到期後立即收費，因此您應該確保通知用戶他們的試用結束日期。

您可以使用使用者實例的 onTrial 方法或訂閱實例的 onTrial 方法來確定用戶是否在試用期內。下面的兩個示例是等效的：

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

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

要確定現有試用是否已過期，您可以使用 hasExpiredTrial 方法：

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

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

要確定用戶是否在特定訂閱類型的試用期內，您可以將類型提供給 onTrial 或 hasExpiredTrial 方法：

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

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

沒有預先提供付款方式

如果您希望在不事先收集用戶的付款方式信息的情況下提供試用期，您可以將附加到用戶的客戶記錄上的 trial_ends_at 欄位設置為所需的試用結束日期。這通常在用戶註冊期間完成：

use App\Models\User;

$user = User::create([
    // ...
]);

$user->createAsCustomer([
    'trial_ends_at' => now()->addDays(10)
]);

Cashier 將此類試用稱為“通用試用”，因為它不附加到任何現有訂閱。如果當前日期未超過 trial_ends_at 的值，User 實例上的 onTrial 方法將返回 true：

if ($user->onTrial()) {
    // 用戶在試用期內...
}

當您準備為用戶創建實際訂閱時，您可以像平常一樣使用 subscribe 方法：

use Illuminate\Http\Request;

Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()
        ->subscribe('pri_monthly')
        ->returnTo(route('home'));

return view('billing', ['checkout' => $checkout]);
});

要檢索使用者的試用結束日期，您可以使用 trialEndsAt 方法。如果使用者正在進行試用，此方法將返回 Carbon 日期實例，如果不是，則返回 null。您也可以傳遞一個可選的訂閱類型參數，如果您想要為特定訂閱而不是默認訂閱獲取試用結束日期：

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

如果您希望確切知道使用者是否在其“通用”試用期內並且尚未創建實際訂閱，則可以使用 onGenericTrial 方法：

if ($user->onGenericTrial()) {
    // 使用者在其“通用”試用期內...
}

延長或啟動試用

您可以通過調用 extendTrial 方法並指定試用應該結束的時間來延長訂閱上的現有試用期：

$user->subscription()->extendTrial(now()->addDays(5));

或者，您可以通過在訂閱上調用 activate 方法結束其試用期來立即啟動訂閱：

$user->subscription()->activate();

處理 Paddle Webhooks

Paddle 可以通過 Webhooks 通知您的應用程序各種事件。默認情況下，Cashier 服務提供者註冊了一個指向 Cashier Webhook 控制器的路由。此控制器將處理所有傳入的 Webhook 請求。

默認情況下，此控制器將自動處理取消具有太多失敗收費、訂閱更新和付款方式更改的訂閱；但是，正如我們很快會發現的那樣，您可以擴展此控制器以處理您喜歡的任何 Paddle Webhook 事件。

為確保您的應用程序能夠處理 Paddle Webhooks，請確保在 Paddle 控制面板中配置 Webhook URL。默認情況下，Cashier 的 Webhook 控制器響應 /paddle/webhook URL 路徑。您應在 Paddle 控制面板中啟用的所有 Webhooks 的完整列表是：```

顧客已更新
交易已完成
交易已更新
訂閱已建立
訂閱已更新
訂閱已暫停
訂閱已取消

Warning

請確保使用 Cashier 包含的 webhook 簽名驗證中間件來保護傳入的請求。

Webhooks 和 CSRF 保護

由於 Paddle webhooks 需要繞過 Laravel 的 CSRF 保護，您應確保 Laravel 不會嘗試驗證傳入的 Paddle webhooks 的 CSRF 標記。為了實現這一點，您應該在應用程式的 bootstrap/app.php 檔案中排除 paddle/* 免於 CSRF 保護：

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'paddle/*',
    ]);
})

Webhooks 和本地開發

為了讓 Paddle 能夠在本地開發期間向您的應用程式發送 webhooks，您需要通過像 Ngrok 或 Expose 這樣的站點共享服務來公開您的應用程式。如果您正在使用 Laravel Sail 在本地開發您的應用程式，您可以使用 Sail 的站點共享命令。

定義 Webhook 事件處理程序

Cashier 自動處理了因付款失敗而導致的訂閱取消和其他常見的 Paddle webhooks。但是，如果您有其他想要處理的 webhook 事件，您可以通過監聽 Cashier 發佈的以下事件來執行：

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

這兩個事件都包含了 Paddle webhook 的完整載荷。例如，如果您希望處理 transaction.billed webhook，您可以註冊一個監聽器來處理該事件：

<?php

    namespace App\Listeners;

    use Laravel\Paddle\Events\WebhookReceived;

    class PaddleEventListener
    {
        /**
         * 處理接收到的 Paddle Webhooks。
         */
        public function handle(WebhookReceived $event): void
        {
            if ($event->payload['event_type'] === 'transaction.billed') {
                // 處理收到的事件...
            }
        }
    }

Cashier 也會針對接收到的 Webhook 類型發出事件。除了來自 Paddle 的完整載荷外，它們還包含用於處理 Webhook 的相關模型，例如可計費模型、訂閱或收據：

<div class="content-list" markdown="1">

- `Laravel\Paddle\Events\CustomerUpdated`
- `Laravel\Paddle\Events\TransactionCompleted`
- `Laravel\Paddle\Events\TransactionUpdated`
- `Laravel\Paddle\Events\SubscriptionCreated`
- `Laravel\Paddle\Events\SubscriptionUpdated`
- `Laravel\Paddle\Events\SubscriptionPaused`
- `Laravel\Paddle\Events\SubscriptionCanceled`

</div>

您還可以通過在應用程式的 `.env` 檔案中定義 `CASHIER_WEBHOOK` 環境變數來覆蓋默認的內建 Webhook 路由。此值應該是您 Webhook 路由的完整 URL，並且需要與您在 Paddle 控制面板中設定的 URL 相符：

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

驗證 Webhook 簽名

為了保護您的 Webhooks，您可以使用 Paddle 的 Webhook 簽名。為了方便起見，Cashier 自動包含一個中介層，用於驗證傳入的 Paddle Webhook 請求是否有效。

要啟用 Webhook 驗證，請確保在應用程式的 .env 檔案中定義了 PADDLE_WEBHOOK_SECRET 環境變數。Webhook 密鑰可以從您的 Paddle 帳戶儀表板中獲取。

單次收費

為產品收費

如果您想要為客戶啟動產品購買，您可以在可計費模型實例上使用 checkout 方法來為購買生成結帳會話。checkout 方法接受一個或多個價格 ID。如果需要，可以使用關聯陣列來提供正在購買的產品數量：


```blade
<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    購買
</x-paddle-button>

購買會話具有 customData 方法，允許您將任何自訂數據傳遞給底層交易創建。請參考 Paddle 文檔以了解在傳遞自定義數據時可用的選項：

$checkout = $user->checkout('pri_tshirt')
    ->customData([
        'custom_option' => $value,
    ]);

退款交易

退款交易將退還已在購買時使用的客戶付款方式的金額。如果您需要退款 Paddle 購買，您可以在 Cashier\Paddle\Transaction 模型上使用 refund 方法。此方法將接受原因作為第一個參數，一個或多個價格 ID 以及可選金額的關聯數組進行退款。您可以使用 transactions 方法檢索給定可計費模型的交易。

例如，假設我們想要為價格 pri_123 和 pri_456 退款特定交易。我們想要完全退款 pri_123，但只退還 pri_456 兩美元：

use App\Models\User;

$user = User::find(1);

$transaction = $user->transactions()->first();

$response = $transaction->refund('意外收費', [
    'pri_123', // 完全退款此價格...
    'pri_456' => 200, // 只部分退款此價格...
]);

上面的示例退款特定交易中的特定項目。如果您想要退款整個交易，只需提供一個原因：

<table>
    @foreach ($transactions as $transaction)
        <tr>
            <td>{{ $transaction->billed_at->toFormattedDateString() }}</td>
            <td>{{ $transaction->total() }}</td>
            <td>{{ $transaction->tax() }}</td>
            <td><a href="{{ route('download-invoice', $transaction->id) }}" target="_blank">Download</a></td>
        </tr>
    @endforeach
</table>

download-invoice 路由可能如下所示：

use Illuminate\Http\Request;
use Laravel\Paddle\Transaction;

Route::get('/download-invoice/{transaction}', function (Request $request, Transaction $transaction) {
    return $transaction->redirectToInvoicePdf();
})->name('download-invoice');


請參閱 [Paddle 有關信用的文件](https://developer.paddle.com/build/transactions/create-transaction-adjustments) 以獲取更多信息。

> [!WARNING]  
> 信用僅適用於手動收集的交易。自動收集的交易由 Paddle 自動記入。

<a name="transactions"></a>
## 交易

您可以通過 `transactions` 屬性輕鬆檢索可計費模型的交易數組：

    use App\Models\User;

    $user = User::find(1);

    $transactions = $user->transactions;

交易代表您產品和購買的付款，並附有發票。僅已完成的交易存儲在您的應用程式數據庫中。

當列出客戶的交易時，您可以使用交易實例的方法來顯示相關的付款信息。例如，您可能希望在表格中列出每筆交易，讓用戶輕鬆下載任何發票。 

<a name="crediting-transactions"></a>
### 信用交易

就像退款一樣，您也可以對交易進行信用。信用交易將資金添加到客戶的餘額中，以便將來用於購買。信用交易僅適用於手動收集的交易，而不適用於自動收集的交易（例如訂閱），因為 Paddle 會自動處理訂閱信用：

    $transaction = $user->transactions()->first();

    // 完全信用特定行項...
    $response = $transaction->credit('補償', 'pri_123');

有關更多信息，請參閱 [Paddle 有關信用的文件](https://developer.paddle.com/build/transactions/create-transaction-adjustments)。

> [!WARNING]  
> 信用僅適用於手動收集的交易。自動收集的交易由 Paddle 自動記入。

    $response = $transaction->refund('意外收費');

有關退款的更多信息，請參閱 [Paddle 的退款文件](https://developer.paddle.com/build/transactions/create-transaction-adjustments)。

### 過去和即將到來的付款

您可以使用 `lastPayment` 和 `nextPayment` 方法來檢索並顯示客戶的過去或即將到來的定期訂閱付款：

```php
use App\Models\User;

$user = User::find(1);

$subscription = $user->subscription();

$lastPayment = $subscription->lastPayment();
$nextPayment = $subscription->nextPayment();

這兩個方法將返回一個 Laravel\Paddle\Payment 實例；但是，當交易尚未被 Webhooks 同步時，lastPayment 會返回 null，而當計費週期結束時（例如當訂閱已被取消時），nextPayment 會返回 null：

下一次付款：{{ $nextPayment->amount() }} 到期日：{{ $nextPayment->date()->format('d/m/Y') }}

測試

在測試時，您應該手動測試您的計費流程，以確保您的整合按預期運作。

對於自動化測試，包括在 CI 環境中執行的測試，您可以使用 Laravel 的 HTTP Client 來模擬對 Paddle 發出的 HTTP 呼叫。儘管這並不測試來自 Paddle 的實際回應，但它提供了一種在不實際調用 Paddle API 的情況下測試應用程式的方法。

Files

cashier-paddle.md

Latest commit

History

cashier-paddle.md

File metadata and controls

Laravel Cashier (Paddle)

簡介

升級 Cashier

安裝

Paddle 測試環境

組態設定

可計費模型

API 金鑰

Paddle JS

貨幣設定

覆寫預設模型

快速入門

銷售產品

提供給 Paddle 結帳的元資料

銷售訂閱

建立一個訂閱中介層

允許客戶管理其計費計劃

結帳會話

疊加式結帳

手動呈現疊加結帳

內嵌式結帳

手動渲染內嵌結帳

訪客結帳

價格預覽

顧客價格預覽

折扣

顧客

顧客默認值

檢查訂閱狀態

取消訂閱狀態

逾期狀態

訂閱範圍

訂閱單次收費

更新付款資訊

變更方案

部分計費

訂閱數量

多產品訂閱的數量

具有多個產品的訂閱

多個訂閱

暫停訂閱

取消訂閱

訂閱試用

預先提供付款方式

沒有預先提供付款方式

延長或啟動試用

處理 Paddle Webhooks

Webhooks 和 CSRF 保護

Webhooks 和本地開發

定義 Webhook 事件處理程序

驗證 Webhook 簽名

單次收費

為產品收費

退款交易

測試