Payment with Stripe

Introduction

Stripe is a payment processing platform that allows you to accept payments from your customers.

Create New Account

https://dashboard.stripe.com/

Webhook Configuration & Signing Secret

Endpoint: https://{domain.ltd}/api/billing/webhook/stripe
Events

# Charge (charge.dispute.)
charge.dispute.created
charge.dispute.funds_withdrawn
charge.dispute.closed

# Checkout
checkout.session.completed

# Customer (customer.subscription.)
customer.subscription.created
customer.subscription.deleted
customer.subscription.updated

# Invoice
invoice.created
invoice.paid
invoice.payment_failed

# Payment Intent
payment_intent.payment_failed
payment_intent.succeeded

# Radar
radar.early_fraud_warning.created
radar.early_fraud_warning.updated

# Refund
refund.created
refund.failed
refund.updated

Better-Auth Stripe Plugin

https://www.better-auth.com/docs/plugins/stripe

pnpm add @better-auth/stripe
pnpm add stripe@^18.0.0

Environment Variables

STRIPE_SECRET_KEY=sk_test_51O000000000000000000000
STRIPE_WEBHOOK_SECRET=whsec_51O000000000000000000000

通过以下链接查找 SECRET_KEY、WEBHOOK_SECRET、PRICE_ID 等

product + prices: https://dashboard.stripe.com/[account]/products?active=true
webhook: https://dashboard.stripe.com/[account]/workbench/webhooks

Stripe Configuration

Product & Price

Webhook

Webhook 的配置在 Stripe Dashboard 的 Workbench 中。

Webhook Endpoint

Better Auth 的 Stripe 插件默认已经实现了以下 3 个事件的处理。若需要处理更多的事件，详见：https://www.better-auth.com/docs/plugins/stripe#webhook-handling

Events:

checkout.session.completed Updates subscription status after checkout
customer.subscription.updated Updates subscription details when changed
customer.subscription.deleted Marks subscription as canceled

Hook URL（Better Auth Stripe 插件已实现）:

https://your-domain.com/api/auth/stripe/webhook

Subscription

Subscription Status

status: "active" | "canceled" | "incomplete" | "incomplete_expired" | "past_due" | "paused" | "trialing" | "unpaid";

Stripe Testing

https://docs.stripe.com/testing

Stripe Webhook Events

⚠️早期欺诈警告

针对早期欺诈的事件，进行实时通知；对其进行退款处理。

事件： radar.early_fraud_warning.created & radar.early_fraud_warning.updated

radar.early_fraud_warning.created
radar.early_fraud_warning.updated
checkout.session.completed 用户完成结账创建用户、记录首次订阅或充值积分。

💳支付与 Checkout 阶段事件

💡对于订阅型 SaaS，重点是 checkout.session.completed；对于充值型 SaaS，重点是 payment_intent.succeeded

事件类型	说明	用途
✅ `checkout.session.completed`	用户完成结账	创建用户、记录首次订阅或充值积分
`checkout.session.async_payment_succeeded`	异步支付成功（如 SEPA）	延迟确认支付的渠道（非卡类）
`checkout.session.async_payment_failed`	异步支付失败	处理支付失败通知
✅ `payment_intent.succeeded`	支付意图成功（一次性付款）	处理单次购买、积分充值
✅ `payment_intent.payment_failed`	支付失败	提示用户更新卡信息

🧾发票与账单事件（Invoice Events）

事件类型	说明	用途
✅ `invoice.created`	Stripe 创建新账单	订阅续费前的预告（可用于提醒）
✅ `invoice.paid`	发票支付成功	更新有效期、发放积分
✅ `invoice.payment_succeeded`	与 `invoice.paid` 相似，兼容旧版	同步账期成功
`invoice.payment_failed`	支付失败	通知用户更新支付方式
`invoice.upcoming`	发票将生成（通常在下一周期前 1 周）	提前提醒用户续费或扣款
`invoice.finalized`	发票定稿可下载	保存发票 URL（`invoice_pdf`）
`invoice.voided`	发票作废	清理对应账单记录

📊 订阅生命周期事件（Subscription Events）

事件类型	说明	用途
✅ `customer.subscription.created`	新订阅创建	保存 plan、trial、周期信息
✅ `customer.subscription.updated`	用户升级 / 降级 / 修改计划	更新套餐、周期、状态
✅ `customer.subscription.deleted`	用户取消订阅	标记状态为 canceled
`customer.subscription.trial_will_end`	试用即将结束（默认提前 3 天）	提醒用户续费或升级
`customer.subscription.pending_update_applied`	延迟更新的订阅已生效（如降级）	同步 plan_pending → plan_current
`customer.subscription.pending_update_expired`	延迟更新过期未生效	清空 pending 记录
`customer.subscription.resumed`	暂停后恢复	恢复订阅状态

💵 客户信息与支付方式事件

事件类型	说明	用途
`customer.created`	新客户创建	建立本地用户 → Stripe Customer 映射
`customer.updated`	客户资料更新（如邮箱、地址）	同步本地客户信息
`customer.deleted`	客户被删除	清理数据
`payment_method.attached`	用户新增支付方式	更新默认支付卡
`payment_method.updated`	支付方式更新（例如卡片过期）	同步显示信息
`payment_method.detached`	删除支付方式	检测是否需要提醒重新添加

退款与争议（Refund / Dispute）

事件类型	说明	用途
`charge.refunded`	退款已完成	更新退款状态
`charge.dispute.created`	用户发起争议	人工介入或冻结功能
`charge.dispute.closed`	争议结束	更新处理结果

Stripe Portal

设置(Settings) - 计费(Billing) - 客户门户(Portal)

启用客户门户，客户自助管理自己订阅和账单的选项。

订阅产品

客户可切换方案，并搜索添加产品

变更方案

当客户更改方案或者数量：按比例分配收款和信用额度

降级方案（需要技术

切换到更便宜的方案时：请等到开单周期结束后再更新当切换到更短的间隔期时：请等到开单周期结束后再更新

Payment with Stripe

Table of Contents