Laravel Cashier（Stripe）

• 簡介
• 升級 Cashier
• 安裝
• 配置
  • 可計費模型
  • API 金鑰
  • 貨幣配置
  • 稅務配置
  • 日誌
  • 使用自訂模型
• 快速入門
  • 銷售產品
  • 銷售訂閱
• 客戶
  • 檢索客戶
  • 建立客戶
  • 更新客戶
  • 餘額
  • 稅號
  • 與 Stripe 同步客戶資料
  • 計費入口
• 付款方式
• 訂閱
  • 建立訂閱
  • 檢查訂閱狀態
  • 更改價格
  • 訂閱數量
  • 取消訂閱
  • 恢復訂閱
• 訂閱試用
• 處理 Stripe Webhook
• 單次扣款
• 發票
• 結帳
• 處理付款失敗
• 測試

簡介

Laravel Cashier Stripe 為 Stripe 的訂閱計費服務提供了一個表達力強、流暢的介面。它處理了幾乎所有您不想編寫的樣板訂閱計費代碼。除了基本的訂閱管理之外，Cashier 還可以處理優惠券、訂閱方案轉換、訂閱「數量」、取消寬限期，甚至產生發票 PDF。

升級 Cashier

升級到新版本的 Cashier 時，務必仔細查閱升級指南。

[!WARNING] 為防止重大變更，Cashier 使用固定的 Stripe API 版本。Cashier 16 使用 Stripe API 版本 2025-06-30.basil。Stripe API 版本將在次要版本中更新，以便利用新的 Stripe 功能和改進。

安裝

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

composer require laravel/cashier

安裝套件後，使用 vendor:publish Artisan 命令發佈 Cashier 的遷移：

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

然後，執行 migrate 命令來建立所需的資料表：

php artisan migrate

要發佈 Cashier 的配置檔，請使用：

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

配置

可計費模型

在使用 Cashier 之前，您需要將 Billable trait 新增到您的使用者模型定義中。此 trait 提供了各種方法來允許您執行計費任務，例如建立訂閱、應用優惠券和更新付款方式：

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

API 金鑰

接下來，您應在 .env 檔案中配置您的 Stripe 金鑰：

STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...

貨幣配置

您可以透過設定 CASHIER_CURRENCY 環境變數來指定用於定價的貨幣，預設為 usd。

快速入門

銷售產品

Cashier 可以輕鬆處理一次性產品購買。當使用者想要購買產品時，使用 checkout 方法將他們重導向到 Stripe 託管的結帳頁面。Cashier 會自動處理成功的付款並觸發相關事件。

use Illuminate\Http\Request;
use Laravel\Cashier\Cashier;

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

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

銷售訂閱

要建立訂閱，您需要首先建立一個 Stripe 價格 ID。然後使用 newSubscription 方法開始訂閱：

use Illuminate\Http\Request;

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

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

客戶

檢索客戶

您可以使用 asStripeCustomer 方法檢索 Stripe 客戶物件：

$stripeCustomer = $user->asStripeCustomer();

建立客戶

當使用者開始首次付款時，Cashier 會自動在 Stripe 中建立客戶。如果您想手動建立客戶，可以使用 createAsStripeCustomer 方法。

付款方式

Cashier 提供了管理付款方式的完整方法。使用 createPaymentMethod、paymentMethods、defaultPaymentMethod、updateDefaultPaymentMethod、addPaymentMethod、deletePaymentMethod 等方法。付款方式通常使用 Stripe 的 Elements UI 元件在前端收集。

訂閱

建立訂閱

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

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

檢查訂閱狀態

您可以使用 subscribed 方法檢查使用者是否已訂閱：

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

Cashier 還提供了 onTrial、cancelled、onGracePeriod 等方法來檢查訂閱狀態。

更改價格

使用 swap 方法將訂閱變更為新價格：

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

取消訂閱

使用 cancel 方法取消訂閱：

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

恢復訂閱

如果訂閱仍在寬限期內，可以使用 resume 方法恢復訂閱：

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

訂閱試用

Cashier 支援在建立訂閱時提供試用期。使用 trialDays 方法指定試用天數，或使用 trialUntil 設定特定的結束日期。

處理 Stripe Webhook

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

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

然後在 Stripe 儀表板中配置 webhook URL。Cashier 處理諸如 customer.subscription.updated、charge.refunded、invoice.payment_succeeded 等常見 webhook。

單次扣款

使用 charge 方法對客戶進行單次扣款：

$user->charge(1000, 'payment_method_id');

金額以貨幣最小單位（美分）為單位。使用 refund 方法退款：

$user->refund($paymentIntentId);

發票

使用 invoices 方法檢索使用者的發票。使用 downloadInvoice 方法產生並下載發票 PDF。Cashier 使用 DomPDF 產生 PDF 檔案。

結帳

Cashier 支援 Stripe Checkout 來處理一次性付款和訂閱。checkout 方法返回一個結帳實例，可以將使用者重導向到 Stripe 託管的結帳頁面。

return $user->checkout(['price_standard' => 1])->redirect();

處理付款失敗

Cashier 包含內建支援來處理需要額外確認的付款，特別是由於強客戶認證（SCA）的要求。您可以使用 payment 方法檢索失敗付款的付款意圖並顯示確認頁面。

測試

Cashier 附帶了一個 Stripe「fake」實作，允許您在測試 Cashier 時定義預期行為。這允許您在不需要實際呼叫 Stripe API 的情況下測試您的程式碼：

use Laravel\Cashier\Http\Controllers\WebhookController;

$webhookController = new WebhookController;
$response = $webhookController->handleWebhook($requestPayload);