Laravel Cashier

介绍
升级 Cashier
安装
配置
客户
支付方式
订阅
订阅试用
处理 Stripe Webhooks
单次收费
发票
- 生成发票 PDF
强客户认证 (SCA)
- 需要额外确认的付款
- 离线支付通知
Stripe SDK

介绍

Laravel Cashier 提供了一个流畅的接口来使用 Stripe 的订阅计费服务。它处理了几乎所有你不想写的订阅计费样板代码。除了基本的订阅管理，Cashier 还可以处理优惠券、交换订阅、订阅“数量”、取消宽限期，甚至生成发票 PDF。

升级 Cashier

在升级到新版本的 Cashier 时，务必仔细查看升级指南。

NOTE

为了防止破坏性更改，Cashier 使用固定的 Stripe API 版本。Cashier 10.1 使用 Stripe API 版本 2019-08-14。Stripe API 版本将在小版本更新中更新，以便利用新的 Stripe 功能和改进。

安装

首先，通过 Composer 安装 Stripe 的 Cashier 包：

php

composer require laravel/cashier

NOTE

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

数据库迁移

Cashier 服务提供者注册了自己的数据库迁移目录，因此在安装包后记得迁移数据库。Cashier 迁移将向你的 users 表添加几个列，并创建一个新的 subscriptions 表来保存所有客户的订阅：

php

php artisan migrate

如果你需要覆盖 Cashier 包附带的迁移，可以使用 vendor:publish Artisan 命令发布它们：

php

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

如果你想完全阻止 Cashier 的迁移运行，可以使用 Cashier 提供的 ignoreMigrations。通常，这个方法应该在 AppServiceProvider 的 register 方法中调用：

php

use Laravel\Cashier\Cashier;

Cashier::ignoreMigrations();

NOTE

Stripe 建议用于存储 Stripe 标识符的任何列都应区分大小写。因此，你应该确保 stripe_id 列的排序规则在 MySQL 中设置为例如 utf8_bin。更多信息可以在 Stripe 文档中找到。

配置

计费模型

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

php

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Cashier 假定你的计费模型将是 Laravel 附带的 App\User 类。如果你希望更改此设置，可以在 .env 文件中指定不同的模型：

php

CASHIER_MODEL=App\User

NOTE

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

API 密钥

接下来，你应该在 .env 文件中配置你的 Stripe 密钥。你可以从 Stripe 控制面板中检索你的 Stripe API 密钥。

php

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

货币配置

默认的 Cashier 货币是美元 (USD)。你可以通过设置 CASHIER_CURRENCY 环境变量来更改默认货币：

php

CASHIER_CURRENCY=eur

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

php

CASHIER_CURRENCY_LOCALE=nl_BE

NOTE

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

日志记录

Cashier 允许你指定用于记录所有 Stripe 相关异常的日志通道。你可以使用 CASHIER_LOGGER 环境变量指定日志通道：

php

CASHIER_LOGGER=stack

客户

检索客户

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

php

use Laravel\Cashier\Cashier;

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

创建客户

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

php

$stripeCustomer = $user->createAsStripeCustomer();

一旦客户在 Stripe 中创建，你可以在稍后开始订阅。你还可以使用可选的 $options 数组传递任何其他由 Stripe API 支持的参数：

php

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

如果你想在计费实体已经是 Stripe 中的客户时返回客户对象，你也可以使用 createOrGetStripeCustomer 方法。

php

$stripeCustomer = $user->createOrGetStripeCustomer();

更新客户

有时，你可能希望直接使用附加信息更新 Stripe 客户。你可以使用 updateStripeCustomer 方法实现这一点：

php

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

自定义电子邮件地址

默认情况下，Cashier 将使用你的计费模型上的 email 属性在 Stripe 中创建客户。你可以使用 stripeEmail 方法覆盖此设置：

php

/**
 * 获取用于在 Stripe 中创建客户的电子邮件地址。
 *
 * @return string|null
 */
public function stripeEmail()
{
    return $this->email;
}

你也可以选择返回 null，因为在 Stripe 中创建客户时不需要电子邮件地址。如果你不提供电子邮件地址，Stripe 中的功能如催款邮件、付款失败提醒和其他电子邮件相关功能将不可用。

支付方式

存储支付方式

为了使用 Stripe 创建订阅或执行“一次性”收费，你需要存储支付方式并从 Stripe 检索其标识符。实现这一点的方法取决于你计划将支付方式用于订阅还是单次收费，因此我们将在下面分别进行检查。

订阅的支付方式

在将信用卡存储到客户以供将来使用时，必须使用 Stripe Setup Intents API 来安全地收集客户的支付方式详细信息。“Setup Intent”表示 Stripe 将要对客户的支付方式进行收费。Cashier 的 Billable trait 包含 createSetupIntent 方法，可以轻松创建新的 Setup Intent。你应该从将呈现收集客户支付方式详细信息的表单的路由或控制器中调用此方法：

php

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

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

php

<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 元素附加到表单并安全地收集客户的支付详细信息：

php

<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 检索安全的“支付方式标识符”：

php

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 库输入他们的支付方式详细信息。例如，考虑以下表单：

php

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

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

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

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

php

<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 检索安全的“支付方式标识符”：

php

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 实例的集合：

php

$paymentMethods = $user->paymentMethods();

要检索默认支付方式，可以使用 defaultPaymentMethod 方法：

php

$paymentMethod = $user->defaultPaymentMethod();

你还可以使用 findPaymentMethod 方法检索计费模型拥有的特定支付方式：

php

$paymentMethod = $user->findPaymentMethod($paymentMethodId);

确定用户是否有支付方式

要确定计费模型是否已将支付方式附加到其帐户，请使用 hasPaymentMethod 方法：

php

if ($user->hasPaymentMethod()) {
    //
}

更新默认支付方式

updateDefaultPaymentMethod 方法可用于更新客户的默认支付方式信息。此方法接受 Stripe 支付方式标识符，并将新支付方式指定为默认计费支付方式：

php

$user->updateDefaultPaymentMethod($paymentMethod);

要将你的默认支付方式信息与 Stripe 中客户的默认支付方式信息同步，可以使用 updateDefaultPaymentMethodFromStripe 方法：

php

$user->updateDefaultPaymentMethodFromStripe();

NOTE

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

添加支付方式

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

php

$user->addPaymentMethod($paymentMethod);

NOTE

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

删除支付方式

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

php

$paymentMethod->delete();

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

php

$user->deletePaymentMethods();

NOTE

如果用户有一个活动的订阅，你应该阻止他们删除其默认支付方式。

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

php

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

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

php

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

不完整和逾期状态

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

同样，如果在交换计划时需要二次付款操作，订阅将被标记为 past_due。当你的订阅处于这些状态之一时，直到客户确认其付款之前，它将不会激活。可以使用计费模型或订阅实例上的 hasIncompletePayment 方法检查订阅是否有不完整的付款：

php

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

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

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

php

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

如果你希望订阅在 past_due 状态时仍被视为活跃，可以使用 Cashier 提供的 keepPastDueSubscriptionsActive 方法。通常，此方法应在 AppServiceProvider 的 register 方法中调用：

php

use Laravel\Cashier\Cashier;

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

NOTE

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

更改计划

在用户订阅你的应用程序后，他们可能偶尔想要更改为新的订阅计划。要将用户交换到新的订阅计划，请将计划的标识符传递给 swap 方法：

php

$user = App\User::find(1);

$user->subscription('default')->swap('provider-plan-id');

如果用户在试用期内，试用期将保持不变。此外，如果订阅存在“数量”，该数量也将保持不变。

如果你想交换计划并取消用户当前的任何试用期，可以使用 skipTrial 方法：

php

$user->subscription('default')
        ->skipTrial()
        ->swap('provider-plan-id');

如果你想交换计划并立即向用户开具发票，而不是等待他们的下一个计费周期，可以使用 swapAndInvoice 方法：

php

$user = App\User::find(1);

$user->subscription('default')->swapAndInvoice('provider-plan-id');

分摊

默认情况下，Stripe 在计划之间交换时会分摊费用。noProrate 方法可用于在不分摊费用的情况下更新订阅：

php

$user->subscription('default')->noProrate()->swap('provider-plan-id');

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

订阅数量

有时订阅会受到“数量”的影响。例如，你的应用程序可能会按每个帐户每月 每用户 收取 $10。要轻松增加或减少订阅数量，请使用 incrementQuantity 和 decrementQuantity 方法：

php

$user = User::find(1);

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

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

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

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

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

php

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

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

php

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

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

订阅税

要指定用户在订阅上支付的税率，请在你的计费模型上实现 taxPercentage 方法，并返回一个介于 0 和 100 之间的数值，最多保留两位小数。

php

public function taxPercentage()
{
    return 20;
}

taxPercentage 方法使你能够在模型级别应用税率，这对于跨多个国家和税率的用户群可能很有帮助。

NOTE

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

同步税率

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

php

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

订阅锚定日期

默认情况下，计费周期锚定是订阅创建的日期，或者如果使用了试用期，则是试用期结束的日期。如果你想修改计费锚定日期，可以使用 anchorBillingCycleOn 方法：

php

use App\User;
use Carbon\Carbon;

$user = User::find(1);

$anchor = Carbon::parse('first day of next month');

$user->newSubscription('default', 'premium')
            ->anchorBillingCycleOn($anchor->startOfDay())
            ->create($paymentMethod);

有关管理订阅计费周期的更多信息，请查阅 Stripe 计费周期文档

取消订阅

要取消订阅，请在用户的订阅上调用 cancel 方法：

php

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

当订阅被取消时，Cashier 将自动设置数据库中的 ends_at 列。此列用于知道何时 subscribed 方法应开始返回 false。例如，如果客户在 3 月 1 日取消订阅，但订阅原定于 3 月 5 日结束，则 subscribed 方法将继续返回 true，直到 3 月 5 日。

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

php

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

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

php

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

恢复订阅

如果用户已取消其订阅并且你希望恢复它，请使用 resume 方法。用户必须仍在其宽限期内才能恢复订阅：

php

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

如果用户取消订阅，然后在订阅完全过期之前恢复该订阅，他们将不会立即被计费。相反，他们的订阅将被重新激活，并且他们将在原始计费周期上被计费。

订阅试用

NOTE

Cashier 管理订阅的试用日期，并不从 Stripe 计划中派生。因此，你应该在 Stripe 中将你的计划配置为零天的试用期，以便 Cashier 可以管理试用。

提前支付方式

如果你希望在仍然收集支付方式信息的同时向客户提供试用期，你应该在创建订阅时使用 trialDays 方法：

php

$user = User::find(1);

$user->newSubscription('default', 'monthly')
            ->trialDays(10)
            ->create($paymentMethod);

此方法将在数据库中的订阅记录上设置试用期结束日期，并指示 Stripe 在此日期之后才开始向客户计费。在使用 trialDays 方法时，Cashier 将覆盖 Stripe 中计划配置的任何默认试用期。

NOTE

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

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

php

use Carbon\Carbon;

$user->newSubscription('default', 'monthly')
            ->trialUntil(Carbon::now()->addDays(10))
            ->create($paymentMethod);

你可以使用用户实例的 onTrial 方法或订阅实例的 onTrial 方法来确定用户是否在其试用期内。以下两个示例是相同的：

php

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

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

不提前支付方式

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

php

$user = User::create([
    // 填充其他用户属性...
    'trial_ends_at' => now()->addDays(10),
]);

NOTE

确保在你的模型定义中为 trial_ends_at 添加一个日期变换器。

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

php

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

如果你希望知道用户是否在其“通用”试用期内并且尚未创建实际订阅，你也可以使用 onGenericTrial 方法：

php

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

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

php

$user = User::find(1);

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

延长试用期

extendTrial 方法允许你在创建订阅后延长试用期：

php

// 试用期在 7 天后结束...
$subscription->extendTrial(
    now()->addDays(7)
);

// 在试用期上再增加 5 天...
$subscription->extendTrial(
    $subscription->trial_ends_at->addDays(5)
);

如果试用期已过期并且客户已经为订阅付费，你仍然可以为他们提供延长的试用期。试用期内的时间将从客户的下一个发票中扣除。

处理 Stripe Webhooks

NOTE

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

Stripe 可以通过 webhooks 通知你的应用程序各种事件。默认情况下，通过 Cashier 服务提供者配置了指向 Cashier 的 webhook 控制器的路由。此控制器将处理所有传入的 webhook 请求。

默认情况下，此控制器将自动处理取消订阅（根据你的 Stripe 设置定义的失败次数过多）、客户更新、客户删除、订阅更新和支付方式更改；然而，正如我们将很快发现的那样，你可以扩展此控制器以处理任何你喜欢的 webhook 事件。

为了确保你的应用程序可以处理 Stripe webhooks，请确保在 Stripe 控制面板中配置 webhook URL。你应该在 Stripe 控制面板中配置的所有 webhooks 的完整列表是：

customer.subscription.updated
customer.subscription.deleted
customer.updated
customer.deleted
invoice.payment_action_required

NOTE

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

Webhooks 和 CSRF 保护

由于 Stripe webhooks 需要绕过 Laravel 的 CSRF 保护，请确保在 VerifyCsrfToken 中间件中将 URI 列为例外，或将路由列在 web 中间件组之外：

php

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

定义 Webhook 事件处理程序

Cashier 自动处理失败收费的订阅取消，但如果你有其他想要处理的 webhook 事件，请扩展 Webhook 控制器。你的方法名称应符合 Cashier 的预期约定，具体来说，方法应以 handle 和你希望处理的 webhook 的“驼峰式”名称为前缀。例如，如果你希望处理 invoice.payment_succeeded webhook，你应该在控制器中添加一个 handleInvoicePaymentSucceeded 方法：

php

<?php

namespace App\Http\Controllers;

use Laravel\Cashier\Http\Controllers\WebhookController as CashierController;

class WebhookController extends CashierController
{
    /**
     * 处理发票付款成功。
     *
     * @param  array  $payload
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function handleInvoicePaymentSucceeded($payload)
    {
        // 处理事件
    }
}

接下来，在你的 routes/web.php 文件中定义一个指向你的 Cashier 控制器的路由。这将覆盖默认的已提供路由：

php

Route::post(
    'stripe/webhook',
    '\App\Http\Controllers\WebhookController@handleWebhook'
);

Cashier 在接收到 webhook 时会发出 Laravel\Cashier\Events\WebhookReceived 事件，并在 Cashier 处理 webhook 时发出 Laravel\Cashier\Events\WebhookHandled 事件。这两个事件都包含 Stripe webhook 的完整负载。

失败的订阅

如果客户的信用卡过期怎么办？不用担心 - Cashier 的 Webhook 控制器将为你取消客户的订阅。失败的付款将自动被控制器捕获和处理。控制器将在 Stripe 确定订阅失败时（通常在三次付款尝试失败后）取消客户的订阅。

验证 Webhook 签名

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

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

单次收费

简单收费

NOTE

charge 方法接受你想要收费的金额，以你应用程序使用的货币的最低单位表示。

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

php

// Stripe 接受以美分为单位的收费...
$stripeCharge = $user->charge(100, $paymentMethod);

charge 方法接受一个数组作为其第三个参数，允许你将任何选项传递给底层的 Stripe 收费创建。请查阅 Stripe 文档，了解创建收费时可用的选项：

php

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

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

php

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

带发票的收费

有时你可能需要进行一次性收费，但也需要为收费生成发票，以便你可以向客户提供 PDF 收据。invoiceFor 方法可以让你做到这一点。例如，让我们为客户开具 $5.00 的“一次性费用”发票：

php

// Stripe 接受以美分为单位的收费...
$user->invoiceFor('One Time Fee', 500);

发票将立即对用户的默认支付方式进行收费。invoiceFor 方法还接受一个数组作为其第三个参数。此数组包含发票项目的计费选项。方法接受的第四个参数也是一个数组。此最终参数接受发票本身的计费选项：

php

$user->invoiceFor('Stickers', 500, [
    'quantity' => 50,
], [
    'tax_percent' => 21,
]);

NOTE

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

退款

如果你需要退款 Stripe 收费，可以使用 refund 方法。此方法接受 Stripe Payment Intent ID 作为其第一个参数：

php

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

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

发票

你可以使用 invoices 方法轻松检索计费模型的发票数组：

php

$invoices = $user->invoices();

// 在结果中包含待处理的发票...
$invoices = $user->invoicesIncludingPending();

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

php

<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>

生成发票 PDF

在路由或控制器中，可以使用 downloadInvoice 方法生成发票的 PDF 下载。此方法将自动生成适当的 HTTP 响应以将下载发送到浏览器：

php

use Illuminate\Http\Request;

Route::get('user/invoice/{invoice}', function (Request $request, $invoiceId) {
    return $request->user()->downloadInvoice($invoiceId, [
        'vendor' => 'Your Company',
        'product' => 'Your Product',
    ]);
});

强客户认证

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

NOTE

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

需要额外确认的付款

SCA 规定通常需要额外的验证才能确认和处理付款。当这种情况发生时，Cashier 将抛出一个 IncompletePayment 异常，通知你需要额外的验证。在捕获此异常后，你有两种选择来继续。

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

php

use Laravel\Cashier\Exceptions\IncompletePayment;

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

在付款确认页面上，客户将被提示再次输入其信用卡信息并执行 Stripe 要求的任何其他操作，例如“3D Secure”确认。确认付款后，用户将被重定向到上面指定的 redirect 参数提供的 URL。

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

不完整的付款异常可能会在以下方法中抛出：charge、invoiceFor 和 invoice 在 Billable 用户上。在处理订阅时，SubscriptionBuilder 上的 create 方法，以及 Subscription 模型上的 incrementAndInvoice 和 swapAndInvoice 方法可能会抛出异常。

不完整和逾期状态

当付款需要额外确认时，订阅将保持在 incomplete 或 past_due 状态，如其 stripe_status 数据库列所示。Cashier 将在付款确认完成后通过 webhook 自动激活客户的订阅。

有关 incomplete 和 past_due 状态的更多信息，请参阅我们的其他文档。

离线支付通知

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

php

CASHIER_PAYMENT_NOTIFICATION=Laravel\Cashier\Notifications\ConfirmPayment

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

NOTE

即使客户手动进行需要额外确认的付款时，也会发送通知。不幸的是，Stripe 无法知道付款是手动完成的还是“离线”的。但是，如果客户在确认付款后访问付款页面，他们将只会看到“付款成功”消息。客户将无法意外地确认相同的付款两次并产生意外的第二次收费。

Stripe SDK

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

php

$stripeSubscription = $subscription->asStripeSubscription();

$stripeSubscription->update($subscription->stripe_id, ['application_fee_percent' => 5]);

Laravel Cashier ​

介绍 ​

升级 Cashier ​

安装 ​

数据库迁移 ​

配置 ​

计费模型 ​

API 密钥 ​

货币配置 ​

日志记录 ​

客户 ​

检索客户 ​

创建客户 ​

更新客户 ​

自定义电子邮件地址 ​

支付方式 ​

存储支付方式 ​

订阅的支付方式 ​

单次收费的支付方式 ​

检索支付方式 ​

确定用户是否有支付方式 ​

更新默认支付方式 ​

添加支付方式 ​

删除支付方式 ​

订阅 ​

创建订阅 ​

额外的用户详细信息 ​

优惠券 ​

检查订阅状态 ​

取消的订阅状态 ​

不完整和逾期状态 ​

更改计划 ​

分摊 ​

订阅数量 ​

订阅税 ​

同步税率 ​

订阅锚定日期 ​

取消订阅 ​

恢复订阅 ​

订阅试用 ​

提前支付方式 ​

不提前支付方式 ​

延长试用期 ​

处理 Stripe Webhooks ​

Webhooks 和 CSRF 保护 ​

定义 Webhook 事件处理程序 ​

失败的订阅 ​

验证 Webhook 签名 ​

单次收费 ​

简单收费 ​

带发票的收费 ​

退款 ​

发票 ​

生成发票 PDF ​

强客户认证 ​

需要额外确认的付款 ​

不完整和逾期状态 ​

离线支付通知 ​

Stripe SDK ​

Laravel Cashier

介绍

升级 Cashier

安装

数据库迁移

配置

计费模型

API 密钥

货币配置

日志记录

客户

检索客户

创建客户

更新客户

自定义电子邮件地址

支付方式

存储支付方式

订阅的支付方式

单次收费的支付方式

检索支付方式

确定用户是否有支付方式

更新默认支付方式

添加支付方式

删除支付方式

订阅

创建订阅

额外的用户详细信息

优惠券

检查订阅状态

取消的订阅状态

不完整和逾期状态

更改计划

分摊

订阅数量

订阅税

同步税率

订阅锚定日期

取消订阅

恢复订阅

订阅试用

提前支付方式

不提前支付方式

延长试用期

处理 Stripe Webhooks

Webhooks 和 CSRF 保护

定义 Webhook 事件处理程序

失败的订阅

验证 Webhook 签名

单次收费

简单收费

带发票的收费

退款

发票

生成发票 PDF

强客户认证

需要额外确认的付款

不完整和逾期状态

离线支付通知

Stripe SDK