laravel-cashier-stripe

用途

Laravel Cashier (Stripe) 技能用于协助在 Laravel 应用中开发基于 Stripe 的订阅计费、支付处理与 Stripe 集成。当需要实现订阅计费、设置 Stripe 循环付款、管理客户订阅与试用、处理一次性收费或发票、处理 Stripe Webhook 事件、实现 Stripe Checkout 结账流程、管理客户支付方式、使用 Stripe 发票与账单门户、设置试用期与按比例计费逻辑，或调试 Laravel 中的 Stripe 集成问题时，可触发该技能。

主要能力

安装与配置：通过 Composer 安装 Cashier，发布并运行迁移，可选发布配置文件。
Billable 模型：通过 Billable trait 为 Eloquent 模型（通常为 User）添加订阅与支付功能。
订阅管理：创建订阅（支持试用天数、促销码、Checkout）、检查订阅状态、检查特定产品订阅、检查试用状态、切换套餐、跳过试用、取消订阅（立即或期末）、恢复处于宽限期的订阅。
支付方式管理：创建 Setup Intent、获取支付方式列表与默认支付方式、添加与更新默认支付方式。
一次性收费与发票：一次性收费、为服务创建发票、退款；获取全部发票、即将到来的发票、下载发票 PDF。
账单门户：重定向到 Stripe 账单门户。
客户管理：创建或获取 Stripe 客户、更新客户信息、管理税务 ID（创建与删除）。
Webhook：Stripe 会发送订阅变更、支付失败、发票更新等 Webhook 事件，Cashier 自动处理常见 Webhook，也可通过监听特定事件扩展功能。
Checkout 会话：Stripe Checkout 提供预构建支付页面，Cashier 简化订阅与一次性产品的 Checkout 会话创建。

使用方式

安装与迁移：

composer require laravel/cashier
php artisan vendor:publish --tag="cashier-migrations"
php artisan migrate
php artisan vendor:publish --tag="cashier-config"

配置 Billable 模型：

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

创建订阅（含试用与 Checkout）：

$user->newSubscription('default', 'price_monthly')
    ->trialDays(5)
    ->allowPromotionCodes()
    ->checkout([
        'success_url' => route('checkout.success'),
        'cancel_url' => route('checkout.cancel'),
    ]);

检查订阅状态：

if ($user->subscribed('default')) {
    // 用户已订阅 "default" 计划
}

if ($user->subscribedToProduct('prod_premium', 'default')) {
    // 用户已订阅 premium 产品
}

if ($user->subscription('default')->onTrial()) {
    // 用户仍在试用期
}

管理支付方式：

$intent = $user->createSetupIntent();
$paymentMethods = $user->paymentMethods();
$defaultMethod = $user->defaultPaymentMethod();
$user->addPaymentMethod($paymentMethodId);
$user->updateDefaultPaymentMethod($paymentMethodId);

切换套餐：

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

一次性收费与发票：

$user->charge(1000, $paymentMethodId, [
    'description' => 'One-time charge',
]);

$user->invoiceFor('Premium Support', 5000, [
    'description' => '3 months of premium support',
]);

$user->refund($chargeId);

取消与恢复订阅：

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

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

发票与账单门户：

$invoices = $user->invoices();
$upcomingInvoice = $user->upcomingInvoice('default');
return $user->invoices()->first()->download();

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

客户与税务 ID：

$stripeCustomer = $user->createOrGetStripeCustomer();
$user->updateStripeCustomer([
    'name' => 'Updated Name',
    'email' => 'updated@example.com',
]);
$taxId = $user->createTaxId('eu_vat', 'BE0123456789');
$user->deleteTaxId('txi_belgium');

环境变量配置（.env）：

STRIPE_KEY=pk_test_your_stripe_publishable_key
STRIPE_SECRET=sk_test_your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_signing_secret
CASHIER_CURRENCY=usd

开发阶段使用测试模式密钥（pk_test_、sk_test_），生产环境切换为正式密钥（pk_live_、sk_live_）。

适用场景

在 Laravel 应用中实现订阅计费与循环付款。
管理客户订阅、试用、套餐变更与按比例计费。
处理一次性收费、发票与退款。
集成 Stripe Checkout 结账流程与账单门户。
处理 Stripe Webhook 事件。
管理客户支付方式与税务 ID。
调试 Laravel 中的 Stripe 集成问题。

限制与注意事项

Cashier 要求 PHP 8.1+ 与 Laravel 10.0+。
生产环境应配置 Webhook 以确保可靠的订阅管理。
开发与测试阶段应使用 Stripe 测试模式。
Billable trait 可添加到任意 Eloquent 模型，不限于 User。
Cashier 自动处理大多数 Webhook 事件。
可考虑使用 Stripe 账单门户实现客户自助服务。
上线前应充分测试订阅流程。
该技能基于 Laravel 12.x 的 Laravel Cashier，最新信息请参考官方文档 https://laravel.com/docs/billing。
测试卡号示例：成功 4242 4242 4242 4242；拒付 4000 0000 0000 0002；需要验证 4000 0025 0000 3155。
技能包含 references/other.md 参考文件，涵盖安装配置、订阅管理、支付方式与 Setup Intent、一次性收费与发票、Stripe Checkout 集成、Webhook 处理、客户门户集成、税务 ID 管理、测试策略等详细内容。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项