交易工具包 (Paddle)

未匹配的标注
本文档最新版为 12.x,旧版本可能放弃维护,推荐阅读最新版!

Laravel Cashier (Paddle)

简介

[!WARNING]
本文档介绍 Cashier Paddle 2.x 与 Paddle Billing 的集成。如果你仍在使用 Paddle Classic,应使用 Cashier Paddle 1.x。

Laravel Cashier Paddle 为 Paddle 的订阅计费服务提供清晰、流畅的接口,替你处理几乎所有繁琐的订阅计费样板代码。除了基本的订阅管理,Cashier 还支持切换订阅、订阅「数量」、暂停订阅、取消订阅后的宽限期等功能。

深入了解 Cashier Paddle 之前,建议先阅读 Paddle 的概念指南和 API 文档。

升级 Cashier

升级到新版本的 Cashier 时,请务必仔细阅读升级指南。

安装

首先,使用 Composer 包管理器安装适用于 Paddle 的 Cashier 包:

composer require laravel/cashier-paddle

接下来,使用 vendor:publish Artisan 命令发布 Cashier 的迁移文件:

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

然后,运行应用的数据库迁移。Cashier 的迁移会创建 customers 表,以及用于存储客户订阅信息的 subscriptions 和 subscription_items 表。最后,还会创建 transactions 表,存储与客户关联的所有 Paddle 交易记录:

php artisan migrate

[!WARNING]
为确保 Cashier 正确处理所有 Paddle 事件,请记得配置 Cashier 的 Webhook 处理。

Paddle 沙盒

在本地和预发布环境开发时,应注册 Paddle Sandbox 账户。该账户提供沙盒环境,让你无需实际支付即可开发和测试应用。你可以使用 Paddle 的测试卡号模拟各种支付场景。

使用 Paddle 沙盒环境时,应在应用的 .env 文件中将 PADDLE_SANDBOX 环境变量设置为 true:

PADDLE_SANDBOX=true

完成应用开发后,你可以申请 Paddle 商家账户。应用正式上线前,Paddle 需要审核并批准应用的域名。

配置

可计费模型

使用 Cashier 之前,必须在用户模型的定义中添加 Billable trait。该 trait 提供多种方法,让你执行创建订阅、更新支付方式信息等常见计费任务:

use Laravel\Paddle\Billable;

class User extends Authenticatable
{
    use Billable;
}

如果你有不是用户的可计费实体,也可以向这些类添加该 trait:

use Illuminate\Database\Eloquent\Model;
use Laravel\Paddle\Billable;

class Team extends Model
{
    use Billable;
}

API 密钥

接下来,在应用的 .env 文件中配置 Paddle 密钥。你可以从 Paddle 控制面板获取 API 密钥:

PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
PADDLE_API_KEY=your-paddle-api-key
PADDLE_RETAIN_KEY=your-paddle-retain-key
PADDLE_WEBHOOK_SECRET="your-paddle-webhook-secret"
PADDLE_SANDBOX=true

使用 Paddle 沙盒环境时,应将 PADDLE_SANDBOX 环境变量设置为 true。如果将应用部署到生产环境并使用 Paddle 正式商家环境,则应将其设置为 false。

PADDLE_RETAIN_KEY 是可选项,仅在使用 Paddle 的 Retain 功能时需要设置。

Paddle JS

Paddle 使用自己的 JavaScript 库启动结账组件。你可以在应用布局的 </head> 结束标签前放置 @paddleJS Blade 指令,以加载该库:

<head>
    ...

    @paddleJS
</head>

货币配置

你可以指定语言区域,用于格式化发票上显示的金额。Cashier 在内部使用 PHP 的 NumberFormatter 类设置货币的语言区域:

CASHIER_CURRENCY_LOCALE=nl_BE

[!WARNING]
要使用 en 之外的语言区域,请确保服务器已安装并配置 ext-intl PHP 扩展。

覆盖默认模型

你可以定义自己的模型并继承相应的 Cashier 模型,来扩展 Cashier 内部使用的模型:

use Laravel\Paddle\Subscription as CashierSubscription;

class Subscription extends CashierSubscription
{
    // ...
}

定义模型后,可以通过 Laravel\Paddle\Cashier 类让 Cashier 使用自定义模型。通常应在应用的 App\Providers\AppServiceProvider 类的 boot 方法中完成配置:

use App\Models\Cashier\Subscription;
use App\Models\Cashier\Transaction;

/**
 * 启动应用服务。
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useTransactionModel(Transaction::class);
}

快速入门

销售产品

[!NOTE]
使用 Paddle Checkout 之前,应先在 Paddle 控制面板中定义具有固定价格的产品,并配置 Paddle 的 Webhook 处理。

为应用提供产品销售和订阅计费功能可能让人望而却步,但借助 Cashier 和 Paddle Checkout Overlay,你可以轻松构建现代、可靠的支付集成。

对于非循环、仅收费一次的产品,我们使用 Cashier 和 Paddle Checkout Overlay 向客户收费,让客户填写支付信息并确认购买。通过 Checkout Overlay 完成付款后,客户会被重定向到应用中指定的成功页面 URL:

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $request->user()->checkout('pri_deluxe_album')
        ->returnTo(route('dashboard'));

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

如上例所示,我们使用 Cashier 提供的 checkout 方法创建结账对象,根据给定的「价格标识符」向客户展示 Paddle Checkout Overlay。在 Paddle 中,「价格」指的是为特定产品定义的价格。

必要时,checkout 方法会自动在 Paddle 中创建客户,并将该客户记录与应用数据库中的相应用户关联。结账会话结束后,客户会被重定向到专门的成功页面,你可以在页面上向客户显示提示信息。

在 buy 视图中,我们会放置一个按钮来显示 Checkout Overlay。Cashier Paddle 提供了 paddle-button Blade 组件;你也可以手动渲染覆盖式结账:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Buy Product
</x-paddle-button>

向 Paddle Checkout 提供元数据

销售产品时,通常会使用应用自行定义的 Cart 和 Order 模型来跟踪已完成的订单和已购买的产品。将客户重定向到 Paddle Checkout Overlay 完成购买时,你可能需要提供现有订单的标识符,以便客户返回应用后,将已完成的购买与相应订单关联起来。

为此,你可以向 checkout 方法提供一个自定义数据数组。假设用户开始结账时,应用会创建一个待处理的 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',
    ]);

    $checkout = $request->user()->checkout($order->price_ids)
        ->customData(['order_id' => $order->id]);

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

如上例所示,用户开始结账时,我们会将购物车或订单关联的所有 Paddle 价格标识符传给 checkout 方法。客户添加商品时,应用负责将商品与「购物车」或订单关联。我们还通过 customData 方法将订单 ID 传给 Paddle Checkout Overlay。

客户完成结账后,你可能希望将订单标记为「已完成」。为此,可以监听 Paddle 发送并由 Cashier 以事件形式触发的 Webhook,将订单信息存入数据库。

首先,监听 Cashier 分发的 TransactionCompleted 事件。通常应在应用的 AppServiceProvider 类的 boot 方法中注册事件监听器:

use App\Listeners\CompleteOrder;
use Illuminate\Support\Facades\Event;
use Laravel\Paddle\Events\TransactionCompleted;

/**
 * 启动应用服务。
 */
public function boot(): void
{
    Event::listen(TransactionCompleted::class, CompleteOrder::class);
}

在此示例中,CompleteOrder 监听器可以如下定义:

namespace App\Listeners;

use App\Models\Order;
use Laravel\Paddle\Cashier;
use Laravel\Paddle\Events\TransactionCompleted;

class CompleteOrder
{
    /**
     * 处理传入的 Cashier Webhook 事件。
     */
    public function handle(TransactionCompleted $event): void
    {
        $orderId = $event->payload['data']['custom_data']['order_id'] ?? null;

        $order = Order::findOrFail($orderId);

        $order->update(['status' => 'completed']);
    }
}

有关 transaction.completed 事件包含的数据,请参阅 Paddle 文档。

销售订阅

[!NOTE]
使用 Paddle Checkout 之前,应先在 Paddle 控制面板中定义具有固定价格的产品,并配置 Paddle 的 Webhook 处理。

为应用提供产品销售和订阅计费功能可能让人望而却步,但借助 Cashier 和 Paddle Checkout Overlay,你可以轻松构建现代、可靠的支付集成。

为了了解如何使用 Cashier 和 Paddle Checkout Overlay 销售订阅,我们以一个简单的订阅服务为例:它提供基础月付方案(price_basic_monthly)和年付方案(price_basic_yearly),这两个价格可以归在 Paddle 控制面板的「Basic」产品(pro_basic)下。此外,该服务还可能提供 Expert 方案,对应产品 pro_expert。

首先,看看客户如何订阅服务。客户可能会在应用的定价页面点击 Basic 方案的「订阅」按钮,该按钮会针对所选方案打开 Paddle Checkout Overlay。先通过 checkout 方法创建结账会话:

use Illuminate\Http\Request;

Route::get('/subscribe', function (Request $request) {
    $checkout = $request->user()->checkout('price_basic_monthly')
        ->returnTo(route('dashboard'));

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

在 subscribe 视图中,我们会放置一个按钮来显示 Checkout Overlay。Cashier Paddle 提供了 paddle-button Blade 组件;你也可以手动渲染覆盖式结账:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

现在,点击 Subscribe 按钮后,客户即可填写支付信息并创建订阅。由于某些支付方式需要几秒钟才能处理完毕,还应配置 Cashier 的 Webhook 处理,以确定订阅何时真正开始。

现在客户已能创建订阅,我们需要限制应用的部分功能,让它们仅对已订阅用户开放。你可以通过 Cashier 的 Billable trait 提供的 subscribed 方法判断用户当前的订阅状态:

@if ($user->subscribed())
    <p>You are subscribed.</p>
@endif

我们还可以轻松判断用户是否订阅了特定的产品或价格:

@if ($user->subscribedToProduct('pro_basic'))
    <p>You are subscribed to our Basic product.</p>
@endif

@if ($user->subscribedToPrice('price_basic_monthly'))
    <p>You are subscribed to our monthly Basic plan.</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('/subscribe');
        }

        return $next($request);
    }
}

定义中间件后,可以将其分配给路由:

use App\Http\Middleware\Subscribed;

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

允许客户管理计费方案

客户可能希望将订阅方案切换为其他产品或「等级」。在上面的示例中,我们希望允许客户将月付订阅改为年付订阅。为此,需要提供一个按钮或类似入口,指向以下路由:

use Illuminate\Http\Request;

Route::put('/subscription/{price}/swap', function (Request $request, $price) {
    $user->subscription()->swap($price); // 本例中的 "$price" 为 "price_basic_yearly"。

    return redirect()->route('dashboard');
})->name('subscription.swap');

除了切换方案,还需要允许客户取消订阅。与切换方案类似,提供一个指向以下路由的按钮:

use Illuminate\Http\Request;

Route::put('/subscription/cancel', function (Request $request, $price) {
    $user->subscription()->cancel();

    return redirect()->route('dashboard');
})->name('subscription.cancel');

这样,订阅将在计费周期结束时取消。

[!NOTE]
只要配置了 Cashier 的 Webhook 处理,Cashier 就会检查来自 Paddle 的 Webhook,自动保持应用中与 Cashier 相关的数据表同步。例如,通过 Paddle 控制面板取消客户的订阅时,Cashier 会收到相应的 Webhook,并在应用数据库中将订阅标记为「已取消」。

结账会话

大多数向客户收费的操作都通过 Paddle 的覆盖式结账组件或嵌入式结账完成。

使用 Paddle 处理结账支付之前,应在 Paddle 结账设置控制面板中定义应用的默认支付链接。

覆盖式结账

显示 Checkout Overlay 组件之前,必须使用 Cashier 生成结账会话。该会话会告知结账组件应执行的计费操作:

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

Cashier 提供了 paddle-button Blade 组件。你可以将结账会话作为属性传给组件;点击按钮时,Paddle 的结账组件便会显示:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

默认情况下,组件会使用 Paddle 的默认样式显示。你可以为组件添加 data-theme='light' 等 Paddle 支持的属性来自定义样式:

<x-paddle-button :checkout="$checkout" class="px-8 py-4" data-theme="light">
    Subscribe
</x-paddle-button>

Paddle 结账组件以异步方式运行。用户通过组件创建订阅后,Paddle 会向应用发送 Webhook,以便应用正确更新数据库中的订阅状态。因此,务必正确配置 Webhook,以处理来自 Paddle 的状态变更。

[!WARNING]
订阅状态变更后,收到相应 Webhook 的延迟通常很短,但应用仍应考虑到这一延迟:用户完成结账后,订阅可能不会立即可用。

手动渲染覆盖式结账

你也可以不使用 Laravel 内置的 Blade 组件,手动渲染覆盖式结账。首先,按照前面的示例生成结账会话:

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

接下来,可以使用 Paddle.js 初始化结账。在此示例中,我们创建一个带有 paddle_button 类的链接。Paddle.js 会检测该类,并在点击链接时显示覆盖式结账:

<?php
$items = $checkout->getItems();
$customer = $checkout->getCustomer();
$custom = $checkout->getCustomData();
?>

<a
    href='#!'
    class='paddle_button'
    data-items='{!! json_encode($items) !!}'
    @if ($customer) data-customer-id='{{ $customer->paddle_id }}' @endif
    @if ($custom) data-custom-data='{{ json_encode($custom) }}' @endif
    @if ($returnUrl = $checkout->getReturnUrl()) data-success-url='{{ $returnUrl }}' @endif
>
    Buy Product
</a>

嵌入式结账

如果不想使用 Paddle 的「覆盖式」结账组件,也可以将组件嵌入页面。虽然这种方式不允许调整结账的 HTML 字段,但可以将组件嵌入应用中。

为方便使用嵌入式结账,Cashier 提供了 paddle-checkout Blade 组件。首先应生成结账会话:

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

然后,将结账会话传给组件的 checkout 属性:

<x-paddle-checkout :checkout="$checkout" class="w-full" />

要调整嵌入式结账组件的高度,可以向 Blade 组件传入 height 属性:

<x-paddle-checkout :checkout="$checkout" class="w-full" height="500" />

有关嵌入式结账自定义选项的详情,请参阅 Paddle 的嵌入式结账指南和可用的结账设置。

手动渲染嵌入式结账

你也可以不使用 Laravel 内置的 Blade 组件,手动渲染嵌入式结账。首先,按照前面的示例生成结账会话:

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));

    return view('billing', ['checkout' => $checkout]);
});

接下来,可以使用 Paddle.js 初始化结账。此示例使用 Alpine.js 演示;你可以根据自己的前端技术栈修改示例:

<?php
$options = $checkout->options();

$options['settings']['frameTarget'] = 'paddle-checkout';
$options['settings']['frameInitialHeight'] = 366;
?>

<div class="paddle-checkout" x-data="{}" x-init="
    Paddle.Checkout.open(@json($options));
">
</div>

游客结账

有时,你可能需要为无需在应用中注册账户的用户创建结账会话。为此,可以使用 guest 方法:

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

Route::get('/buy', function (Request $request) {
    $checkout = Checkout::guest(['pri_34567'])
        ->returnTo(route('home'));

    return view('billing', ['checkout' => $checkout]);
});

然后,可以将结账会话传给 Paddle 按钮或嵌入式结账 Blade 组件。

价格预览

Paddle 允许按货币自定义价格,也就是为不同国家配置不同价格。Cashier Paddle 的 previewPrices 方法可以获取这些价格,该方法接收需要查询的价格 ID:

use Laravel\Paddle\Cashier;

$prices = Cashier::previewPrices(['pri_123', 'pri_456']);

货币会根据请求的 IP 地址确定;你也可以指定国家来获取价格:

use Laravel\Paddle\Cashier;

$prices = Cashier::previewPrices(['pri_123', 'pri_456'], ['address' => [
    'country_code' => 'BE',
    'postal_code' => '1234',
]]);

获取价格后,可以按需显示:

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    @endforeach
</ul>

你也可以分别显示小计和税额:

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->subtotal() }} (+ {{ $price->tax() }} tax)</li>
    @endforeach
</ul>

更多信息请参阅 Paddle 关于价格预览的 API 文档。

客户价格预览

如果用户已经是客户,而你希望显示适用于该客户的价格,可以直接从客户实例获取:

use App\Models\User;

$prices = User::find(1)->previewPrices(['pri_123', 'pri_456']);

Cashier 在内部使用用户的客户 ID 获取以其货币计价的价格。例如,美国用户看到美元价格,比利时用户看到欧元价格。如果找不到匹配的货币,则使用产品的默认货币。你可以在 Paddle 控制面板中自定义产品或订阅方案的所有价格。

折扣

你也可以选择显示折扣后的价格。调用 previewPrices 方法时,通过 discount_id 选项提供折扣 ID:

use Laravel\Paddle\Cashier;

$prices = Cashier::previewPrices(['pri_123', 'pri_456'], [
    'discount_id' => 'dsc_123'
]);

然后显示计算后的价格:

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    @endforeach
</ul>

客户

客户默认值

Cashier 允许你为创建结账会话时的客户信息定义默认值。设置后,可以预先填写客户的电子邮件地址和姓名,让客户直接进入结账组件的支付环节。你可以在可计费模型上重写以下方法来设置默认值:

/**
 * 获取要关联到 Paddle 的客户姓名。
 */
public function paddleName(): string|null
{
    return $this->name;
}

/**
 * 获取要关联到 Paddle 的客户电子邮件地址。
 */
public function paddleEmail(): string|null
{
    return $this->email;
}

Cashier 中所有生成结账会话的操作都会使用这些默认值。

获取客户

你可以使用 Cashier::findBillable 方法,通过 Paddle 客户 ID 获取客户。该方法会返回可计费模型的实例:

use Laravel\Paddle\Cashier;

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

创建客户

有时,你可能希望创建 Paddle 客户,但暂不创建订阅。可以使用 createAsCustomer 方法:

$customer = $user->createAsCustomer();

该方法返回 Laravel\Paddle\Customer 实例。在 Paddle 中创建客户后,你可以在之后的任意时间创建订阅。还可以传入可选的 $options 数组,提供额外的 Paddle API 支持的客户创建参数:

$customer = $user->createAsCustomer($options);

订阅

创建订阅

要创建订阅,首先从数据库中获取可计费模型的实例,通常是 App\Models\User 的实例。获取模型后,可以使用 subscribe 方法为其创建结账会话:

use Illuminate\Http\Request;

Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe($premium = 'pri_123', 'default')
        ->returnTo(route('home'));

    return view('billing', ['checkout' => $checkout]);
});

subscribe 方法的第一个参数是用户订阅的具体价格,应与 Paddle 中的价格标识符对应。returnTo 方法接收一个 URL,用户成功完成结账后会被重定向到该地址。subscribe 方法的第二个参数是订阅的内部「类型」。如果应用只提供一种订阅,可以将其命名为 default 或 primary。该类型仅供应用内部使用,不应显示给用户;它不能包含空格,且在创建订阅后绝不能更改。

你也可以使用 customData 方法提供包含订阅自定义元数据的数组:

$checkout = $request->user()->subscribe($premium = 'pri_123', 'default')
    ->customData(['key' => 'value'])
    ->returnTo(route('home'));

创建订阅结账会话后,可以将其传给 Cashier Paddle 提供的 paddle-button Blade 组件:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

用户完成结账后,Paddle 会发送 subscription_created Webhook。Cashier 收到该 Webhook 后会为客户设置订阅。为确保应用正确接收并处理所有 Webhook,请确保已正确配置 Webhook 处理。

检查订阅状态

用户订阅应用后,你可以使用多种便捷方法检查订阅状态。首先,如果用户拥有有效订阅,subscribed 方法会返回 true,即使订阅仍处于试用期也是如此:

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

如果应用提供多个订阅,可以在调用 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()) {
            // 该用户不是付费客户……
            return redirect('/billing');
        }

        return $next($request);
    }
}

要判断用户是否仍处于试用期,可以使用 onTrial 方法。该方法有助于判断是否应向用户显示试用期提示:

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

subscribedToPrice 方法可根据 Paddle 价格 ID 判断用户是否订阅了指定方案。在此示例中,我们判断用户的 default 订阅是否有效地订阅了月付价格:

if ($user->subscribedToPrice($monthly = 'pri_123', 'default')) {
    // ...
}

recurring 方法可用于判断用户当前是否拥有有效订阅,并且不再处于试用期或宽限期:

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

已取消订阅的状态

要判断用户是否曾有有效订阅但已取消,可以使用 canceled 方法:

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

你也可以判断用户是否已取消订阅,但在订阅完全到期前仍处于「宽限期」。例如,用户在 3 月 5 日取消了原定于 3 月 10 日到期的订阅,那么宽限期会持续到 3 月 10 日。在此期间,subscribed 方法仍会返回 true:

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

逾期状态

如果订阅支付失败,订阅会被标记为 past_due。处于此状态时,订阅在客户更新支付信息之前不会生效。你可以使用订阅实例的 pastDue 方法判断订阅是否逾期:

if ($user->subscription()->pastDue()) {
    // ...
}

订阅逾期时,应引导用户更新支付信息。

如果希望订阅在 past_due 状态下仍被视为有效,可以使用 Cashier 提供的 keepPastDueSubscriptionsActive 方法。通常应在 AppServiceProvider 的 register 方法中调用:

use Laravel\Paddle\Cashier;

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

[!WARNING]
订阅处于 past_due 状态时,在支付信息更新之前无法更改。因此,此时调用 swap 和 updateQuantity 方法会抛出异常。

订阅查询作用域

大多数订阅状态也可作为查询作用域使用,方便你查询数据库中处于特定状态的订阅:

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

// 获取用户的所有已取消订阅……
$subscriptions = $user->subscriptions()->canceled()->get();

可用的查询作用域完整列表如下:

Subscription::query()->valid();
Subscription::query()->onTrial();
Subscription::query()->expiredTrial();
Subscription::query()->notOnTrial();
Subscription::query()->active();
Subscription::query()->recurring();
Subscription::query()->pastDue();
Subscription::query()->paused();
Subscription::query()->notPaused();
Subscription::query()->onPausedGracePeriod();
Subscription::query()->notOnPausedGracePeriod();
Subscription::query()->canceled();
Subscription::query()->notCanceled();
Subscription::query()->onGracePeriod();
Subscription::query()->notOnGracePeriod();

订阅单次收费

订阅单次收费允许你在订阅费用之外向订阅者收取一次性费用。调用 charge 方法时,必须提供一个或多个价格 ID:

// 收取一个价格……
$response = $user->subscription()->charge('pri_123');

// 一次收取多个价格……
$response = $user->subscription()->charge(['pri_123', 'pri_456']);

charge 方法要到订阅的下一个计费周期才会实际向客户收费。如果希望立即收费,可以改用 chargeAndInvoice 方法:

$response = $user->subscription()->chargeAndInvoice('pri_123');

更新支付信息

Paddle 会为每个订阅保存一个支付方式。要更新订阅的默认支付方式,应使用订阅模型的 redirectToUpdatePaymentMethod 方法,将客户重定向到 Paddle 托管的支付方式更新页面:

use Illuminate\Http\Request;

Route::get('/update-payment-method', function (Request $request) {
    $user = $request->user();

    return $user->subscription()->redirectToUpdatePaymentMethod();
});

用户完成信息更新后,Paddle 会发送 subscription_updated Webhook,应用数据库中的订阅信息也会随之更新。

更改方案

用户订阅应用后,可能会希望切换到新的订阅方案。要更新用户的订阅方案,应将 Paddle 价格标识符传给订阅的 swap 方法:

use App\Models\User;

$user = User::find(1);

$user->subscription()->swap($premium = 'pri_456');

如果希望切换方案后立即向用户开具发票,而不是等待下一个计费周期,可以使用 swapAndInvoice 方法:

$user = User::find(1);

$user->subscription()->swapAndInvoice($premium = 'pri_456');

按比例分摊

默认情况下,Paddle 在切换方案时会按比例分摊费用。可以使用 noProrate 方法更新订阅,而不按比例分摊费用:

$user->subscription('default')->noProrate()->swap($premium = 'pri_456');

如果希望禁用按比例分摊并立即向客户开具发票,可以结合使用 swapAndInvoice 和 noProrate 方法:

$user->subscription('default')->noProrate()->swapAndInvoice($premium = 'pri_456');

或者,如果不希望因订阅变更向客户收费,可以使用 doNotBill 方法:

$user->subscription('default')->doNotBill()->swap($premium = 'pri_456');

有关 Paddle 按比例分摊政策的更多信息,请参阅其按比例分摊文档。

订阅数量

有时订阅会受「数量」影响。例如,项目管理应用可能会按每个项目每月 10 美元收费。可以使用 incrementQuantity 和 decrementQuantity 方法轻松增加或减少订阅数量:

$user = User::find(1);

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

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

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

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

你也可以使用 updateQuantity 方法设置指定数量:

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

可以使用 noProrate 方法更新订阅数量,而不按比例分摊费用:

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

多产品订阅的数量

如果订阅包含多个产品,应将需要增加或减少数量的价格 ID 作为第二个参数传给增减数量的方法:

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

多产品订阅

多产品订阅允许你将多个计费产品分配给同一个订阅。例如,假设你正在构建一个客户服务「帮助台」应用,其基础订阅价格为每月 10 美元,同时提供一个每月额外收费 15 美元的实时聊天附加产品。

创建订阅结账会话时,可以将价格数组作为第一个参数传给 subscribe 方法,为订阅指定多个产品:

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe([
        'price_monthly',
        'price_chat',
    ]);

    return view('billing', ['checkout' => $checkout]);
});

上例中,客户的 default 订阅将关联两个价格,分别按照各自的计费周期收费。必要时,可以传入键值对组成的关联数组,指定每个价格的数量:

$user = User::find(1);

$checkout = $user->subscribe(['price_monthly', 'price_chat' => 5]);

要向现有订阅添加另一个价格,必须使用订阅的 swap 方法。调用时,还应包含订阅当前的价格和数量:

$user = User::find(1);

$user->subscription()->swap(['price_chat', 'price_original' => 2]);

上例会添加新价格,但客户要到下一个计费周期才会为其付费。如果希望立即收费,可以使用 swapAndInvoice 方法:

$user->subscription()->swapAndInvoice(['price_chat', 'price_original' => 2]);

你可以使用 swap 方法并省略要移除的价格,来从订阅中移除价格:

$user->subscription()->swap(['price_original' => 2]);

[!WARNING]
不能移除订阅中的最后一个价格;应直接取消订阅。

多个订阅

Paddle 允许客户同时拥有多个订阅。例如,一家健身房可能提供游泳和举重订阅,每种订阅的价格各不相同。客户可以订阅其中一种或两种方案。

应用创建订阅时,可以将订阅类型作为第二个参数传给 subscribe 方法。类型可以是表示用户所创建订阅类型的任意字符串:

use Illuminate\Http\Request;

Route::post('/swimming/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe($swimmingMonthly = 'pri_123', 'swimming');

    return view('billing', ['checkout' => $checkout]);
});

在此示例中,我们为客户创建了月付游泳订阅。客户之后可能希望切换为年付订阅;调整时,只需切换 swimming 订阅的价格:

$user->subscription('swimming')->swap($swimmingYearly = 'pri_456');

当然,你也可以直接取消该订阅:

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

暂停订阅

要暂停订阅,请在用户的订阅上调用 pause 方法:

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

暂停订阅时,Cashier 会自动设置数据库中的 paused_at 列,用于判断 paused 方法何时应开始返回 true。例如,客户在 3 月 1 日暂停订阅,但订阅原定于 3 月 5 日续费,则 paused 方法会在 3 月 5 日之前继续返回 false。这是因为通常允许用户在计费周期结束前继续使用应用。

默认情况下,暂停会在下一个计费周期生效,让客户继续使用已付费周期的剩余时间。如果希望立即暂停订阅,可以使用 pauseNow 方法:

$user->subscription()->pauseNow();

使用 pauseUntil 方法可以将订阅暂停至指定时间:

$user->subscription()->pauseUntil(now()->plus(months: 1));

或者,可以使用 pauseNowUntil 方法立即暂停订阅,直至指定时间:

$user->subscription()->pauseNowUntil(now()->plus(months: 1));

可以使用 onPausedGracePeriod 方法判断用户是否已暂停订阅但仍处于「宽限期」:

if ($user->subscription()->onPausedGracePeriod()) {
    // ...
}

要恢复已暂停的订阅,可以在订阅上调用 resume 方法:

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

[!WARNING]
订阅暂停期间无法修改。如果要切换方案或更新数量,必须先恢复订阅。

取消订阅

要取消订阅,请在用户的订阅上调用 cancel 方法:

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

取消订阅时,Cashier 会自动设置数据库中的 ends_at 列,用于判断 subscribed 方法何时应开始返回 false。例如,客户在 3 月 1 日取消订阅,但订阅原定于 3 月 5 日结束,则 subscribed 方法在 3 月 5 日之前仍会返回 true。这是因为通常允许用户在计费周期结束前继续使用应用。

可以使用 onGracePeriod 方法判断用户是否已取消订阅但仍处于「宽限期」:

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

如果希望立即取消订阅,可以在订阅上调用 cancelNow 方法:

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

要阻止处于宽限期的订阅被取消,可以调用 stopCancelation 方法:

$user->subscription()->stopCancelation();

[!WARNING]
Paddle 订阅取消后无法恢复。如果客户希望继续订阅,必须创建新的订阅。

订阅试用

预先提供支付方式

如果希望为客户提供试用期,同时预先收集支付方式信息,应在 Paddle 控制面板中为客户订阅的价格设置试用时长,然后照常创建结账会话:

use Illuminate\Http\Request;

Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()
        ->subscribe('pri_monthly')
        ->returnTo(route('home'));

    return view('billing', ['checkout' => $checkout]);
});

应用收到 subscription_created 事件时,Cashier 会在数据库的订阅记录中设置试用结束日期,并指示 Paddle 在该日期之后才开始向客户收费。

[!WARNING]
如果客户的订阅在试用结束日期之前未被取消,试用到期后将立即收费,因此务必通知用户试用结束日期。

可以使用用户实例的 onTrial 方法判断用户是否处于试用期:

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

要判断现有试用期是否已过期,可以使用 hasExpiredTrial 方法:

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

要判断用户是否处于特定订阅类型的试用期,可以将类型传给 onTrial 或 hasExpiredTrial 方法:

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

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

不预先提供支付方式

如果希望提供试用期而不预先收集用户的支付方式信息,可以将用户关联的客户记录上的 trial_ends_at 列设置为期望的试用结束日期。通常在用户注册时完成:

use App\Models\User;

$user = User::create([
    // ...
]);

$user->createAsCustomer([
    'trial_ends_at' => now()->plus(days: 10)
]);

Cashier 将这种试用称为「通用试用」,因为它不与任何现有订阅关联。如果当前日期尚未超过 trial_ends_at 的值,User 实例的 onTrial 方法会返回 true:

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

准备好为用户创建实际订阅后,可以像往常一样使用 subscribe 方法:

use Illuminate\Http\Request;

Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()
        ->subscribe('pri_monthly')
        ->returnTo(route('home'));

    return view('billing', ['checkout' => $checkout]);
});

要获取用户的试用结束日期,可以使用 trialEndsAt 方法。用户处于试用期时,该方法返回 Carbon 日期实例,否则返回 null。如果要获取默认订阅以外的特定订阅的试用结束日期,也可以传入可选的订阅类型参数:

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

如果希望明确判断用户是否处于「通用」试用期且尚未创建实际订阅,可以使用 onGenericTrial 方法:

if ($user->onGenericTrial()) {
    // 用户处于「通用」试用期内……
}

延长或激活试用

可以调用订阅的 extendTrial 方法并指定试用结束时间,以延长现有试用期:

$user->subscription()->extendTrial(now()->plus(days: 5));

也可以在订阅上调用 activate 方法结束试用期,立即激活订阅:

$user->subscription()->activate();

处理 Paddle Webhook

Paddle 可以通过 Webhook 向应用通知各种事件。默认情况下,Cashier 服务提供者会注册一个指向其 Webhook 控制器的路由,由该控制器处理所有传入的 Webhook 请求。

默认情况下,该控制器会自动处理因收费失败次数过多而取消订阅、订阅更新和支付方式变更。不过,你也可以扩展控制器来处理所需的任何 Paddle Webhook 事件。

为确保应用能够处理 Paddle Webhook,请务必在 Paddle 控制面板中配置 Webhook URL。默认情况下,Cashier 的 Webhook 控制器响应 /paddle/webhook 路径。应在 Paddle 控制面板中启用的 Webhook 完整列表如下:

  • Customer Updated(客户更新)
  • Transaction Completed(交易完成)
  • Transaction Updated(交易更新)
  • Subscription Created(订阅创建)
  • Subscription Updated(订阅更新)
  • Subscription Paused(订阅暂停)
  • Subscription Canceled(订阅取消)

[!WARNING]
请务必使用 Cashier 自带的 Webhook 签名验证中间件保护传入请求。

Webhook 与 CSRF 保护

由于 Paddle Webhook 需要绕过 Laravel 的 CSRF 保护,应确保 Laravel 不会尝试验证传入的 Paddle Webhook 的 CSRF 令牌。为此,应在应用的 bootstrap/app.php 文件中将 paddle/* 排除在 CSRF 保护之外:

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

Webhook 与本地开发

为了让 Paddle 在本地开发期间向应用发送 Webhook,需要通过 Ngrok 或 Expose 等站点共享服务暴露应用。如果使用 Laravel Sail 进行本地开发,可以使用 Sail 的站点共享命令。

定义 Webhook 事件处理器

Cashier 会自动处理因收费失败而取消订阅及其他常见的 Paddle Webhook。如果还需要处理其他 Webhook 事件,可以监听 Cashier 分发的以下事件:

  • Laravel\Paddle\Events\WebhookReceived
  • Laravel\Paddle\Events\WebhookHandled

这两个事件都包含 Paddle Webhook 的完整载荷。例如,要处理 transaction.billed Webhook,可以注册一个监听器:

<?php

namespace App\Listeners;

use Laravel\Paddle\Events\WebhookReceived;

class PaddleEventListener
{
    /**
     * 处理收到的 Paddle Webhook。
     */
    public function handle(WebhookReceived $event): void
    {
        if ($event->payload['event_type'] === 'transaction.billed') {
            // 处理传入的事件……
        }
    }
}

Cashier 还会根据收到的 Webhook 类型分发专门的事件。除了 Paddle 的完整载荷,这些事件还包含处理 Webhook 所用的相关模型,例如可计费模型、订阅或收据:

  • Laravel\Paddle\Events\CustomerUpdated
  • Laravel\Paddle\Events\TransactionCompleted
  • Laravel\Paddle\Events\TransactionUpdated
  • Laravel\Paddle\Events\SubscriptionCreated
  • Laravel\Paddle\Events\SubscriptionUpdated
  • Laravel\Paddle\Events\SubscriptionPaused
  • Laravel\Paddle\Events\SubscriptionCanceled

你也可以在应用的 .env 文件中定义 CASHIER_WEBHOOK 环境变量,覆盖默认的内置 Webhook 路由。该值应为 Webhook 路由的完整 URL,并须与 Paddle 控制面板中设置的 URL 一致:

CASHIER_WEBHOOK=https://example.com/my-paddle-webhook-url

验证 Webhook 签名

为保护 Webhook,可以使用 Paddle 的 Webhook 签名。为方便起见,Cashier 自动提供了一个中间件,用于验证传入的 Paddle Webhook 请求。

要启用 Webhook 验证,请确保应用的 .env 文件中定义了 PADDLE_WEBHOOK_SECRET 环境变量。Webhook 密钥可以从 Paddle 账户控制面板获取。

单次收费

产品收费

要为客户发起产品购买,可以使用可计费模型实例的 checkout 方法生成结账会话。该方法接收一个或多个价格 ID;必要时,可以使用关联数组提供购买产品的数量:

use Illuminate\Http\Request;

Route::get('/buy', function (Request $request) {
    $checkout = $request->user()->checkout(['pri_tshirt', 'pri_socks' => 5]);

    return view('buy', ['checkout' => $checkout]);
});

生成结账会话后,可以使用 Cashier 提供的 paddle-button Blade 组件,让用户查看 Paddle 结账组件并完成购买:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Buy
</x-paddle-button>

结账会话提供 customData 方法,让你向底层交易创建过程传入自定义数据。有关传入自定义数据时可用选项的更多信息,请参阅 Paddle 文档:

$checkout = $user->checkout('pri_tshirt')
    ->customData([
        'custom_option' => $value,
    ]);

交易退款

交易退款会将退款金额退回客户购买时使用的支付方式。要为 Paddle 购买退款,可以使用 Cashier\Paddle\Transaction 模型的 refund 方法。第一个参数是退款原因,之后可传入包含一个或多个待退款价格 ID 及可选金额的关联数组。你可以使用 transactions 方法获取可计费模型的交易记录。

例如,假设要退还某笔交易中的 pri_123 和 pri_456:前者全额退款,后者只退还两美元:

use App\Models\User;

$user = User::find(1);

$transaction = $user->transactions()->first();

$response = $transaction->refund('Accidental charge', [
    'pri_123', // 全额退还此价格……
    'pri_456' => 200, // 仅部分退还此价格……
]);

上例退还交易中的特定项目。如果要退还整笔交易,只需提供退款原因:

$response = $transaction->refund('Accidental charge');

有关退款的更多信息,请参阅 Paddle 退款文档。

[!WARNING]
退款在处理完成前必须经过 Paddle 批准。

交易贷记

与退款类似,你也可以为交易贷记。交易贷记会将资金加入客户余额,供其日后购买使用。贷记仅适用于手动收款的交易,不适用于自动收款的交易(如订阅),因为 Paddle 会自动处理订阅贷记:

$transaction = $user->transactions()->first();

// 全额贷记指定的交易项目……
$response = $transaction->credit('Compensation', 'pri_123');

更多信息请参阅 Paddle 的贷记文档。

[!WARNING]
贷记仅适用于手动收款的交易;自动收款的交易由 Paddle 自行处理贷记。

交易

你可以通过 transactions 属性轻松获取可计费模型的交易数组:

use App\Models\User;

$user = User::find(1);

$transactions = $user->transactions;

交易表示产品及购买行为的付款记录,并附有发票。只有已完成的交易才会存储在应用数据库中。

为客户列出交易时,可以使用交易实例的方法显示相关支付信息。例如,你可以在表格中列出每笔交易,让用户轻松下载发票:

<table>
    @foreach ($transactions as $transaction)
        <tr>
            <td>{{ $transaction->billed_at->toFormattedDateString() }}</td>
            <td>{{ $transaction->total() }}</td>
            <td>{{ $transaction->tax() }}</td>
            <td><a href="{{ route('download-invoice', $transaction->id) }}" target="_blank">Download</a></td>
        </tr>
    @endforeach
</table>

download-invoice 路由可以如下定义:

use Illuminate\Http\Request;
use Laravel\Paddle\Transaction;

Route::get('/download-invoice/{transaction}', function (Request $request, Transaction $transaction) {
    return $transaction->redirectToInvoicePdf();
})->name('download-invoice');

过往与即将进行的付款

可以使用 lastPayment 和 nextPayment 方法获取并显示客户循环订阅的过往或即将进行的付款:

use App\Models\User;

$user = User::find(1);

$subscription = $user->subscription();

$lastPayment = $subscription->lastPayment();
$nextPayment = $subscription->nextPayment();

这两个方法都会返回 Laravel\Paddle\Payment 实例;但当交易尚未通过 Webhook 同步时,lastPayment 返回 null;当计费周期已结束(例如订阅已取消)时,nextPayment 返回 null:

Next payment: {{ $nextPayment->amount() }} due on {{ $nextPayment->date()->format('d/m/Y') }}

测试

测试时,应手动测试计费流程,确保集成按预期工作。

对于自动化测试(包括 CI 环境中的测试),可以使用 Laravel HTTP 客户端模拟对 Paddle 的 HTTP 调用。虽然这样不会测试 Paddle 的实际响应,但可以在不实际调用 Paddle API 的情况下测试应用。

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

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

原文地址:https://learnku.com/docs/laravel/13.x/ca...

译文地址:https://learnku.com/docs/laravel/13.x/ca...

上一篇 下一篇
《L05 电商实战》
从零开发一个电商项目,功能包括电商后台、商品 & SKU 管理、购物车、订单管理、支付宝支付、微信支付、订单退款流程、优惠券等
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
贡献者:1
讨论数量: 0
发起讨论 只看当前版本


暂无话题~