【免费下载链接】flexpriceUsage-based pricing and billing for developers Cloud or self-hosted ⚙️ No-code UI Realtime usage metering Credits top-ups Control feature access项目地址https://gitcode.com/gh_mirrors/fl/flexprice点击查看免费下载本文以 FlexPrice 开源仓库中的 payment-link-architecture.md 为核心骨架结合仓库源码internal/api/v1/payment.go、internal/ee/service/payment_processor.go、internal/integration/stripe/webhook/handler.go等展开系统讲解支付链接功能的完整生命周期如何为发票创建支付链接、如何调用 Stripe Checkout Session、如何通过签名验证的 Webhook 驱动支付状态机、以及支付成功后如何与发票对账。读完本文你将掌握 FlexPrice 支付链接的 API 用法、状态机设计、Webhook 幂等保护机制与故障排查方法。一、什么是 Payment Link 功能Payment Link支付链接是 FlexPrice 面向开发者的按量计费/账单平台中一项关键的收款能力客户无需注册、无需绑定卡只需点击链接即可在 Stripe 的安全支付页完成对发票Invoice的付款。从功能定位看它属于 Payment 模块下的一种支付方式PaymentMethodType PAYMENT_LINK与CARD保存卡直扣、ACH、OFFLINE、CREDITS钱包积分等支付方式并列。支付链接特别适合线下/外部渠道生成的发票需要给客户一个自助付款入口不希望在应用内收集银行卡信息的场景将支付 UI 完全托管给 Stripe需要「生成链接 → 客户稍后支付 → 异步回调对账」这种非同步结算节奏的场景。核心链路一句话概括系统先创建一笔INITIATED状态的支付记录 → 调用 Stripe 创建 Checkout Session 拿到支付 URL → 客户在 Stripe 页面完成付款 → Stripe 通过 Webhook 回传结果 → 系统校验签名、更新支付状态、与发票对账。二、整体架构与支付状态机2.1 支付状态PaymentStatusFlexPrice 将支付状态定义为强类型枚举见 internal/types/payment.go状态含义INITIATED支付记录已创建尚未发给网关支付链接的初始状态PENDING支付链接已创建成功等待客户付款PROCESSING处理中创建链接/扣款过程中的临时状态SUCCEEDED支付成功终态语义但允许后续退款/作废OVERPAID超额支付FAILED支付失败终态REFUNDED/PARTIALLY_REFUNDED已退款 / 部分退款终态VOIDED已作废终态从源码看IsTerminal()将VOIDED、REFUNDED、FAILED视为终态而SUCCEEDED之所以不是终态是因为 AUTH 类支付还可以从成功流转到退款或作废internal/types/payment.go。2.2 状态机与合法流转FlexPrice 在状态机层面做了很强的约束每个状态只允许迁移到白名单内的目标状态非法迁移会被ValidateTransitionTo拒绝并返回校验错误防止「调用方直接把支付改成SUCCEEDED而完全绕过网关」这类数据造假internal/types/payment.go。文档给出的支付链接核心状态流INITIATED → PENDING → PROCESSING → SUCCEEDED (Final) INITIATED → PENDING → PROCESSING → FAILED (Final)对应到源码中的paymentStatusTransitions映射INITIATED可直接迁移到PENDING、PROCESSING、SUCCEEDED、OVERPAID、FAILEDPENDING可迁移到PROCESSING、SUCCEEDED、OVERPAID、FAILEDFAILED只能自迁移internal/types/payment.go。重要约束一旦支付到达SUCCEEDED任何 Webhook 都不能再改变它——这是整个系统防止重复 Webhook 造成数据损坏的核心保护线后文详述。2.3 支付方式与目的类型支付方式CARD、ACH、OFFLINE、CREDITS、PAYMENT_LINK、UPIinternal/types/payment.go目的类型INVOICE对发票收款、CUSTOMER用于给客户 tokenize 支付方式的授权扣款见 internal/types/payment.go。三、创建支付链接一次 API 调用背后的完整流程3.1 API 端点支付链接的创建走通用支付创建接口路由注册见 internal/api/router.goPOST /api/v1/payments请求体结合 internal/api/dto/payment.go 的CreatePaymentRequest{ idempotency_key: optional-uuid, destination_type: INVOICE, destination_id: invoice-uuid, payment_method_type: PAYMENT_LINK, payment_gateway: stripe, amount: 1000, currency: USD, success_url: https://your-app.com/success, cancel_url: https://your-app.com/cancel, process_payment: false, save_card_and_make_default: false, gateway_options: { stripe: { tax_id_collection_enabled: true } } }关键字段说明字段说明备注destination_type必填支付目的类型当前支持INVOICE/CUSTOMERdestination_id必填目标实体 ID发票场景传发票 UUIDpayment_method_type必填支付方式支付链接传PAYMENT_LINKpayment_gateway网关支付链接必须显式指定网关否则校验报错amount必填金额decimal类型序列化为字符串currency必填ISO 三字母币种入库时统一转为小写process_payment是否立即处理默认true创建链接通常传false先落库再单独触发处理success_url/cancel_url支付完成/取消后的跳转地址存入gateway_metadatagateway_options.stripe.tax_id_collection_enabled是否在 Checkout 收集税号仅允许用于 Stripe PAYMENT_LINK 组合其他组合会校验失败其中idempotency_key用于幂等去重save_card_and_make_default表示是否在支付成功后把卡保存为客户的默认支付方式。3.2 创建阶段CreatePayment做了什么入口 Handler 见 internal/api/v1/payment.go实际业务在paymentService.CreatePaymentinternal/ee/service/payment.goDTO → 领域模型CreatePaymentRequest.ToPayment(ctx)完成币种校验、网关选项校验、初始化gateway_metadata写入success_url、cancel_url、save_card_and_make_default、tax_id_collection_enabledinternal/api/dto/payment.go。支付链接的初始状态被强制为INITIATED并设置TrackAttempts true、清空PaymentMethodID、置空GatewayPaymentID若PaymentGateway为空则直接校验报错internal/api/dto/payment.go。校验发票发票必须存在、必须满足支付资格CUSTOMER目的则校验客户存在internal/ee/service/payment.go。落库后返回PaymentResponse此时payment_status为INITIATED。注意创建阶段并不会立即调用 Stripe。文档明确「System creates a payment record with status INITIATED」——支付链接的真正创建发生在处理阶段见第四节这样设计让「创建支付记录」与「请求网关」解耦失败时不会产生孤儿记录。3.3 响应结构PaymentResponseinternal/api/dto/payment.go除基础字段外对支付链接会额外从GatewayMetadata[payment_url]中提取payment_url返回给客户端internal/api/dto/payment.go。四、处理支付创建真实支付链接ProcessPayment4.1 API 端点POST /api/v1/payments/{payment-id}/process对应PaymentHandler.ProcessPaymentinternal/api/v1/payment.go内部委托给PaymentProcessorService.ProcessPaymentinternal/ee/service/payment_processor.go。4.2 处理流程细节状态准入检查支付链接类型同时接受INITIATED和PENDING幂等重放安全其他支付方式只接受PENDING。状态不符返回ErrInvalidOperationinternal/ee/service/payment_processor.go。临时置为PROCESSING并发布payment.pending系统事件internal/ee/service/payment_processor.go。按支付方式分发支付链接走handlePaymentLinkCreation若已是PENDING则直接跳过已处理过。网关路由handlePaymentLinkCreation根据payment_gateway字段路由到 Stripe / Razorpay / Nomod / Chargebee默认 Stripeinternal/ee/service/payment_processor.go。4.3 Stripe 支付链接创建的关键逻辑handleStripePaymentLinkCreationinternal/ee/service/payment_processor.go会从GatewayMetadata中取出success_url、cancel_url组装 Stripe 请求发票 ID、客户 ID、金额、币种、跳转地址、save_card_and_make_default、tax_id_collection_enabled在 metadata 中注入flexprice_payment_id——这是后续 Webhook 将 Stripe 事件关联回 FlexPrice 支付记录的关键锚点internal/ee/service/payment_processor.go调用stripeIntegration.PaymentSvc.CreatePaymentLink真实 Stripe 实现见 internal/integration/stripe/payment.go内部会校验发票未支付、未作废、金额不超过剩余应付款、币种与发票一致并确保客户已同步到 StripeEnsureCustomerSyncedToStripeinternal/integration/stripe/payment.go成功把GatewayTrackingID记为 Checkout Session IDcs_...、GatewayPaymentID记为 PaymentIntent IDpi_...将payment_url、session_id写入gateway_metadata状态更新为PENDINGinternal/ee/service/payment_processor.go失败Stripe SDK 报错状态保持INITIATED若已被临时改成PROCESSING则回滚回INITIATED不写failed_at和error_message向客户端返回错误、允许重试internal/ee/service/payment_processor.go。文档总结的创建阶段状态流与源码完全一致INITIATED → PENDING (if Stripe succeeds) INITIATED → INITIATED (if Stripe fails)五、数据库字段与持久化模型文档列出的核心字段payment_status、gateway_tracking_id、gateway_payment_id、payment_method_id、succeeded_at、failed_at、error_message在领域模型 internal/domain/payment/model.go 中均有对应且实际模型更丰富字段存储内容示例来源确认payment_status当前状态INITIATED、PENDING、SUCCEEDED、FAILEDmodel.gogateway_tracking_id网关侧「预支付句柄」Checkout Session / 托管页 / 网关发票cs_test_1234567890model.gogateway_payment_id网关侧交易 IDPaymentIntentpi_1234567890model.gogateway_metadata网关相关元数据payment_url、session_id、success_url等—model.gopayment_method_id支付方式 ID支付链接场景必须为空pm_1234567890model.gosucceeded_at/failed_at成功 / 失败时间戳2024-01-15T10:30:00Zmodel.goerror_message失败原因Card declinedmodel.gotrack_attempts是否记录每次扣款尝试true支付链接恒为 truemodel.goattempts支付尝试明细PaymentAttempt数组每次尝试的状态/错误/网关尝试 IDmodel.go模型校验Payment.Validate也强制了「支付链接不得携带payment_method_id」的规则internal/domain/payment/model.go。支付记录表名为payments尝试表为payment_attemptsinternal/domain/payment/model.go。六、Webhook 处理从签名验证到状态更新6.1 端点与签名验证Stripe Webhook 入口为POST /api/v1/webhooks/stripe/{tenant-id}/{environment-id}路由注册见 internal/api/router.goHandler 见 internal/api/v1/webhook.go。处理步骤从 URL 路径取tenant_id、environment_id并注入上下文——这实现了多租户 多环境的隔离每个环境有独立的 Stripe 连接配置与 Webhook Secret读取原始请求体校验Stripe-Signature头通过stripeIntegration.PaymentSvc.ParseWebhookEvent(body, signature, webhookSecret)完成签名验证与事件解析——验证失败直接返回 400只有 Stripe 的事件才会进入处理逻辑交由stripeIntegration.WebhookHandler.HandleWebhookEvent分发处理internal/integration/stripe/webhook/handler.go。事件类型常量定义在 internal/types/payment_gateway.go。6.2 Webhook 类型与处理映射文档所列 6 种 Webhook 类型在源码中均有对应定义处理语义如下Webhook 类型触发时机处理动作checkout.session.completed客户完成 Checkout标记支付为SUCCEEDED并触发发票对账checkout.session.async_payment_succeeded异步付款如银行转账成功标记支付为SUCCEEDEDcheckout.session.async_payment_failed异步付款失败标记支付为FAILEDcheckout.session.expired支付链接过期标记支付为FAILEDpayment_intent.payment_failed立即扣款失败如卡被拒标记支付为FAILEDpayment_intent.succeeded扣款成功标记支付为SUCCEEDED其中checkout.session.completed与payment_intent.succeeded/payment_intent.payment_failed在 Webhook Handler 中有显式实现internal/integration/stripe/webhook/handler.go未识别的事件类型仅记录日志并返回 nil不视为错误避免无谓的 Stripe 重试风暴。6.3 核心处理逻辑checkout.session.completed 为例handleCheckoutSessionCompletedinternal/integration/stripe/webhook/handler.go完整呈现了文档描述的「三查两更新」解析 Checkout Session从metadata[flexprice_payment_id]反查 FlexPrice 支付记录没有该标记则跳过幂等保护检查若支付已是SUCCEEDED直接跳过、不更新防止重复 Webhook 覆盖终态handler.go携带 PaymentIntent ID 调用HandleFlexPriceCheckoutPayment完成支付状态更新与发票对账对关联了 Checkout Session 的支付还会走handleCheckoutSessionForPayment处理 Session 的完成/过期/失败必要时对「Session 已结束但资金晚到账」的情况执行refundLateCapturedPayment退款兜底handler.go。重复 Webhook 防护双保险一方面支付达到SUCCEEDED后拒绝一切改写另一方面 Handler 对每个事件都先查库确认当前状态再做更新多个payment_intent.succeeded并发到达也不会产生脏数据。七、支付成功后发票对账与后处理支付成功并不止步于状态更新。handlePostProcessing→handleInvoicePostProcessinginternal/ee/service/payment_processor.go会自动完成汇总该发票所有SUCCEEDED状态的支付金额计算AmountPaid与AmountRemaining若剩余金额为 0发票标记SUCCEEDED若发票仍是DRAFT则顺带FINALIZED并触发invoice.finalized出站 Webhook 与收入事实revenue facts翻转部分支付发票保持PENDING文档强调系统支持部分支付场景对「购买积分」型发票metadata 带wallet_transaction_id支付完成后自动完成钱包交易、给客户钱包入账internal/ee/service/payment_processor.go。八、安全特性总结Webhook 签名验证每个 Webhook 都必须通过Stripe-Signature 环境级 Webhook Secret 校验非 Stripe 来源一律 400internal/api/v1/webhook.go支付终态保护SUCCEEDED后的支付不可被任何 Webhook 改写从状态机ValidateTransitionTo与 Webhook 处理幂等检查两个层面双重保障环境隔离每个 tenant environment 独立配置 Stripe 连接与 Webhook SecretWebhook URL 直接携带{tenant-id}/{environment-id}元数据锚点通过flexprice_payment_id将 Stripe 事件安全地关联回内部支付记录避免误关联他人支付。九、错误处理设计场景系统行为设计意图Stripe SDK 创建链接失败状态保持INITIATED返回错误给客户端允许重试不给失败的尝试留下FAILED污点重试即可继续payment_processor.goWebhook 对应未知支付记录 warning 日志返回成功200不触发 Stripe 重试不因单条异常事件阻塞整个队列留待人工排查重复 Webhook幂等检查跳过对SUCCEEDED的更新多个 Webhook 不会损坏数据状态非法迁移ValidateTransitionTo拒绝防止绕过网关直接改库造假types/payment.go金额/币种不匹配创建阶段即校验从源头避免对账偏差stripe/payment.go十、测试验证与实战建议仓库在 internal/ee/service/payment_test.go 中提供了与文档测试路径一一对应的单测TestCreatePaymentWithPaymentLink/TestCreatePaymentLink_InitiatedStatus验证创建支付链接后状态为INITIATEDpayment_test.goTestCreatePaymentLink_TaxIDCollection验证tax_id_collection_enabled仅允许 Stripe PAYMENT_LINK 组合其他组合校验失败payment_test.goTestPaymentProcessor_PaymentLinkFlow走完整「创建 → 处理 → 状态流转」链路payment_test.go。对应文档的手动验收路径Happy PathPOST /api/v1/payments创建支付链接 → 状态INITIATEDPOST /api/v1/payments/{id}/process→ 状态PENDING返回payment_url客户点击链接付款 → Stripe 回调checkout.session.completed→ 状态SUCCEEDED发票AmountRemaining归零。Error Path创建 →INITIATEDStripe 调用失败 → 状态仍为INITIATED重试 process →PENDING。Card Decline客户使用被拒卡 → Webhookpayment_intent.payment_failed→ 状态FAILEDerror_message记录原因。常见问题排查对应文档「Common Issues」症状排查方向状态卡在INITIATED链接未生成检查 Stripe API Key / 连接配置connections表是否在当前环境有效查看 process 返回的错误客户已付款但状态未更新Webhook 未收到在 Stripe Dashboard 核对 Webhook Endpoint URL 是否为.../api/v1/webhooks/stripe/{tenant-id}/{environment-id}并确认该环境配置了正确的 Webhook Secret数据库状态与 Stripe 不一致检查 Webhook 处理日志internal/api/v1/webhook.go会记录 payload 长度与签名验证结果、确认支付记录未被误标SUCCEEDED锁死十一、总结FlexPrice 的 Payment Link 功能是一个「简单但完整」的异步支付闭环以INITIATED → PENDING → SUCCEEDED/FAILED的状态机为主线通过flexprice_payment_id元数据把 Stripe Checkout Session 与内部支付记录可靠关联以签名验证 终态幂等双保险保证 Webhook 处理安全支付成功后自动完成发票对账、发票定稿与钱包入账等后处理。该设计既保证了多租户多环境隔离下的事件安全也通过「失败保持INITIATED可重试」的容错策略支撑了真实生产场景。相关实现与测试可进一步阅读 internal/ee/service/payment_processor.go、internal/integration/stripe/webhook/handler.go 与 internal/ee/service/payment_test.go。赞分享【免费下载链接】flexpriceUsage-based pricing and billing for developers Cloud or self-hosted ⚙️ No-code UI Realtime usage metering Credits top-ups Control feature access项目地址https://gitcode.com/gh_mirrors/fl/flexprice点击查看免费下载相关推荐Flexprice Payment Lifecycle 状态机解析从 InitiatePayment 到 Webhook 回执的统一支付生命周期管理Flexprice Payment Lifecycle 状态机解析从 InitiatePayment 到 Webhook 回执的统一支付生命周期管理 导读 本Easy-Vibe 支付接入实战用 Stripe 搭建最小可行收费系统从 Checkout Session 到 Webhook 验签Easy Vibe 支付接入实战用 Stripe 搭建最小可行收费系统从 Checkout Session 到 Webhook 验签 当你的产品已经拥有页教程文档Flexprice 续期支付门控Subscription Renewal Gating设计解读从续期发票支付到订阅状态机的完整闭环Flexprice 续期支付门控Subscription Renewal Gating设计解读从续期发票支付到订阅状态机的完整闭环 本文围绕 Flexpr上一篇CANN训练营SoftshrinkGrad任务书下一篇Frog命令行技巧如何使用-e参数一键提取并复制文本到剪贴板创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考