Laravel 的收费系统 Cashier

简介

Laravel Cashier 提供了直观、流畅的接口来接入 Stripe's and Braintree's 订阅付费服务。它可以处理几乎所有你写起来非常头疼的付费订阅代码。除了提供基本的订阅管理之外,Cashier 还可以帮你处理优惠券,交换订阅、订阅“数量”、取消宽限期,甚至还可以生成 pdf 文档。

{注意} 如果你只是“一次性”的收费并且不提供订阅,你就不应该使用 Cashier。可以直接使用 Stripe 和 Braintree 的 SDK。

配置

Stripe

Composer

首先, 将 Stripe 的 Cashier 包添加到您的依赖项中:

  1. composer require "laravel/cashier":"~7.0"

数据库迁移

在使用 Cashier 之前,我们需要 准备数据库。我们需要向你的 users 表中添加几个列,并创建一个新的 subscriptions 表来保存所有客户的订阅:

  1. Schema::table('users', function ($table) {
  2. $table->string('stripe_id')->nullable();
  3. $table->string('card_brand')->nullable();
  4. $table->string('card_last_four')->nullable();
  5. $table->timestamp('trial_ends_at')->nullable();
  6. });
  7. Schema::create('subscriptions', function ($table) {
  8. $table->increments('id');
  9. $table->unsignedInteger('user_id');
  10. $table->string('name');
  11. $table->string('stripe_id');
  12. $table->string('stripe_plan');
  13. $table->integer('quantity');
  14. $table->timestamp('trial_ends_at')->nullable();
  15. $table->timestamp('ends_at')->nullable();
  16. $table->timestamps();
  17. });

一旦迁移文件建立好后,运行 Artisan 的 migrate 命令。

Billable 模型

接下来,添加 Billable trait 到模型定义。这个 trait 提供了多个方法以便执行常用支付任务,例如创建订阅、使用优惠券以及更新信用卡信息:

  1. use Laravel\Cashier\Billable;
  2. class User extends Authenticatable
  3. {
  4. use Billable;
  5. }

API Keys

最后,在配置文件 services.php 中配置 Stripe 的 key,你可以在Stripe 官网个人中心的控制面板中获取这些 Stripe API key 信息:

  1. 'stripe' => [
  2. 'model' => App\User::class,
  3. 'key' => env('STRIPE_KEY'),
  4. 'secret' => env('STRIPE_SECRET'),
  5. ],

Braintree

Braintree 注意事项

对于很多操作,Stripe 和 Braintree 实现 Cashier 的功能都是一样的,两者都提供了通过信用卡进行订阅支付的功能,但是 Braintree 还支持通过 PayPal 支付。不过,Braintree 也缺失一些 Stripe 支持的功能,在决定使用 Stripe 还是 Braintree 之前,需要考虑以下几点:

  • Braintree 支持 PayPal 而 Stripe 不支持。
  • Braintree 不支持 incrementdecrement方法,这是 Braintree 的限制,而不是 Cashier 限制。
  • Braintree 不支持基于百分比的折扣。这是 Braintree 的限制,而不是 Cashier 限制。

Composer

首先,将 Braintree 的 Cashier 包添加到您的依赖项中:

  1. composer require "laravel/cashier-braintree":"~2.0"

服务提供者

接下来, 在 config/app.php 配置文件中,注册 Laravel\Cashier\CashierServiceProvider 服务提供者

  1. Laravel\Cashier\CashierServiceProvider::class

信用卡优惠计划

在使用 Cashier 之前,你需要首先在 Braintree 控制面板中定义一个 plan-credit 折扣。这个折扣会根据用户选择的支付选项匹配合适的折扣比例,比如选择年付还是月付。

在 Braintree 控制面板中配置的折扣总额可以随意填写,Cashier 会在每次使用优惠券的时候根据我们自己的定制覆盖该默认值。由于 Braintree 不支持在订阅频率上来匹配折扣比例,所以这一优惠券是必需的。

数据库迁移

开始使用 Cashier 之前, 我们需要 准备一下数据库。我们需要在数据库的 users 表中新增几个列,以及创建一个新的 subscriptions 表来存储客户的订阅信息:

  1. Schema::table('users', function ($table) {
  2. $table->string('braintree_id')->nullable();
  3. $table->string('paypal_email')->nullable();
  4. $table->string('card_brand')->nullable();
  5. $table->string('card_last_four')->nullable();
  6. $table->timestamp('trial_ends_at')->nullable();
  7. });
  8. Schema::create('subscriptions', function ($table) {
  9. $table->increments('id');
  10. $table->unsignedInteger('user_id');
  11. $table->string('name');
  12. $table->string('braintree_id');
  13. $table->string('braintree_plan');
  14. $table->integer('quantity');
  15. $table->timestamp('trial_ends_at')->nullable();
  16. $table->timestamp('ends_at')->nullable();
  17. $table->timestamps();
  18. });

一旦迁移文件建立好后,运行 Artisan 的 migrate 命令。

Billable 模型

下一步, 添加 Billable trait 到你的模型定义中:

  1. use Laravel\Cashier\Billable;
  2. class User extends Authenticatable
  3. {
  4. use Billable;
  5. }

API Keys

下一步, 你应该在 services.php 文件中配置以下选项:

  1. 'braintree' => [
  2. 'model' => App\User::class,
  3. 'environment' => env('BRAINTREE_ENV'),
  4. 'merchant_id' => env('BRAINTREE_MERCHANT_ID'),
  5. 'public_key' => env('BRAINTREE_PUBLIC_KEY'),
  6. 'private_key' => env('BRAINTREE_PRIVATE_KEY'),
  7. ],

然后,你应该向 AppServiceProvider 服务提供者的 boot 方法中,添加以下的 Braintree SDK 调用:

  1. \Braintree_Configuration::environment(config('services.braintree.environment'));
  2. \Braintree_Configuration::merchantId(config('services.braintree.merchant_id'));
  3. \Braintree_Configuration::publicKey(config('services.braintree.public_key'));
  4. \Braintree_Configuration::privateKey(config('services.braintree.private_key'));

货币配置

Cashier 使用美元(USD)作为默认货币。你可以通过在服务提供者的 boot 方法中调用 Cashier::useCurrency 方法来更改默认的货币。这个 useCurrency 方法接受两个字符串参数:货币和货币符号:

  1. use Laravel\Cashier\Cashier;
  2. Cashier::useCurrency('eur', '€');

订阅

创建订阅

创建订阅,首先需要获取到一个 Billable 模型实例,这通常是 App\User 的一个实例。一旦您获取了模型实例,您可以使用 newSubscription 方法创建模型的订阅:

  1. $user = User::find(1);
  2. $user->newSubscription('main', 'premium')->create($stripeToken);

newSubscription 方法的第一个参数应该是订阅的名称。如果您的应用程序只提供一个订阅,那么您可以将其设置为 main or primary。第二个参数是用户订阅的 Stripe / Braintree 计划。这个值应该与 Stripe 或 Braintree 中的标识符对应。

create 方法接受一个 Stripe 信用卡 / 源令牌,它将开始订阅,并使用客户 ID 和其他相关的账单信息更新数据库。

用户其他的详细信息

如果您想要指定用户其他的详细信息,您可以通过将它们作为第二个参数传递给 create 方法:

  1. $user->newSubscription('main', 'monthly')->create($stripeToken, [
  2. 'email' => $email,
  3. ]);

要了解更多关于 Stripe 或 Braintree 支持的额外字段,请查看 Stripe 的 内容创建客户文档 或对应的 Braintree 文档

优惠券

如果您想在创建订阅时使用优惠券,您可以使用 withCoupon 方法:

  1. $user->newSubscription('main', 'monthly')
  2. ->withCoupon('code')
  3. ->create($stripeToken);

检查订阅状态

一旦用户在您的应用程序订阅了,您可以使用各种方便的方法轻松地检查他们的订阅状态。首先,如果用户有一个激活的订阅,那么 subscribed 的方法将返回 true ,即使订阅当前处于试用阶段:

  1. if ($user->subscribed('main')) {
  2. //
  3. }

这个 subscribed 方法还可以在 路由中间件 使用,允许您根据用户的订阅状态对路由和控制器进行访问。

  1. public function handle($request, Closure $next)
  2. {
  3. if ($request->user() && ! $request->user()->subscribed('main')) {
  4. // This user is not a paying customer...
  5. return redirect('billing');
  6. }
  7. return $next($request);
  8. }

如果您想要确定用户是否仍然处于测试阶段,您可以使用 onTrial 方法。这个方法对于向用户显示他们仍然处于试用期的警告是很有用的。

  1. if ($user->subscription('main')->onTrial()) {
  2. //
  3. }

基于给定的 Stripe / Braintree 计划 ID,可以使用 subscribedToPlan 方法来确定用户是否订阅了该计划。在本例中,我们将确定用户的 main 订阅是否激活了 monthly 计划:

  1. if ($user->subscribedToPlan('monthly', 'main')) {
  2. //
  3. }

取消订阅状态

为了确定用户是否曾经订阅,但是已经取消了他们的订阅,您可以使用 cancelled 方法:

  1. if ($user->subscription('main')->cancelled()) {
  2. //
  3. }

您还可以确定用户是否已经取消了订阅,但是仍然处于订阅的「宽限期」,直到订阅完全过期为止。例如,如果用户在 3 月 5 日取消了原定于 3 月 10 日到期的订阅,那么用户将在 3 月 10 日之前进行「宽限期」。请注意,在此期间 subscribed 方法仍然返回 true

  1. if ($user->subscription('main')->onGracePeriod()) {
  2. //
  3. }

修改订阅计划

用户在您的应用程序中订阅了之后,他们可能会偶尔想要更改一个新的订阅计划。要将一个用户切换到一个新的订阅,需将订阅计划的标识符传递给 swap 方法:

  1. $user = App\User::find(1);
  2. $user->subscription('main')->swap('provider-plan-id');

如果用户在试用期,试用期的期限会被保留。另外,如果订阅的数量存在「份额」,那么该份额也将保持。

如果你想在更改用户订阅计划的时候取消用户当前订阅的试用期,可以使用 skipTrial 方法:

  1. $user->subscription('main')
  2. ->skipTrial()
  3. ->swap('provider-plan-id');

订阅量

{note} 订阅量仅由 Cashier 的 Stripe 支持。Braintree 没有一个对应于 Stripe 的「数量」的特性。

有些时候订阅是会受「数量」影响的。举个例子,你的应用程序的付费方式可能是每个账户 $10 / 月。你可以使用 incrementQuantitydecrementQuantity 方法轻松的增加或减少你的订阅量:

  1. $user = User::find(1);
  2. $user->subscription('main')->incrementQuantity();
  3. // 对当前的订阅量加5 ...
  4. $user->subscription('main')->incrementQuantity(5);
  5. $user->subscription('main')->decrementQuantity();
  6. // 对当前的订阅量减5 ...
  7. $user->subscription('main')->decrementQuantity(5);

或者, 你可以使用 updateQuantity 方法设定一个特定的数量:

  1. $user->subscription('main')->updateQuantity(10);

noProrate 方法可用于更新订阅的数量,而不会对收费进行定价:

  1. $user->subscription('main')->noProrate()->updateQuantity(10);

要获得更多关于订阅量的信息, 请参考 Stripe 文档.

订阅税额

在计费模式上实现 taxPercentage 方法,并且返回一个 0 到 100 不超过2位小数的数字,用来指定用户在订阅中支付的税率百分比。

  1. public function taxPercentage() {
  2. return 20;
  3. }

taxPercentage 方法使你能够在模型的基础上应用税率,这对于一个跨越多个国家和税率的用户群可能有帮助。

{note} taxPercentage 方法只适用于付费订阅模式。如果你用 charges 来做「一次性」收费,你需要同时手工指定税率。

取消订阅

在用户订阅上调用 cancel 方法用来取消订阅:

  1. $user->subscription('main')->cancel();

当一个订阅被取消时,Cashier 将会自动的在你的数据库中设置 ends_at 列。这个列经常被用来知道何时 subscribed 字段应该开始返回 false 。例如,如果客户在 3 月 1 日取消订阅,但是订阅计划直到 3 月 5 日才结束,subscribed 方法将会继续返回 true 一直到 3 月 5 日。

你可以使用 onGracePeriod 方法确定用户是否确定订阅,但是仍然存在一个「宽限期」:

  1. if ($user->subscription('main')->onGracePeriod()) {
  2. //
  3. }

如果你想马上取消订阅,请在用户的订阅中调用 cancelNow 方法:

  1. $user->subscription('main')->cancelNow();

恢复订阅

如果一个用已经取消订阅,你可以使用 resume 方法在你希望去恢复它的时候。用户 必须 仍然在他们的宽限期内才可以恢复订阅:

  1. $user->subscription('main')->resume();

如果用户取消订阅,然后在订阅完全过期前恢复该订阅,他们将不会被立即计费。相反,他们的订阅将会被重新激活,需要按照原来的支付流程再次进行支付。

更新信用卡

updateCard 方法可用于更新用户的信用卡信息,该方法接受一个 Stripe 令牌并设置一个新的信用卡作为默认支付源:$user->updateCard($stripeToken);

试用订阅

有信用卡的情况

如果你想给你的顾客提供试用期,同时收集支付方法信息,那么你应该在创建订阅使用 trialDays 方法:

  1. $user = User::find(1);
  2. $user->newSubscription('main', 'monthly')
  3. ->trialDays(10)
  4. ->create($stripeToken);

该方法会在数据库订阅记录上设置订阅期结束时间,以便告知 Sripe / Braintree 在此之前不要计算用户的账单信息。

{note} 如果顾客没有在试用期结束前取消订阅,订阅会被自动结算,所以你应该确保告知你的用户他们的试用结束期。

trialUntil 方法允许提供 DateTime 实例指定试用结束期:

  1. use Carbon\Carbon;
  2. $user->newSubscription('main', 'monthly')
  3. ->trialUntil(Carbon::now()->addDays(10))
  4. ->create($stripeToken);

你可以使用用户实例的onTrial 方法或者订阅实例的 onTrial 方法判断用户是否处于试用期。下面两个示例等价:

  1. if ($user->onTrial('main')) {
  2. //
  3. }
  4. if ($user->subscription('main')->onTrial()) {
  5. //
  6. }

没有信用卡的情况

如果你不想在提供试用期的时候收集用户支付方式信息,只需设置用户记录的 trial_ends_at 列为期望的试用期结束日期即可,这通常在用户注册期间完成:

  1. $user = User::create([
  2. // Populate other user properties...
  3. 'trial_ends_at' => now()->addDays(10),
  4. ]);

{note} 确保已添加 trial_ends_at 日期修改器 到模型定义。

Cashier 把这种类型的引用引申为「一般体验」,因为它没有关联任何已存在的订阅。如果当前的日期没有超过 trail_ends_at 值, User 实例的 onTrial 方法将会返回 true

  1. if ($user->onTrial()) {
  2. // 用户在他们的试用期内...
  3. }

如果你希望明确的知道用户处于「一般」试用期,并且还未创建实际的订阅,那么你可以使用 onGenericTrial 方法:

  1. if ($user->onGenericTrial()) {
  2. // 用户在他们「一般」试用期...
  3. }

如果你准备给用户创建实际的订阅,通常你可以使用 newSubsription 方法:

  1. $user = User::find(1);
  2. $user->newSubscription('main', 'monthly')->create($stripeToken);

处理 Stripe Webhooks

Stripe 和 Braintree 都可以通过 webhook 通知应用各种各样的事件。去处理 Stripe webhooks,需要定义一个去 Cashier webhook控制器的路由。这个控制器可以处理所有输入 webhook 的请求并将他们分发到合适的控制器方法:

  1. Route::post(
  2. 'stripe/webhook',
  3. '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
  4. );

{note} 一旦已经注册了路由,确保在 Stripe 控制面板配置了 webhook URL

默认情况下,这个控制器将会自动对支付失败次数过多(这个次数可以在 Stripe 设置中定义)的订阅进行取消;此外,我们很快会发现,你可以扩展这控制器去处理任何你想要处理的 webhook 事件。

Webhooks & CSRF 保护

因为 Stripe webhooks 需要绕过 Laraval 的 CSRF 保护,确保在你的 VerifyCsrfToken 中间件列出 URI ,或者将其置于 web 中间件组之外:

  1. protected $except = [
  2. 'stripe/*',
  3. ];

定义 Webhook 事件处理程序

Cashier 对于失败支付自动进行取消订阅,但是如果你有其他的 Stripe webhook 事件希望去处理,可以扩展 Webhook 控制器。你的方法名应该与Cashier 期望的约定相符,更具体的说,你希望处理Stripe webhook 的方法应该以 handle 和「大小写」名为前缀。举例来说,如果你希望处理 invoice.payment_succeeded webhook,你应该在控制器添加 handleInvoicePaymentSucceeded 方法:

  1. <?php
  2. namespace App\Http\Controllers;
  3. use Laravel\Cashier\Http\Controllers\WebhookController as CashierController;
  4. class WebhookController extends CashierController
  5. {
  6. /**
  7. * Handle a Stripe webhook.
  8. *
  9. * @param array $payload
  10. * @return Response
  11. */
  12. public function handleInvoicePaymentSucceeded($payload)
  13. {
  14. // 处理事件
  15. }
  16. }

接下来,在 routes/web.php 文件中定义去 Cashier 控制器的路由Next, define a route to your Cashier controller within your routes/web.php file:

  1. Route::post(
  2. 'stripe/webhook',
  3. '\App\Http\Controllers\WebhookController@handleWebhook'
  4. );

订阅失败

如果用户的信用卡过期怎么办?不用担心 - Cashier 包含了一个 Webhook 控制器可以轻松为你取消用户的订阅。正如上文所述,所有你需要做的只是将路由指向控制器:

  1. Route::post(
  2. 'stripe/webhook',
  3. '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
  4. );

就是这样!失败的支付将会被控制器捕获和处理,该控制器会在 Stripe 判断订阅失败后(通常尝试支付失败3次及以上)取消用户的订阅。

处理 Braintree Webhooks

Stripe 和 Braintree 都可以通过 webhooks 通知应用各种各样的事件。去处理 Braintree webhooks,需要定义一个去 Cashier webhook 控制器的路由。这个控制器可以处理所有输入 webhook 的请求并将它们分发到合适的路由器方法:

  1. Route::post(
  2. 'braintree/webhook',
  3. '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
  4. );

{note} 一旦已经注册了路由,确保在 Braintree 控制器面板配置了 webhook URL。

默认情况下,这个控制器将会自动对支付失败次数过多(这个次数可以在 Braintree 设置中定义)的订阅进行取消;此外,我们很快会发现,你可以扩展这控制器去处理任何你想要处理的 webhook 事件。

Webhooks & CSRF 保护

因为 Braintree webhooks 需要绕过 Laravel 的 CSRF 保护,确保在你的 VerifyCsrfToken 中间件列出 URI ,或者将其置于 web 中间件组之外:

  1. protected $except = [
  2. 'braintree/*',
  3. ];

定义 Webhook 事件处理器

Cashier 对于失败支付自动进行取消订阅,但是如果你有其他的 Braintree webhook 事件希望去处理,可以扩展 Webhook 控制器。你的方法名应该与Cashier 期望的约定相符,更具体的说,你希望处理Braintree webhook 的方法应该以 handle 和「大小写」名为前缀。举例来说,如果你希望处理 dispute_opened webhook,你应该在控制器添加 handleDisputeOpened 方法:

  1. <?php
  2. namespace App\Http\Controllers;
  3. use Braintree\WebhookNotification;
  4. use Laravel\Cashier\Http\Controllers\WebhookController as CashierController;
  5. class WebhookController extends CashierController
  6. {
  7. /**
  8. * Handle a Braintree webhook.
  9. *
  10. * @param WebhookNotification $webhook
  11. * @return Response
  12. */
  13. public function handleDisputeOpened(WebhookNotification $notification)
  14. {
  15. // 处理事件
  16. }
  17. }

失败的订阅

如果用户的信用卡过期怎么办?不用担心 - Cashier 包含了一个 Webhook 控制器可以轻松为你取消用户的订阅。只需要将路由指向控制器:

  1. Route::post(
  2. 'braintree/webhook',
  3. '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
  4. );

就是这样!失败的支付将会被控制器捕获和处理,该控制器会在 Braintree 判断订阅失败后(通常尝试支付失败3次及以上)取消用户的订阅。 不要忘记:你需要在 Braintree 控制器面板配置你的 webhook URI。

一次性支付

简单支付

{note} 使用 Stripe 时,charge 方法接收你想支付于 应用程序使用的货币的最小单位 的金额。然而,当使用 Braintree 时,你应该将全部的美元金额传入 charge 方法:

如果你想对订阅客户的信用卡收取「一次性」费用,可以在可计费模型实例上使用 charge 方法:

  1. // Stripe 接收分为单位的费用...
  2. $user->charge(100);
  3. // Braintree 接收美元为单位的费用...
  4. $user->charge(1);

charge 方法接受一个数组作为它的第二个参数,允许你创建支付时将任何你想要的选项传递给底层的 Stripe / Braintree 。 有关在创建支付时可用的选项,请参阅 Stripe 或 Braintree 文档:

  1. $user->charge(100, [
  2. 'custom_option' => $value,
  3. ]);

如果支付失败,charge 方法将会抛出异常。如果支付成功,该方法将会返回完整的 Stripe / Braintree 响应:

  1. try {
  2. $response = $user->charge(100);
  3. } catch (Exception $e) {
  4. //
  5. }

费用与发票

有时你可能需要支付一次性费用同时也需要生成费用发票,以便可以向客户提供 PDF 收据。 invoiceFor 方法可以让你做到这一点。 例如,向客户开具 5.00 美元的「一次性费用」发票:

  1. // Stripe 接收分为单位的费用...
  2. $user->invoiceFor('One Time Fee', 500);
  3. // Braintree 接收美元为单位的费用...
  4. $user->invoiceFor('One Time Fee', 5);

该发票会立即通过用户信用卡支付。 invoiceFor 方法接收一个数组作为第三个参数,允许你在创建支付将任何你想要的选项传递给底层的 Stripe / Braintree :

  1. $user->invoiceFor('One Time Fee', 500, [
  2. 'custom-option' => $value,
  3. ]);

如果你使用 Braintree 作为你的账单提供者,你在调用 invoiceFor 方法时必须包含 description 选项:

  1. $user->invoiceFor('One Time Fee', 500, [
  2. 'description' => '发票描述写在这里',
  3. ]);

{note} invoiceFor 方法将会创建 Stripe 发票,该发票将会在支付失败后重试。如果你不想失败后重试,你需要在第一次支付失败后调用 Stripe API 关闭它。

发票

你可以使用 invoices 方法轻松获取账单模型的发票数组:

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

当列出顾客发票清单时,你可以使用发票辅助函数来显示相关的发票信息。例如,你可能想在表格中列出每张发票,从而方便用户下载它们:

  1. <table>
  2. @foreach ($invoices as $invoice)
  3. <tr>
  4. <td>{{ $invoice->date()->toFormattedDateString() }}</td>
  5. <td>{{ $invoice->total() }}</td>
  6. <td><a href="/user/invoice/{{ $invoice->id }}">Download</a></td>
  7. </tr>
  8. @endforeach
  9. </table>

生成 PDF 发票

从路由或控制器内,使用 downloadInvoice 方法生成一个发票的 PDF 下载。这个方法会自动给浏览器生成合适的 HTTP 下载响应:

use Illuminate\Http\Request;

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

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。