Laravel Cashier（Paddle）

• 簡介
• 升級 Cashier
• 安裝
  • Paddle 沙箱
• 配置
  • 可計費模型
  • API 金鑰
  • Paddle JS
  • 貨幣配置
  • 覆寫預設模型
• 快速入門
  • 銷售產品
  • 銷售訂閱
• 結帳工作階段
  • 覆蓋式結帳
  • 內嵌式結帳
  • 訪客結帳
• 價格預覽
• 客戶
• 訂閱
  • 建立訂閱
  • 檢查訂閱狀態
  • 更改方案
  • 訂閱數量
  • 暫停訂閱
  • 取消訂閱
• 訂閱試用
• 處理 Paddle 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

配置

可計費模型

將 Billable trait 新增到您的使用者模型：

use Laravel\Paddle\Billable;

class User extends Authenticatable
{
    use Billable;
}

API 金鑰

在 .env 中配置您的 Paddle API 金鑰：

PADDLE_CLIENT_ID=...
PADDLE_CLIENT_SECRET=...
PADDLE_WEBHOOK_SECRET=...

快速入門

銷售產品

使用 checkout 方法建立結帳工作階段，將使用者重導向到 Paddle 託管的結帳頁面：

use Illuminate\Http\Request;

Route::get('/product/{product}/checkout', function (Request $request, string $product) {
    $checkout = $request->user()->checkout($product);

    return $checkout->redirect();
});

銷售訂閱

使用 newSubscription 方法建立訂閱：

use Illuminate\Http\Request;

Route::post('/subscribe', function (Request $request) {
    $subscription = $request->user()->newSubscription('default', 'pri_monthly')
        ->create();

    return redirect('/home');
});

結帳工作階段

Cashier Paddle 支援覆蓋式結帳（Overlay Checkout）和內嵌式結帳（Inline Checkout）。覆蓋式結帳會打開一個 Paddle 託管的模式視窗，而內嵌式結帳則將結帳表單嵌入到您的頁面中。

客戶

使用 createAsCustomer 方法在 Paddle 中建立客戶記錄。使用 customer 方法檢索客戶資訊。

訂閱

建立訂閱

使用 newSubscription 方法建立新訂閱。第一個參數是訂閱的名稱，第二個參數是 Paddle 中的價格 ID：

$user->newSubscription('default', 'pri_monthly')->create();

檢查訂閱狀態

使用 subscribed、onTrial、paused、cancelled、onGracePeriod 等方法檢查訂閱狀態。

更改方案

使用 swap 方法將訂閱轉換到新價格：

$user->subscription('default')->swap('pri_yearly');

暫停訂閱

使用 pause 方法暫停訂閱：

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

取消訂閱

使用 cancel 方法取消訂閱：

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

訂閱試用

Cashier Paddle 支援試用期。使用 trialDays 設定試用天數，或使用 trialUntil 設定特定的結束日期。

處理 Paddle Webhook

Cashier 自動處理 Paddle webhook。發佈 webhook 路由：

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

然後在 Paddle 儀表板中配置 webhook URL。Cashier 處理諸如 subscription.created、subscription.updated、transaction.completed 等事件。

單次扣款

使用 charge 方法對客戶進行單次扣款。使用 Paddle 的產品價格 ID 來建立一次性付款。

交易

使用 transactions 方法檢索客戶的交易記錄。使用 downloadInvoice 方法下載發票。

測試

測試時，Cashier Paddle 提供了一個模擬實作。您可以透過設定相應的環境變數來使用 Paddle 的沙箱環境進行測試。