Laravel Cashier (Stripe)

• 简介
• 升级 Cashier
• 安装
• 配置
  • 可计费模型
  • API 密钥
  • 货币配置
  • 税务配置
  • 日志记录
  • 使用自定义模型
• 快速入门
  • 销售产品
  • 销售订阅
• 客户
  • 检索客户
  • 创建客户
  • 更新客户
  • 余额
  • 税号
  • 与 Stripe 同步客户数据
  • 账单门户
• 支付方式
  • 存储支付方式
  • 检索支付方式
  • 支付方式存在性
  • 更新默认支付方式
  • 添加支付方式
  • 删除支付方式
• 订阅
  • 创建订阅
  • 检查订阅状态
  • 变更价格
  • 订阅数量
  • 多产品订阅
  • 多订阅
  • 按使用量计费
  • 订阅税费
  • 订阅锚定日期
  • 取消订阅
  • 恢复订阅
• 订阅试用期
  • 预先提供支付方式
  • 无需预先提供支付方式
  • 延长试用期
• 处理 Stripe Webhooks
  • 定义 Webhook 事件处理器
  • 验证 Webhook 签名
• 单次扣款
  • 简单扣款
  • 带发票的扣款
  • 创建支付意图
  • 退款
• 发票
  • 检索发票
  • 即将生成的发票
  • 预览订阅发票
  • 生成发票 PDF
• 结账
  • 产品结账
  • 单次扣款结账
  • 订阅结账
  • 收集税号
  • 访客结账
• 处理支付失败
  • 确认支付
• 强客户认证 (SCA)
  • 需要额外确认的支付
  • 离线支付通知
• Stripe SDK
• 测试

简介

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"

然后，运行数据库迁移：

php artisan migrate

Cashier 的迁移会向你的 users 表添加几列。它们还会创建一个新的 subscriptions 表来保存所有客户的订阅，以及一个 subscription_items 表用于包含多个价格的订阅。

如果需要，你也可以使用 vendor:publish Artisan 命令发布 Cashier 的配置文件：

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

最后，为确保 Cashier 能正确处理所有 Stripe 事件，请记得配置 Cashier 的 webhook 处理。

WARNING

Stripe 建议用于存储 Stripe 标识符的任何列都应区分大小写。因此，在使用 MySQL 时，应确保 stripe_id 列的排序规则设置为 utf8_bin。有关此问题的更多信息，请参阅 Stripe 文档。

配置

可计费模型

在使用 Cashier 之前，请将 Billable trait 添加到你的可计费模型定义中。通常，这将是 App\Models\User 模型。此 trait 提供了各种方法，允许你执行常见的计费任务，例如创建订阅、应用优惠券和更新支付方式信息：

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Cashier 假定你的可计费模型将是 Laravel 自带的 App\Models\User 类。如果你想更改此项，可以通过 useCustomerModel 方法指定不同的模型。此方法通常应在你的 AppServiceProvider 类的 boot 方法中调用：

use App\Models\Cashier\User;
use Laravel\Cashier\Cashier;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Cashier::useCustomerModel(User::class);
}

WARNING

如果你使用的不是 Laravel 提供的 App\Models\User 模型，则需要发布并修改提供的 Cashier 迁移，以匹配你的替代模型的表名。

API 密钥

接下来，你应该在应用程序的 .env 文件中配置你的 Stripe API 密钥。你可以从 Stripe 控制面板中获取 Stripe API 密钥：

STRIPE_KEY=你的-stripe-公钥
STRIPE_SECRET=你的-stripe-密钥
STRIPE_WEBHOOK_SECRET=你的-stripe-webhook-密钥

WARNING

你应该确保在应用程序的 .env 文件中定义了 STRIPE_WEBHOOK_SECRET 环境变量，因为此变量用于确保传入的 webhook 实际上来自 Stripe。

货币配置

默认的 Cashier 货币是美元 (USD)。你可以通过在应用程序的 .env 文件中设置 CASHIER_CURRENCY 环境变量来更改默认货币：

CASHIER_CURRENCY=eur

除了配置 Cashier 的货币外，你还可以指定在发票上显示货币值时要使用的区域设置。Cashier 内部使用 PHP 的 NumberFormatter 类 来设置货币区域：

CASHIER_CURRENCY_LOCALE=nl_BE

WARNING

要使用除 en 以外的区域，请确保在服务器上安装并配置了 ext-intl PHP 扩展。

税务配置

借助 Stripe Tax，可以自动计算 Stripe 生成的所有发票的税费。你可以通过在应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中调用 calculateTaxes 方法来启用自动税费计算：

use Laravel\Cashier\Cashier;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Cashier::calculateTaxes();
}

一旦启用税费计算，任何新订阅和生成的一次性发票都将接收自动税费计算。

为使此功能正常工作，客户的账单详细信息（例如客户姓名、地址和税号）需要同步到 Stripe。你可以使用 Cashier 提供的客户数据同步和税号方法来实现此目的。

日志记录

Cashier 允许你指定在记录致命 Stripe 错误时使用的日志通道。你可以通过在应用程序的 .env 文件中定义 CASHIER_LOGGER 环境变量来指定日志通道：

CASHIER_LOGGER=stack

对 Stripe 的 API 调用生成的异常将通过应用程序的默认日志通道记录。

使用自定义模型

你可以自由扩展 Cashier 内部使用的模型，方法是定义自己的模型并扩展相应的 Cashier 模型：

use Laravel\Cashier\Subscription as CashierSubscription;

class Subscription extends CashierSubscription
{
    // ...
}

定义模型后，你可以通过 Laravel\Cashier\Cashier 类指示 Cashier 使用你的自定义模型。通常，你应该在应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中告知 Cashier 你的自定义模型：

use App\Models\Cashier\Subscription;
use App\Models\Cashier\SubscriptionItem;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useSubscriptionItemModel(SubscriptionItem::class);
}

快速入门

销售产品

NOTE

在使用 Stripe Checkout 之前，你应该在 Stripe 仪表板中定义具有固定价格的产品。此外，你应该配置 Cashier 的 webhook 处理。

通过你的应用程序提供产品和订阅计费可能会令人生畏。但是，借助 Cashier 和 Stripe Checkout，你可以轻松构建现代、强大的支付集成。

要向客户收取非经常性的一次性产品费用，我们将利用 Cashier 将客户引导至 Stripe Checkout，在那里他们将提供付款详细信息并确认购买。一旦通过 Checkout 完成付款，客户将被重定向到你应用程序中选择的成功 URL：

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', 'checkout.success')->name('checkout-success');
Route::view('/checkout/cancel', 'checkout.cancel')->name('checkout-cancel');

如上面的示例所示，我们将利用 Cashier 提供的 checkout 方法，将客户重定向到给定“价格标识符”的 Stripe Checkout。使用 Stripe 时，“价格”指的是特定产品的定义价格。

如有必要，checkout 方法将自动在 Stripe 中创建客户，并将该 Stripe 客户记录连接到应用程序数据库中的相应用户。完成结账会话后，客户将被重定向到专用的成功或取消页面，你可以在其中向客户显示信息性消息。

向 Stripe Checkout 提供元数据

销售产品时，通常会通过你自己的应用程序定义的 Cart 和 Order 模型来跟踪已完成订单和已购买的产品。当将客户重定向到 Stripe Checkout 以完成购买时，你可能需要提供一个现有的订单标识符，以便在客户被重定向回你的应用程序时，可以将完成的购买与相应的订单关联起来。

为此，你可以向 checkout 方法提供一个 metadata 数组。假设当用户开始结账流程时，我们的应用程序中会创建一个待处理的 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 数组将订单的 ID 提供给 Stripe Checkout 会话。最后，我们在 Checkout 成功路由中添加了 CHECKOUT_SESSION_ID 模板变量。当 Stripe 将客户重定向回你的应用程序时，此模板变量将自动填充为 Checkout 会话 ID。

接下来，让我们构建 Checkout 成功路由。这是用户在通过 Stripe Checkout 完成购买后将重定向到的路由。在此路由中，我们可以检索 Stripe Checkout 会话 ID 和关联的 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');

请参阅 Stripe 文档，了解有关 Checkout 会话对象包含的数据的更多信息。

销售订阅

NOTE

在使用 Stripe Checkout 之前，你应该在 Stripe 仪表板中定义具有固定价格的产品。此外，你应该配置 Cashier 的 webhook 处理。

通过你的应用程序提供产品和订阅计费可能会令人生畏。但是，借助 Cashier 和 Stripe Checkout，你可以轻松构建现代、强大的支付集成。

要了解如何使用 Cashier 和 Stripe Checkout 销售订阅，让我们考虑一个简单的订阅服务场景，该服务提供月度（price_basic_monthly）和年度（price_basic_yearly）基础计划。这两个价格可以在我们的 Stripe 仪表板中归入一个“基础”产品（pro_basic）。此外，我们的订阅服务可能提供专家计划 pro_expert。

首先，让我们了解客户如何订阅我们的服务。当然，你可以想象客户可能会在我们应用程序的定价页面上点击基础计划的“订阅”按钮。该按钮或链接应将用户引导至一个 Laravel 路由，该路由为他们选择的计划创建 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 方法的 URL。要知道他们的订阅何时真正开始（因为某些支付方式需要几秒钟来处理），我们还需要配置 Cashier 的 webhook 处理。

现在客户可以开始订阅了，我们需要限制应用程序的某些部分，以便只有订阅用户才能访问它们。当然，我们始终可以通过 Cashier 的 Billable trait 提供的 subscribed 方法来确定用户的当前订阅状态：

@if ($user->subscribed())
    <p>您已订阅。</p>
@endif

我们甚至可以轻松确定用户是否订阅了特定产品或价格：

@if ($user->subscribedToProduct('pro_basic'))
    <p>您已订阅我们的基础产品。</p>
@endif

@if ($user->subscribedToPrice('price_basic_monthly'))
    <p>您已订阅我们的月度基础计划。</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('/billing');
        }

        return $next($request);
    }
}

定义中间件后，你可以将其分配给路由：

use App\Http\Middleware\Subscribed;

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

允许客户管理其账单计划

当然，客户可能希望将其订阅计划更改为另一个产品或“层级”。实现此目的的最简单方法是将客户引导至 Stripe 的客户账单门户，该门户提供了一个托管的用户界面，允许客户下载发票、更新支付方式以及更改订阅计划。

首先，在你的应用程序中定义一个链接或按钮，将用户引导至我们将用来启动账单门户会话的 Laravel 路由：

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

接下来，让我们定义启动 Stripe 客户账单门户会话并将用户重定向到门户的路由。redirectToBillingPortal 方法接受用户在退出门户时应返回的 URL：

use Illuminate\Http\Request;

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

NOTE

只要你配置了 Cashier 的 webhook 处理，Cashier 就会通过检查来自 Stripe 的传入 webhook 自动保持应用程序中与 Cashier 相关的数据库表的同步。因此，例如，当用户通过 Stripe 的客户账单门户取消订阅时，Cashier 将接收到相应的 webhook 并在你的应用程序数据库中将该订阅标记为“已取消”。

客户

检索客户

你可以使用 Cashier::findBillable 方法通过客户的 Stripe ID 检索客户。此方法将返回可计费模型的实例：

use Laravel\Cashier\Cashier;

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

创建客户

有时，你可能希望在不开始订阅的情况下创建 Stripe 客户。你可以使用 createAsStripeCustomer 方法来实现：

$stripeCustomer = $user->createAsStripeCustomer();

一旦在 Stripe 中创建了客户，你可以稍后开始订阅。你可以提供一个可选的 $options 数组，以传入任何额外的 Stripe API 支持的客户创建参数：

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

如果你想返回可计费模型的 Stripe 客户对象，可以使用 asStripeCustomer 方法：

$stripeCustomer = $user->asStripeCustomer();

如果你想检索给定可计费模型的 Stripe 客户对象，但不确定该可计费模型是否已经是 Stripe 中的客户，可以使用 createOrGetStripeCustomer 方法。如果 Stripe 中尚不存在，此方法将在 Stripe 中创建一个新客户：

$stripeCustomer = $user->createOrGetStripeCustomer();

更新客户

有时，你可能希望直接使用附加信息更新 Stripe 客户。你可以使用 updateStripeCustomer 方法来实现。此方法接受一个 Stripe API 支持的客户更新选项 数组：

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

余额

Stripe 允许你贷记或借记客户的“余额”。随后，此余额将计入新发票的贷项或借项。要检查客户的总余额，你可以使用可计费模型上可用的 balance 方法。balance 方法将返回以客户货币表示的余额的格式化字符串表示：

$balance = $user->balance();

要贷记客户余额，你可以向 creditBalance 方法提供一个值。如果需要，你还可以提供描述：

$user->creditBalance(500, '优质客户充值。');

向 debitBalance 方法提供一个值将借记客户余额：

$user->debitBalance(300, '不良使用惩罚。');

applyBalance 方法将为客户创建新的客户余额交易。你可以使用 balanceTransactions 方法检索这些交易记录，这在为客户提供贷项和借项日志以供查看时可能很有用：

// 检索所有交易...
$transactions = $user->balanceTransactions();

foreach ($transactions as $transaction) {
    // 交易金额...
    $amount = $transaction->amount(); // $2.31

    // 可用时检索相关发票...
    $invoice = $transaction->invoice();
}

税号

Cashier 提供了一种简便的方法来管理客户的税号。例如，taxIds 方法可用于检索分配给客户的所有税号的集合：

$taxIds = $user->taxIds();

你还可以通过其标识符检索客户的特定税号：

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

你可以通过向 createTaxId 方法提供一个有效的类型和值来创建一个新的税号：

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

createTaxId 方法将立即将增值税号添加到客户的账户。Stripe 也会对增值税号进行验证；但是，这是一个异步过程。你可以通过订阅 customer.tax_id.updated webhook 事件并检查增值税号的 verification 参数来接收验证更新的通知。有关处理 webhook 的更多信息，请查阅关于定义 webhook 处理器的文档。

你可以使用 deleteTaxId 方法删除税号：

$user->deleteTaxId('txi_belgium');

与 Stripe 同步客户数据

通常，当你的应用程序用户更新其姓名、电子邮件地址或 Stripe 也存储的其他信息时，你应将更新告知 Stripe。通过这样做，Stripe 的信息副本将与你的应用程序保持同步。

要自动执行此操作，你可以在可计费模型上定义一个事件监听器，该监听器响应模型的 updated 事件。然后，在你的事件监听器中，你可以在模型上调用 syncStripeCustomerDetails 方法：

use App\Models\User;
use function Illuminate\Events\queueable;

/**
 * 模型的“booted”方法。
 */
protected static function booted(): void
{
    static::updated(queueable(function (User $customer) {
        if ($customer->hasStripeId()) {
            $customer->syncStripeCustomerDetails();
        }
    }));
}

现在，每次更新你的客户模型时，其信息都将与 Stripe 同步。为方便起见，Cashier 会在首次创建客户时自动将客户信息与 Stripe 同步。

你可以通过重写 Cashier 提供的多种方法来自定义用于将客户信息同步到 Stripe 的列。例如，你可以重写 stripeName 方法来自定义当 Cashier 将客户信息同步到 Stripe 时应视为客户“名称”的属性：

/**
 * 获取应同步到 Stripe 的客户名称。
 */
public function stripeName(): string|null
{
    return $this->company_name;
}

类似地，你可以重写 stripeEmail、stripePhone（最多 20 个字符）、stripeAddress 和 stripePreferredLocales 方法。这些方法将在更新 Stripe 客户对象时将信息同步到相应的客户参数。如果你想完全控制客户信息同步过程，可以重写 syncStripeCustomerDetails 方法。

账单门户

Stripe 提供一种简单的方法来设置账单门户，以便你的客户可以管理其订阅、支付方式并查看其账单历史。你可以通过从控制器或路由在可计费模型上调用 redirectToBillingPortal 方法将用户重定向到账单门户：

use Illuminate\Http\Request;

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

默认情况下，当用户完成管理其订阅后，他们将能够通过 Stripe 账单门户中的链接返回到你的应用程序的 home 路由。你可以通过将自定义 URL 作为参数传递给 redirectToBillingPortal 方法来提供用户应返回的自定义 URL：

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 来安全地收集客户的支付方式详细信息。“Setup Intent” 向 Stripe 表明意图向客户的支付方式收费。Cashier 的 Billable trait 包含 createSetupIntent 方法，可以轻松创建新的 Setup Intent。你应该从将呈现收集客户支付方式详细信息表单的路由或控制器调用此方法：

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

创建 Setup Intent 并将其传递给视图后，你应该将其密钥附加到将要收集支付方式的元素上。例如，考虑这个“更新支付方式”表单：

<input id="card-holder-name" type="text">

<!-- Stripe Elements 占位符 -->
<div id="card-element"></div>

<button id="card-button" data-secret="{{ $intent->client_secret }}">
    更新支付方式
</button>

接下来，可以使用 Stripe.js 库将 Stripe Element 附加到表单，并安全地收集客户的支付详细信息：

<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) {
        // 向用户显示 "error.message"...
    } else {
        // 卡片已成功验证...
    }
});

卡片通过 Stripe 验证后，你可以将生成的 setupIntent.payment_method 标识符传递给你的 Laravel 应用程序，在那里它可以附加到客户。支付方式可以作为新的支付方式添加，也可以用于更新默认支付方式。你也可以立即使用支付方式标识符创建新订阅。

NOTE

如果你想了解有关 Setup Intents 和收集客户付款详细信息的更多信息，请查看 Stripe 提供的此概述。

用于单次扣款的支付方式

当然，在对客户的支付方式执行单次扣款时，我们只需要使用一次支付方式标识符。由于 Stripe 的限制，你不能将客户存储的默认支付方式用于单次扣款。你必须允许客户使用 Stripe.js 库输入其支付方式详细信息。例如，考虑以下表单：

<input id="card-holder-name" type="text">

<!-- Stripe Elements 占位符 -->
<div id="card-element"></div>

<button id="card-button">
    处理付款
</button>

定义这样的表单后，可以使用 Stripe.js 库将 Stripe Element 附加到表单，并安全地收集客户的支付详细信息：

<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) {
        // 向用户显示 "error.message"...
    } else {
        // 卡片已成功验证...
    }
});

如果卡片验证成功，你可以将 paymentMethod.id 传递给你的 Laravel 应用程序并处理单次扣款。

检索支付方式

可计费模型实例上的 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();

WARNING

客户的默认支付方式只能用于开票和创建新订阅。由于 Stripe 施加的限制，它不能用于单次扣款。

添加支付方式

要添加新的支付方式，你可以在可计费模型上调用 addPaymentMethod 方法，并传递支付方式标识符：

$user->addPaymentMethod($paymentMethod);

NOTE

要了解如何检索支付方式标识符，请查阅支付方式存储文档。

删除支付方式

要删除支付方式，你可以在要删除的 Laravel\Cashier\PaymentMethod 实例上调用 delete 方法：

$paymentMethod->delete();

deletePaymentMethod 方法将从可计费模型中删除特定的支付方式：

$user->deletePaymentMethod('pm_visa');

deletePaymentMethods 方法将删除可计费模型的所有支付方式信息：

$user->deletePaymentMethods();

默认情况下，此方法将删除所有类型的支付方式。要删除特定类型的支付方式，你可以将 type 作为参数传递给该方法：

$user->deletePaymentMethods('sepa_debit');

WARNING

如果用户有有效的订阅，你的应用程序不应允许他们删除其默认支付方式。

订阅

订阅提供了一种为你的客户设置定期付款的方式。由 Cashier 管理的 Stripe 订阅支持多种订阅价格、订阅数量、试用期等。

创建订阅

要创建订阅，首先检索你的可计费模型的实例，该实例通常是 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 支付方式标识符或 Stripe PaymentMethod 对象，它将开始订阅，并用可计费模型的 Stripe 客户 ID 和其他相关账单信息更新你的数据库。

WARNING

直接将支付方式标识符传递给 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' => '一些额外信息。'],
]);

优惠券

如果你想在创建订阅时应用优惠券，可以使用 withCoupon 方法：

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

或者，如果你想应用 Stripe 促销代码，可以使用 withPromotionCode 方法：

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

给定的促销代码 ID 应该是分配给促销代码的 Stripe API ID，而不是面向客户的促销代码。如果需要根据给定的面向客户的促销代码查找促销代码 ID，可以使用 findPromotionCode 方法：

// 通过面向客户的代码查找促销代码 ID...
$promotionCode = $user->findPromotionCode('SUMMERSALE');

// 通过面向客户的代码查找有效的促销代码 ID...
$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
{
    /**
     * 处理传入的请求。
     *
     * @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')) {
            // 此用户不是付费客户...
            return redirect('/billing');
        }

        return $next($request);
    }
}

如果你想确定用户是否仍在试用期内，可以使用 onTrial 方法。此方法可用于确定你是否应向用户显示他们仍在试用期的警告：

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

subscribedToProduct 方法可用于根据给定的 Stripe 产品标识符确定用户是否订阅了给定产品。在 Stripe 中，产品是价格的集合。在此示例中，我们将确定用户的 default 订阅是否有效订阅了应用程序的“高级”产品。给定的 Stripe 产品标识符应对应于 Stripe 仪表板中你的某个产品的标识符：

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

通过向 subscribedToProduct 方法传递一个数组，你可以确定用户的 default 订阅是否有效订阅了应用程序的“基础”或“高级”产品：

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

subscribedToPrice 方法可用于确定客户的订阅是否对应于给定的价格 ID：

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

recurring 方法可用于确定用户当前是否已订阅且不再处于试用期：

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

WARNING

如果用户有两个相同类型的订阅，subscription 方法将始终返回最新的订阅。例如，一个用户可能有两个类型为 default 的订阅记录；但是，其中一个订阅可能是旧的、已过期的订阅，而另一个是当前的、有效的订阅。将始终返回最新的订阅，而较旧的订阅将保留在数据库中供历史查阅。

已取消订阅状态

要确定用户曾经是有效的订阅者但已取消订阅，你可以使用 canceled 方法：

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

你还可以确定用户是否已取消订阅，但仍处于“宽限期”，直到订阅完全到期。例如，如果用户在 3 月 5 日取消了一个原定于 3 月 10 日到期的订阅，则该用户在 3 月 10 日之前处于“宽限期”。请注意，在此期间 subscribed 方法仍然返回 true：

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

要确定用户是否已取消订阅且不再处于“宽限期”，可以使用 ended 方法：

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

不完整和逾期状态

如果订阅在创建后需要二次支付操作，则订阅将被标记为 incomplete。订阅状态存储在 Cashier 的 subscriptions 数据库表的 stripe_status 列中。

类似地，如果在转换价格时需要二次支付操作，则订阅将被标记为 past_due。当你的订阅处于这两种状态之一时，它将不会处于活动状态，直到客户确认其付款。确定订阅是否有未完成的付款可以通过可计费模型或订阅实例上的 hasIncompletePayment 方法来完成：

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

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

当订阅有未完成的付款时，你应将用户引导至 Cashier 的付款确认页面，并传递 latestPayment 标识符。你可以使用订阅实例上可用的 latestPayment 方法检索此标识符：

<a href="{{ route('cashier.payment', $subscription->latestPayment()->id) }}">
    请确认您的付款。
</a>

如果你希望在订阅处于 past_due 或 incomplete 状态时仍将其视为活动状态，可以使用 Cashier 提供的 keepPastDueSubscriptionsActive 和 keepIncompleteSubscriptionsActive 方法。通常，这些方法应在你的 App\Providers\AppServiceProvider 的 register 方法中调用：

use Laravel\Cashier\Cashier;

/**
 * 注册任何应用程序服务。
 */
public function register(): void
{
    Cashier::keepPastDueSubscriptionsActive();
    Cashier::keepIncompleteSubscriptionsActive();
}

WARNING

当订阅处于 incomplete 状态时，在付款确认之前无法更改它。因此，当订阅处于 incomplete 状态时，swap 和 updateQuantity 方法将抛出异常。

订阅作用域

大多数订阅状态也可以作为查询作用域使用，以便你可以轻松查询数据库中处于给定状态的订阅：

// 获取所有有效订阅...
$subscriptions = Subscription::query()->active()->get();

// 获取用户的所有已取消订阅...
$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 价格的标识符传递给 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 文档。

WARNING

在 swapAndInvoice 方法之前执行 noProrate 方法对按比例分配没有影响。发票将始终发出。

订阅数量

有时订阅会受到“数量”的影响。例如，一个项目管理应用程序可能每个项目每月收费 10 美元。你可以使用 incrementQuantity 和 decrementQuantity 方法轻松增加或减少你的订阅数量：

use App\Models\User;

$user = User::find(1);

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

// 给订阅的当前数量加五...
$user->subscription('default')->incrementQuantity(5);

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

// 给订阅的当前数量减五...
$user->subscription('default')->decrementQuantity(5);

或者，你可以使用 updateQuantity 方法设置特定数量：

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

noProrate 方法可用于在不按比例分配费用的情况下更新订阅的数量：

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

有关订阅数量的更多信息，请查阅 Stripe 文档。

多产品订阅的数量

如果你的订阅是多产品订阅，则应将要增加或减少数量的价格的 ID 作为第二个参数传递给 increment / decrement 方法：

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

多产品订阅

多产品订阅允许你将多个计费产品分配给单个订阅。例如，假设你正在构建一个客户服务“帮助台”应用程序，其基础订阅价格为每月 10 美元，但提供每月额外 15 美元的实时聊天附加产品。多产品订阅的信息存储在 Cashier 的 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');

WARNING

你不能移除订阅上的最后一个价格。相反，你应该直接取消订阅。

转换价格

你还可以更改附加到多产品订阅的价格。例如，假设一个客户有一个带有 price_chat 附加产品的 price_basic 订阅，并且你想将客户从 price_basic 升级到 price_pro 价格：

use App\Models\User;

$user = User::find(1);

$user->subscription('default')->swap(['price_pro', 'price_chat']);

执行上面的示例时，具有 price_basic 的底层订阅项目将被删除，而具有 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');

数量

如果你想更新单个订阅价格上的数量，可以通过将价格的 ID 作为额外参数传递给方法，使用现有的数量方法来实现：

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

WARNING

当订阅有多个价格时，Subscription 模型上的 stripe_price 和 quantity 属性将为 null。要访问单个价格属性，你应该使用 Subscription 模型上可用的 items 关系。

订阅项目

当订阅有多个价格时，它将有多个订阅“项目”存储在你的数据库的 subscription_items 表中。你可以通过订阅上的 items 关系访问它们：

use App\Models\User;

$user = User::find(1);

$subscriptionItem = $user->subscription('default')->items->first();

// 检索特定项目的 Stripe 价格和数量...
$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 仪表板中创建一个具有按使用量计费模型和计量器的新产品。创建计量器后，存储关联的事件名称和计量器 ID，你将需要它们来报告和检索使用量。然后，使用 meteredPrice 方法将计量价格 ID 添加到客户订阅：

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 报告他们的使用量，以便可以准确地向他们收费。要报告计量事件的使用量，你可以在你的 Billable 模型上使用 reportMeterEvent 方法：

$user = User::find(1);

$user->reportMeterEvent('emails-sent');

默认情况下，将向计费周期添加一个“使用量”数量 1。或者，你可以传递要添加到客户计费周期使用量中的特定“使用量”数量：

$user = User::find(1);

$user->reportMeterEvent('emails-sent', quantity: 15);

要检索客户针对计量器的事件摘要，你可以使用 Billable 实例的 meterEventSummaries 方法：

$user = User::find(1);

$meterUsage = $user->meterEventSummaries($meterId);

$meterUsage->first()->aggregated_value // 10

请参阅 Stripe 的计量事件摘要对象文档以获取有关计量事件摘要的更多信息。

要列出所有计量器，你可以使用 Billable 实例的 meters 方法：

$user = User::find(1);

$user->meters();

订阅税费

WARNING

无需手动计算税率，你可以使用 Stripe Tax 自动计算税费

要指定用户在订阅上支付的税率，你应该在你的可计费模型上实现 taxRates 方法，并返回一个包含 Stripe 税率 ID 的数组。你可以在你的 Stripe 仪表板中定义这些税率：

/**
 * 应适用于客户订阅的税率。
 *
 * @return array<int, string>
 */
public function taxRates(): array
{
    return ['txr_id'];
}

taxRates 方法使你能够在逐个客户的基础上应用税率，这对于跨越多个国家和税率的用户群可能很有帮助。

如果你提供多产品订阅，可以通过在你的可计费模型上实现 priceTaxRates 方法来为每个价格定义不同的税率：

/**
 * 应适用于客户订阅的税率。
 *
 * @return array<string, array<int, string>>
 */
public function priceTaxRates(): array
{
    return [
        'price_monthly' => ['txr_id'],
    ];
}

WARNING

taxRates 方法仅适用于订阅费用。如果你使用 Cashier 进行“一次性”扣款，则需要在那时手动指定税率。

同步税率

当更改 taxRates 方法返回的硬编码税率 ID 时，用户任何现有订阅的税务设置将保持不变。如果你想使用新的 taxRates 值更新现有订阅的税额，应在用户的订阅实例上调用 syncTaxRates 方法：

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

这也会同步多产品订阅的任何项目税率。如果你的应用程序提供多产品订阅，应确保你的可计费模型实现了上面讨论的 priceTaxRates 方法。

免税

Cashier 还提供了 isNotTaxExempt、isTaxExempt 和 reverseChargeApplies 方法来确定客户是否免税。这些方法将调用 Stripe API 来确定客户的免税状态：

use App\Models\User;

$user = User::find(1);

$user->isTaxExempt();
$user->isNotTaxExempt();
$user->reverseChargeApplies();

WARNING

这些方法也可用于任何 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();

取消订阅后，Cashier 将自动在你的 subscriptions 数据库表中设置 ends_at 列。此列用于知道 subscribed 方法何时应开始返回 false。

例如，如果客户在 3 月 1 日取消订阅，但订阅原定于 3 月 5 日才结束，subscribed 方法将一直返回 true 直到 3 月 5 日。这样做是因为通常允许用户在计费周期结束前继续使用应用程序。

你可以使用 onGracePeriod 方法确定用户是否已取消订阅但仍处于“宽限期”：

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

如果你想立即取消订阅，请调用用户订阅上的 cancelNow 方法：

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

如果你想立即取消订阅并对任何剩余的未开票计量使用量或新的/待处理的按比例分配发票项目开票，请调用用户订阅上的 cancelNowAndInvoice 方法：

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

你也可以选择在特定时间点取消订阅：

$user->subscription('default')->cancelAt(
    now()->plus(days: 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 中为价格配置的任何默认试用期。

WARNING

如果客户的订阅在试用期结束日期前未取消，他们将在试用期到期后立即被收费，因此你应确保通知用户其试用期结束日期。

trialUntil 方法允许你提供一个 DateTime 实例，指定试用期应何时结束：

use Illuminate\Support\Carbon;

$user->newSubscription('default', 'price_monthly')
    ->trialUntil(Carbon::now()->plus(days: 10))
    ->create($paymentMethod);

你可以使用用户实例的 onTrial 方法或订阅实例的 onTrial 方法来确定用户是否处于试用期内。以下两个示例是等效的：

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

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

你可以使用 endTrial 方法立即结束订阅试用期：

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

要确定现有试用期是否已过期，你可以使用 hasExpiredTrial 方法：

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

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

在 Stripe / Cashier 中定义试用天数

你可以选择在 Stripe 仪表板中定义你的价格接收多少试用天数，或者始终使用 Cashier 显式传递它们。如果你选择在 Stripe 中定义价格的试用天数，应注意新订阅（包括过去有过订阅的客户的新订阅）将始终接收试用期，除非你显式调用 skipTrial() 方法。

无需预先提供支付方式

如果你想在不预先收集用户支付方式信息的情况下提供试用期，可以在用户记录上设置 trial_ends_at 列为你希望的试用期结束日期。这通常在用户注册期间完成：

use App\Models\User;

$user = User::create([
    // ...
    'trial_ends_at' => now()->plus(days: 10),
]);

WARNING

确保在你的可计费模型的类定义为 trial_ends_at 属性添加一个日期转换。

Cashier 将这种类型的试用称为“通用试用”，因为它不附加到任何现有订阅。如果当前日期未超过 trial_ends_at 的值，可计费模型实例上的 onTrial 方法将返回 true：

if ($user->onTrial()) {
    // 用户处于试用期内...
}

一旦你准备好为用户创建实际订阅，可以像往常一样使用 newSubscription 方法：

$user = User::find(1);

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

要检索用户的试用期结束日期，可以使用 trialEndsAt 方法。如果用户处于试用期，此方法将返回一个 Carbon 日期实例；如果不处于试用期，则返回 null。如果你希望获取除默认订阅之外的特定订阅的试用期结束日期，还可以传递一个可选的订阅类型参数：

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

如果你特别想知道用户是否处于“通用”试用期且尚未创建实际订阅，还可以使用 onGenericTrial 方法：

if ($user->onGenericTrial()) {
    // 用户处于“通用”试用期内...
}

延长试用期

extendTrial 方法允许你在订阅创建后延长订阅的试用期。如果试用期已过并且客户已经开始为订阅付费，你仍然可以为他们提供延长的试用期。在试用期内度过的时间将从客户的下一次发票中扣除：

use App\Models\User;

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

// 从现在起 7 天后结束试用...
$subscription->extendTrial(
    now()->plus(days: 7)
);

// 给试用期增加额外的 5 天...
$subscription->extendTrial(
    $subscription->trial_ends_at->plus(days: 5)
);

处理 Stripe Webhooks

NOTE

在本地开发期间，你可以使用 Stripe CLI 来帮助测试 webhook。

Stripe 可以通过 webhook 通知你的应用程序各种事件。默认情况下，Cashier 服务提供器会自动注册一个指向 Cashier webhook 控制器的路由。此控制器将处理所有传入的 webhook 请求。

默认情况下，Cashier webhook 控制器将自动处理取消因失败扣款次数过多（由你的 Stripe 设置定义）的订阅、客户更新、客户删除、订阅更新和支付方式更改；但是，我们很快就会发现，你可以扩展此控制器以处理任何你喜欢的 Stripe webhook 事件。

为确保你的应用程序能够处理 Stripe webhooks，请务必在 Stripe 控制面板中配置 webhook URL。默认情况下，Cashier 的 webhook 控制器响应 /stripe/webhook URL 路径。你应该在 Stripe 控制面板中启用的所有 webhook 的完整列表是：

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• customer.updated
• customer.deleted
• payment_method.automatically_updated
• invoice.payment_action_required
• invoice.payment_succeeded

为方便起见，Cashier 包含一个 cashier:webhook Artisan 命令。此命令将在 Stripe 中创建一个监听 Cashier 所需的所有事件的 webhook：

php artisan cashier:webhook

默认情况下，创建的 webhook 将指向由 APP_URL 环境变量和 Cashier 附带的 cashier.webhook 路由定义的 URL。如果你想使用不同的 URL，可以在调用命令时提供 --url 选项：

php artisan cashier:webhook --url "https://example.com/stripe/webhook"

创建的 webhook 将使用与你 Cashier 版本兼容的 Stripe API 版本。如果你想使用不同的 Stripe 版本，可以提供 --api-version 选项：

php artisan cashier:webhook --api-version="2019-12-03"

创建后，webhook 将立即生效。如果你想创建 webhook 但使其处于禁用状态，直到你准备好，可以在调用命令时提供 --disabled 选项：

php artisan cashier:webhook --disabled

WARNING

确保使用 Cashier 附带的 webhook 签名验证中间件保护传入的 Stripe webhook 请求。

Webhooks 和 CSRF 保护

由于 Stripe webhooks 需要绕过 Laravel 的 CSRF 保护，你应该确保 Laravel 不会尝试验证传入的 Stripe webhooks 的 CSRF 令牌。为此，你应该在你的应用程序的 bootstrap/app.php 文件中将 stripe/* 从 CSRF 保护中排除：

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

定义 Webhook 事件处理器

Cashier 自动处理因失败扣款导致的订阅取消和其他常见的 Stripe webhook 事件。但是，如果你有其他想要处理的 webhook 事件，可以通过监听 Cashier 分发的以下事件来实现：

• Laravel\Cashier\Events\WebhookReceived
• Laravel\Cashier\Events\WebhookHandled

这两个事件都包含 Stripe webhook 的完整负载。例如，如果你想处理 invoice.payment_succeeded webhook，可以注册一个监听器来处理该事件：

<?php

namespace App\Listeners;

use Laravel\Cashier\Events\WebhookReceived;

class StripeEventListener
{
    /**
     * 处理接收到的 Stripe webhooks。
     */
    public function handle(WebhookReceived $event): void
    {
        if ($event->payload['type'] === 'invoice.payment_succeeded') {
            // 处理传入的事件...
        }
    }
}

验证 Webhook 签名

为了保护你的 webhooks，你可以使用 Stripe 的 webhook 签名。为方便起见，Cashier 自动包含一个中间件，用于验证传入的 Stripe webhook 请求是否有效。

要启用 webhook 验证，请确保在你的应用程序的 .env 文件中设置了 STRIPE_WEBHOOK_SECRET 环境变量。webhook secret 可以从你的 Stripe 账户仪表板中检索。

单次扣款

简单扣款

如果你想对客户进行一次性收费，可以在可计费模型实例上使用 charge 方法。你需要提供一个支付方式标识符作为 charge 方法的第二个参数：

use Illuminate\Http\Request;

Route::post('/purchase', function (Request $request) {
    $stripeCharge = $request->user()->charge(
        100, $request->paymentMethodId
    );

    // ...
});

charge 方法接受一个数组作为其第三个参数，允许你传递任何你希望传递给底层 Stripe 扣款创建的选项。有关创建扣款时可用的选项的更多信息，请参阅 Stripe 文档：

$user->charge(100, $paymentMethod, [
    'custom_option' => $value,
]);

你也可以在没有底层客户或用户的情况下使用 charge 方法。为此，请在你的应用程序的可计费模型的新实例上调用 charge 方法：

use App\Models\User;

$stripeCharge = (new User)->charge(100, $paymentMethod);

如果扣款失败，charge 方法将抛出异常。如果扣款成功，将从该方法返回一个 Laravel\Cashier\Payment 实例：

try {
    $payment = $user->charge(100, $paymentMethod);
} catch (Exception $e) {
    // ...
}

WARNING

charge 方法以你的应用程序使用的货币的最小单位接受支付金额。例如，如果客户以美元支付，金额应以美分指定。

带发票的扣款

有时你可能需要进行一次性扣款并向你的客户提供 PDF 发票。invoicePrice 方法可以让你做到这一点。例如，让我们向客户开具五件新 T 恤的发票：

$user->invoicePrice('price_tshirt', 5);

发票将立即从用户的默认支付方式中扣除。invoicePrice 方法也接受一个数组作为其第三个参数。此数组包含发票项目的账单选项。该方法接受的第四个参数也是一个数组，应包含发票本身的账单选项：

$user->invoicePrice('price_tshirt', 5, [
    'discounts' => [
        ['coupon' => 'SUMMER21SALE']
    ],
], [
    'default_tax_rates' => ['txr_id'],
]);

与 invoicePrice 类似，你可以使用 tabPrice 方法通过将项目添加到客户的“标签”然后向客户开具发票来为多个项目（每个发票最多 250 个项目）创建一次性扣款。例如，我们可以为五件衬衫和两个杯子向客户开具发票：

$user->tabPrice('price_tshirt', 5);
$user->tabPrice('price_mug', 2);
$user->invoice();

或者，你可以使用 invoiceFor 方法对客户的默认支付方式进行“一次性”扣款：

$user->invoiceFor('一次性费用', 500);

尽管 invoiceFor 方法可供你使用，但建议你使用 invoicePrice 和 tabPrice 方法以及预定义的价格。通过这样做，你将在 Stripe 仪表板中获得关于按产品销售的更好的分析和数据。

WARNING

invoice、invoicePrice 和 invoiceFor 方法将创建一个 Stripe 发票，该发票将在失败的计费尝试时重试。如果你不希望发票重试失败的扣款，你需要在第一次失败扣款后使用 Stripe API 关闭它们。

创建支付意图

你可以通过在可计费模型实例上调用 pay 方法来创建一个新的 Stripe 支付意图。调用此方法将创建一个包装在 Laravel\Cashier\Payment 实例中的支付意图：

use Illuminate\Http\Request;

Route::post('/pay', function (Request $request) {
    $payment = $request->user()->pay(
        $request->get('amount')
    );

    return $payment->client_secret;
});

创建支付意图后，你可以将客户端密钥返回给你的应用程序前端，以便用户可以在其浏览器中完成支付。要了解有关使用 Stripe 支付意图构建完整支付流程的更多信息，请查阅 Stripe 文档。

使用 pay 方法时，你的 Stripe 仪表板中启用的默认支付方式将可供客户使用。或者，如果你只允许使用某些特定的支付方式，可以使用 payWith 方法：

use Illuminate\Http\Request;

Route::post('/pay', function (Request $request) {
    $payment = $request->user()->payWith(
        $request->get('amount'), ['card', 'bancontact']
    );

    return $payment->client_secret;
});

WARNING

pay 和 payWith 方法以你的应用程序使用的货币的最小单位接受支付金额。例如，如果客户以美元支付，金额应以美分指定。

退款

如果你需要退款 Stripe 扣款，可以使用 refund 方法。此方法接受 Stripe 支付意图 ID 作为其第一个参数：

$payment = $user->charge(100, $paymentMethodId);

$user->refund($payment->id);

发票

检索发票

你可以使用 invoices 方法轻松检索可计费模型的发票数组。invoices 方法返回一个 Laravel\Cashier\Invoice 实例的集合：

$invoices = $user->invoices();

如果你想在结果中包含待处理的发票，可以使用 invoicesIncludingPending 方法：

$invoices = $user->invoicesIncludingPending();

你可以使用 findInvoice 方法通过其 ID 检索特定发票：

$invoice = $user->findInvoice($invoiceId);

显示发票信息

在列出客户的发票时，你可以使用发票的方法来显示相关的发票信息。例如，你可能希望在表格中列出每张发票，允许用户轻松下载其中任何一张：

<table>
    @foreach ($invoices as $invoice)
        <tr>
            <td>{{ $invoice->date()->toFormattedDateString() }}</td>
            <td>{{ $invoice->total() }}</td>
            <td><a href="/user/invoice/{{ $invoice->id }}">下载</a></td>
        </tr>
    @endforeach
</table>

即将生成的发票

要检索客户的即将生成的发票，可以使用 upcomingInvoice 方法：

$invoice = $user->upcomingInvoice();

类似地，如果客户有多个订阅，你也可以检索特定订阅的即将生成的发票：

$invoice = $user->subscription('default')->upcomingInvoice();

预览订阅发票

使用 previewInvoice 方法，你可以在进行价格更改之前预览发票。这将允许你确定在进行给定价格更改时客户的发票将是什么样子：

$invoice = $user->subscription('default')->previewInvoice('price_yearly');

你可以向 previewInvoice 方法传递一个价格数组，以预览具有多个新价格的发票：

$invoice = $user->subscription('default')->previewInvoice(['price_yearly', 'price_metered']);

生成发票 PDF

在生成发票 PDF 之前，你应该使用 Composer 安装 Dompdf 库，它是 Cashier 的默认发票渲染器：

composer require dompdf/dompdf

在路由或控制器中，你可以使用 downloadInvoice 方法来生成给定发票的 PDF 下载。此方法将自动生成下载发票所需的适当 HTTP 响应：

use Illuminate\Http\Request;

Route::get('/user/invoice/{invoice}', function (Request $request, string $invoiceId) {
    return $request->user()->downloadInvoice($invoiceId);
});

默认情况下，发票上的所有数据都来自 Stripe 中存储的客户和发票数据。文件名基于你的 app.name 配置值。但是，你可以通过向 downloadInvoice 方法提供数组作为第二个参数来自定义其中一些数据。此数组允许你自定义信息，例如你的公司和产品详细信息：

return $request->user()->downloadInvoice($invoiceId, [
    'vendor' => '你的公司',
    'product' => '你的产品',
    'street' => '主街 1 号',
    'location' => '2000 安特卫普，比利时',
    'phone' => '+32 499 00 00 00',
    'email' => 'info@example.com',
    'url' => 'https://example.com',
    'vendorVat' => 'BE123456789',
]);

downloadInvoice 方法还允许通过其第三个参数自定义文件名。此文件名将自动以 .pdf 为后缀：

return $request->user()->downloadInvoice($invoiceId, [], 'my-invoice');

自定义发票渲染器

Cashier 还允许使用自定义发票渲染器。默认情况下，Cashier 使用 DompdfInvoiceRenderer 实现，它利用 dompdf PHP 库生成 Cashier 的发票。但是，你可以通过实现 Laravel\Cashier\Contracts\InvoiceRenderer 接口来使用任何你想要的渲染器。例如，你可能希望使用对第三方 PDF 渲染服务的 API 调用来渲染发票 PDF：

use Illuminate\Support\Facades\Http;
use Laravel\Cashier\Contracts\InvoiceRenderer;
use Laravel\Cashier\Invoice;

class ApiInvoiceRenderer implements InvoiceRenderer
{
    /**
     * 渲染给定的发票并返回原始 PDF 字节。
     */
    public function render(Invoice $invoice, array $data = [], array $options = []): string
    {
        $html = $invoice->view($data)->render();

        return Http::get('https://example.com/html-to-pdf', ['html' => $html])->get()->body();
    }
}

实现发票渲染器契约后，你应该在应用程序的 config/cashier.php 配置文件中更新 cashier.invoices.renderer 配置值。此配置值应设置为你自定义渲染器实现的类名。

结账

Cashier Stripe 也支持 Stripe Checkout。Stripe Checkout 通过提供一个预构建的托管支付页面，消除了实现自定义页面来接受支付的痛苦。

以下文档包含有关如何开始将 Stripe Checkout 与 Cashier 结合使用的信息。要了解有关 Stripe Checkout 的更多信息，你还应考虑查阅 Stripe 自己的 Checkout 文档。

产品结账

你可以对在 Stripe 仪表板中创建的现有产品执行结账，方法是在可计费模型上使用 checkout 方法。checkout 方法将启动一个新的 Stripe Checkout 会话。默认情况下，你需要传递一个 Stripe 价格 ID：

use Illuminate\Http\Request;

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

如果需要，你还可以指定产品数量：

use Illuminate\Http\Request;

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

当客户访问此路由时，他们将被重定向到 Stripe 的 Checkout 页面。默认情况下，当用户成功完成或取消购买时，他们将被重定向到你的 home 路由位置，但你可以使用 success_url 和 cancel_url 选项指定自定义回调 URL：

use Illuminate\Http\Request;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout(['price_tshirt' => 1], [
        'success_url' => route('your-success-route'),
        'cancel_url' => route('your-cancel-route'),
    ]);
});

在定义你的 success_url 结账选项时，你可以指示 Stripe 在调用你的 URL 时将结账会话 ID 作为查询字符串参数添加。为此，请将文字字符串 {CHECKOUT_SESSION_ID} 添加到你的 success_url 查询字符串中。Stripe 将用实际的结账会话 ID 替换此占位符：

use Illuminate\Http\Request;
use Stripe\Checkout\Session;
use Stripe\Customer;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout(['price_tshirt' => 1], [
        'success_url' => route('checkout-success').'?session_id={CHECKOUT_SESSION_ID}',
        'cancel_url' => route('checkout-cancel'),
    ]);
});

Route::get('/checkout-success', function (Request $request) {
    $checkoutSession = $request->user()->stripe()->checkout->sessions->retrieve($request->get('session_id'));

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

促销代码

默认情况下，Stripe Checkout 不允许用户可兑换的促销代码。幸运的是，有一种简单的方法可以为你的 Checkout 页面启用它们。为此，你可以调用 allowPromotionCodes 方法：

use Illuminate\Http\Request;

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

单次扣款结账

你也可以为尚未在你的 Stripe 仪表板中创建的临时产品执行简单扣款。为此，你可以在可计费模型上使用 checkoutCharge 方法，并向其传递一个可扣款金额、产品名称和可选数量。当客户访问此路由时，他们将被重定向到 Stripe 的 Checkout 页面：

use Illuminate\Http\Request;

Route::get('/charge-checkout', function (Request $request) {
    return $request->user()->checkoutCharge(1200, 'T-Shirt', 5);
});

WARNING

使用 checkoutCharge 方法时，Stripe 将始终在你的 Stripe 仪表板中创建一个新产品和价格。因此，我们建议你在 Stripe 仪表板中预先创建产品，并使用 checkout 方法。

订阅结账

WARNING

使用 Stripe Checkout 进行订阅需要你在 Stripe 仪表板中启用 customer.subscription.created webhook。此 webhook 将在你的数据库中创建订阅记录并存储所有相关的订阅项目。

你也可以使用 Stripe Checkout 来启动订阅。使用 Cashier 的订阅构建器方法定义你的订阅后，你可以调用 checkout 方法。当客户访问此路由时，他们将被重定向到 Stripe 的 Checkout 页面：

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->checkout();
});

就像产品结账一样，你可以自定义成功和取消 URL：

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->checkout([
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

当然，你也可以为订阅结账启用促销代码：

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->allowPromotionCodes()
        ->checkout();
});

WARNING

不幸的是，Stripe Checkout 在启动订阅时不支持所有订阅账单选项。在订阅构建器上使用 anchorBillingCycleOn 方法、设置按比例分配行为或设置支付行为在 Stripe Checkout 会话期间不会产生任何影响。请查阅 Stripe Checkout 会话 API 文档以查看哪些参数可用。

Stripe Checkout 和试用期

当然，你可以在构建将通过 Stripe Checkout 完成的订阅时定义试用期：

$checkout = Auth::user()->newSubscription('default', 'price_monthly')
    ->trialDays(3)
    ->checkout();

但是，试用期必须至少为 48 小时，这是 Stripe Checkout 支持的最短试用时间。

订阅和 Webhooks

请记住，Stripe 和 Cashier 通过 webhook 更新订阅状态，因此在客户输入其支付信息后返回应用程序时，订阅可能尚未激活。为了处理这种情况，你可能希望显示一条消息，告知用户其付款或订阅正在处理中。

收集税号

Checkout 也支持收集客户的税号。要在结账会话中启用此功能，请在创建会话时调用 collectTaxIds 方法：

$checkout = $user->collectTaxIds()->checkout('price_tshirt');

调用此方法时，客户将可以使用一个新的复选框，允许他们表明是否作为公司购买。如果是，他们将有机会提供其税号。

WARNING

如果你已经在应用程序的服务提供器中配置了自动税费收集，则此功能将自动启用，无需调用 collectTaxIds 方法。

访客结账

使用 Checkout::guest 方法，你可以为没有“账户”的应用程序访客启动结账会话：

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

Route::get('/product-checkout', function (Request $request) {
    return Checkout::guest()->create('price_tshirt', [
        'success_url' => route('your-success-route'),
        'cancel_url' => route('your-cancel-route'),
    ]);
});

与为现有用户创建结账会话类似，你可以利用 Laravel\Cashier\CheckoutBuilder 实例上可用的其他方法来自定义访客结账会话：

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

Route::get('/product-checkout', function (Request $request) {
    return Checkout::guest()
        ->withPromotionCode('promo-code')
        ->create('price_tshirt', [
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

访客结账完成后，Stripe 可以调度一个 checkout.session.completed webhook 事件，因此请确保配置你的 Stripe webhook 以将此事件实际发送到你的应用程序。在 Stripe 仪表板中启用 webhook 后，你可以使用 Cashier 处理该 webhook。webhook 负载中包含的对象将是一个结账对象，你可以检查它以完成客户的订单。

处理支付失败

有时，订阅或单次扣款的支付可能会失败。发生这种情况时，Cashier 将抛出一个 Laravel\Cashier\Exceptions\IncompletePayment 异常，通知你发生了这种情况。捕获此异常后，你有两个选项来决定如何继续。

首先，你可以将客户重定向到 Cashier 附带的专用付款确认页面。此页面已经有一个通过 Cashier 的服务提供器注册的关联命名路由。因此，你可以捕获 IncompletePayment 异常并将用户重定向到付款确认页面：

use Laravel\Cashier\Exceptions\IncompletePayment;

try {
    $subscription = $user->newSubscription('default', 'price_monthly')
        ->create($paymentMethod);
} catch (IncompletePayment $exception) {
    return redirect()->route(
        'cashier.payment',
        [$exception->payment->id, 'redirect' => route('home')]
    );
}

在付款确认页面上，客户将被提示再次输入其信用卡信息并执行 Stripe 要求的任何额外操作，例如“3D Secure”确认。确认付款后，用户将被重定向到上面指定的 redirect 参数提供的 URL。重定向时，message（字符串）和 success（整数）查询字符串变量将被添加到 URL。付款页面目前支持以下支付方式类型：

• 信用卡
• Alipay
• Bancontact
• BECS Direct Debit
• EPS
• Giropay
• iDEAL
• SEPA Direct Debit

或者，你可以让 Stripe 为你处理付款确认。在这种情况下，你可以在你的 Stripe 仪表板中设置 Stripe 的自动账单邮件，而不是重定向到付款确认页面。但是，如果捕获到 IncompletePayment 异常，你仍应通知用户他们将收到一封包含进一步付款确认说明的电子邮件。

对于使用 Billable trait 的模型上的以下方法，可能会抛出支付异常：charge、invoiceFor 和 invoice。在与订阅交互时，SubscriptionBuilder 上的 create 方法，以及 Subscription 和 SubscriptionItem 模型上的 incrementAndInvoice 和 swapAndInvoice 方法可能会抛出未完成支付异常。

确定现有订阅是否有未完成的支付可以通过可计费模型或订阅实例上的 hasIncompletePayment 方法来完成：

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

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

你可以通过检查异常实例上的 payment 属性来获取未完成支付的具体状态：

use Laravel\Cashier\Exceptions\IncompletePayment;

try {
    $user->charge(1000, 'pm_card_threeDSecure2Required');
} catch (IncompletePayment $exception) {
    // 获取支付意图状态...
    $exception->payment->status;

    // 检查特定条件...
    if ($exception->payment->requiresPaymentMethod()) {
        // ...
    } elseif ($exception->payment->requiresConfirmation()) {
        // ...
    }
}

确认支付

某些支付方式需要额外数据才能确认支付。例如，SEPA 支付方式在支付过程中需要额外的“授权书”数据。你可以使用 withPaymentConfirmationOptions 方法将这些数据提供给 Cashier：

$subscription->withPaymentConfirmationOptions([
    'mandate_data' => '...',
])->swap('price_xxx');

你可以查阅 Stripe API 文档以查看确认支付时接受的所有选项。

强客户认证 (SCA)

如果你的企业或你的一个客户位于欧洲，你需要遵守欧盟的强客户认证 (SCA) 规定。这些规定由欧盟于 2019 年 9 月实施，以防止支付欺诈。幸运的是，Stripe 和 Cashier 已准备好构建符合 SCA 的应用程序。

WARNING

在开始之前，请查阅 Stripe 关于 PSD2 和 SCA 的指南以及他们关于新的 SCA API 的文档。

需要额外确认的支付

SCA 规定通常需要额外的验证来确认和处理支付。发生这种情况时，Cashier 将抛出一个 Laravel\Cashier\Exceptions\IncompletePayment 异常，通知你需要额外的验证。有关如何处理这些异常的更多信息，请参阅关于处理支付失败的文档。

Stripe 或 Cashier 呈现的付款确认屏幕可能针对特定银行或卡发行者的支付流程进行了定制，并且可能包括额外的卡片确认、临时小额扣款、单独的设备认证或其他形式的验证。

不完整和逾期状态

当支付需要额外确认时，订阅将保持 incomplete 或 past_due 状态，如其 stripe_status 数据库列所示。一旦支付确认完成，并且 Stripe 通过 webhook 通知你的应用程序其完成，Cashier 将自动激活客户的订阅。

有关 incomplete 和 past_due 状态的更多信息，请参阅我们关于这些状态的附加文档。

离线支付通知

由于 SCA 规定要求客户即使在订阅有效时也偶尔验证其支付详细信息，因此当需要离线支付确认时，Cashier 可以向客户发送通知。例如，这可能在订阅续订时发生。Cashier 的支付通知可以通过将 CASHIER_PAYMENT_NOTIFICATION 环境变量设置为一个通知类来启用。默认情况下，此通知是禁用的。当然，Cashier 包含一个你可以为此目的使用的通知类，但如果需要，你也可以自由提供自己的通知类：

CASHIER_PAYMENT_NOTIFICATION=Laravel\Cashier\Notifications\ConfirmPayment

为确保离线支付确认通知被送达，请验证是否为你的应用程序配置了 Stripe webhooks 并且在你的 Stripe 仪表板中启用了 invoice.payment_action_required webhook。此外，你的 Billable 模型也应使用 Laravel 的 Illuminate\Notifications\Notifiable trait。

WARNING

即使客户在手动进行需要额外确认的支付时，也会发送通知。不幸的是，Stripe 无法知道支付是手动进行的还是“离线的”。但是，如果客户在已经确认付款后访问付款页面，他们将简单地看到一条“付款成功”的消息。客户不会被允许意外地两次确认同一笔支付并招致意外的第二次扣款。

Stripe SDK

Cashier 的许多对象都是 Stripe SDK 对象的包装器。如果你想直接与 Stripe 对象交互，可以使用 asStripe 方法方便地检索它们：

$stripeSubscription = $subscription->asStripeSubscription();

$stripeSubscription->application_fee_percent = 5;

$stripeSubscription->save();

你也可以使用 updateStripeSubscription 方法直接更新 Stripe 订阅：

$subscription->updateStripeSubscription(['application_fee_percent' => 5]);

如果你想直接使用 Stripe\StripeClient 客户端，可以在 Cashier 类上调用 stripe 方法。例如，你可以使用此方法访问 StripeClient 实例并从你的 Stripe 账户中检索价格列表：

use Laravel\Cashier\Cashier;

$prices = Cashier::stripe()->prices->all();

测试

在测试使用 Cashier 的应用程序时，你可以模拟对 Stripe API 的实际 HTTP 请求；但这需要你部分地重新实现 Cashier 自己的行为。因此，我们建议允许你的测试命中实际的 Stripe API。虽然这较慢，但它能提供更多信心，让你的应用程序按预期工作，并且任何慢速测试都可以放在它们自己的 Pest / PHPUnit 测试组中。

测试时，请记住 Cashier 本身已经有一个很棒的测试套件，因此你应该只关注测试自己应用程序的订阅和支付流程，而不是每个底层的 Cashier 行为。

首先，将你的 Stripe 密钥的测试版本添加到你的 phpunit.xml 文件中：

<env name="STRIPE_SECRET" value="sk_test_<your-key>"/>

现在，每当你在测试中与 Cashier 交互时，它将向你的 Stripe 测试环境发送实际的 API 请求。为方便起见，你应该在你的 Stripe 测试账户中预先填充你可能在测试期间使用的订阅/价格。

NOTE

为了测试各种计费场景，例如信用卡拒绝和失败，你可以使用 Stripe 提供的大量测试卡号和令牌。