feat(pay-v2): P8 Task2 PaidEvent.Kind + SubscriptionProvider + Stripe 订阅 Checkout/取消

2026-07-10 17:51:42 +08:00
parent 799d74668d
commit 83e3551609
3 changed files with 139 additions and 6 deletions
@@ -41,10 +41,12 @@ func (p *Provider) Method() string { return "stripe" }

 func (p *Provider) Capabilities() provider.Capabilities {
 	return provider.Capabilities{
-		RenderTypes:      []provider.RenderType{provider.RenderRedirect},
-		SupportsRefund:   true, // P4:/v1/refunds
-		SettleCurrencies: []string{supportedCurrency},
-		Regions:          []string{"global"},
+		RenderTypes:       []provider.RenderType{provider.RenderRedirect},
+		SupportsRefund:    true, // P4:/v1/refunds
+		SupportsRecurring: true, // P8:Checkout mode=subscription,续费由 Stripe 网关调度
+		RecurringKind:     provider.RecurringKindGatewayScheduled,
+		SettleCurrencies:  []string{supportedCurrency},
+		Regions:           []string{"global"},
 	}
 }

@@ -111,6 +113,59 @@ func (p *Provider) Create(_ context.Context, req provider.CreateRequest) (*provi
 	}, nil
 }

+// CreateSubscriptionCheckout 建 Stripe 订阅(Checkout mode=subscription):返回 redirect 收银台。
+// 订阅号(sub_...)在用户完成支付后才生成 → 经 checkout.session.completed webhook 诞生 pay 订阅。
+// 续费由 Stripe 网关驱动(invoice.paid),pay 不主动 Charge(区别于 token_offsession)。
+func (p *Provider) CreateSubscriptionCheckout(_ context.Context, req provider.CreateRequest) (*provider.Session, error) {
+	if req.Currency != supportedCurrency {
+		return nil, fmt.Errorf("stripe: 仅支持 %s, got %s", supportedCurrency, req.Currency)
+	}
+	params := &gostripe.CheckoutSessionParams{
+		Mode:              gostripe.String(string(gostripe.CheckoutSessionModeSubscription)),
+		SuccessURL:        gostripe.String(req.ReturnURL),
+		ClientReferenceID: gostripe.String(req.OutTradeNo),
+		LineItems: []*gostripe.CheckoutSessionLineItemParams{{
+			Quantity: gostripe.Int64(1),
+			PriceData: &gostripe.CheckoutSessionLineItemPriceDataParams{
+				Currency:   gostripe.String(strings.ToLower(supportedCurrency)),
+				UnitAmount: gostripe.Int64(req.AmountMinor),
+				// 最小可行:固定月付。周期(month/year)后续由 product 定价档下发,此处留 month 默认。
+				Recurring: &gostripe.CheckoutSessionLineItemPriceDataRecurringParams{
+					Interval: gostripe.String("month"),
+				},
+				ProductData: &gostripe.CheckoutSessionLineItemPriceDataProductDataParams{
+					Name: gostripe.String(req.Subject),
+				},
+			},
+		}},
+		// 订阅 metadata 带 out_trade_no,便于人工对账;续费/取消映射实际走 sub id 反查,不依赖它。
+		SubscriptionData: &gostripe.CheckoutSessionSubscriptionDataParams{
+			Metadata: map[string]string{"out_trade_no": req.OutTradeNo},
+		},
+	}
+	if v := req.Metadata["pay_sub_id"]; v != "" {
+		params.SubscriptionData.Metadata["pay_sub_id"] = v
+	}
+	sess, err := p.sc.CheckoutSessions.New(params)
+	if err != nil {
+		return nil, fmt.Errorf("stripe: 创建订阅 Checkout 失败: %w", err)
+	}
+	return &provider.Session{
+		ProviderRef: sess.ID,
+		RenderType:  provider.RenderRedirect,
+		Payload:     map[string]any{"url": sess.URL},
+	}, nil
+}
+
+// CancelSubscription 立即取消 Stripe 订阅(不等本期末)。Stripe 随后发 customer.subscription.deleted,
+// 入站处理器幂等标 canceled,与本地主动标一致收敛。
+func (p *Provider) CancelSubscription(_ context.Context, providerSubRef string) error {
+	if _, err := p.sc.Subscriptions.Cancel(providerSubRef, nil); err != nil {
+		return fmt.Errorf("stripe: 取消订阅失败: %w", err)
+	}
+	return nil
+}
+
 func (p *Provider) VerifyCallback(_ context.Context, in provider.CallbackInput) (*provider.PaidEvent, error) {
 	sig := in.Headers["Stripe-Signature"]
 	// stripe-go 默认 ConstructEvent 会额外校验 event.api_version == SDK 编译期常量
@@ -6,6 +6,7 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -26,11 +27,19 @@ func fakeStripeAPI(t *testing.T) *httptest.Server {
 		w.Header().Set("Content-Type", "application/json")
 		switch {
 		case r.Method == http.MethodPost && strings.HasPrefix(r.URL.Path, "/v1/checkout/sessions"):
-			// 创建 session
-			fmt.Fprint(w, `{"id":"cs_test_123","object":"checkout.session","url":"https://checkout.stripe.com/c/pay/cs_test_123","amount_total":2999,"currency":"usd","payment_status":"unpaid"}`)
+			// 创建 session。一次性(mode=payment)与订阅(mode=subscription)共用此分支,
+			// 靠 form body 是否带 "subscription" 区分,回不同 id 供各自用例断言。
+			b, _ := io.ReadAll(r.Body)
+			if strings.Contains(string(b), "subscription") {
+				fmt.Fprint(w, `{"id":"cs_sub_123","object":"checkout.session","url":"https://checkout.stripe.com/c/pay/cs_sub_123","mode":"subscription","amount_total":2999,"currency":"usd","payment_status":"unpaid"}`)
+			} else {
+				fmt.Fprint(w, `{"id":"cs_test_123","object":"checkout.session","url":"https://checkout.stripe.com/c/pay/cs_test_123","amount_total":2999,"currency":"usd","payment_status":"unpaid"}`)
+			}
 		case r.Method == http.MethodGet && strings.Contains(r.URL.Path, "/v1/checkout/sessions/cs_test_123"):
 			// 查询 session — 已付
 			fmt.Fprint(w, `{"id":"cs_test_123","object":"checkout.session","amount_total":2999,"currency":"usd","payment_status":"paid"}`)
+		case r.Method == http.MethodDelete && strings.Contains(r.URL.Path, "/v1/subscriptions/sub_cancel_ok"):
+			fmt.Fprint(w, `{"id":"sub_cancel_ok","object":"subscription","status":"canceled"}`)
 		default:
 			http.Error(w, `{"error":{"message":"not found"}}`, http.StatusNotFound)
 		}
@@ -47,6 +56,41 @@ func newStripe(t *testing.T, ts *httptest.Server) *st.Provider {
 	return st.New(sc, whSecret)
 }

+func TestCreateSubscriptionCheckout(t *testing.T) {
+	ts := fakeStripeAPI(t)
+	defer ts.Close()
+	p := newStripe(t, ts)
+
+	sess, err := p.CreateSubscriptionCheckout(context.Background(), provider.CreateRequest{
+		OutTradeNo: "PAY-S1", Subject: "Pro Monthly", AmountMinor: 2999, Currency: "USD",
+		ReturnURL: "https://x/return", Metadata: map[string]string{"pay_sub_id": "SUB-1"},
+	})
+	if err != nil {
+		t.Fatalf("create sub checkout: %v", err)
+	}
+	if sess.RenderType != provider.RenderRedirect || sess.ProviderRef != "cs_sub_123" {
+		t.Fatalf("session = %+v", sess)
+	}
+}
+
+func TestCancelSubscription(t *testing.T) {
+	ts := fakeStripeAPI(t)
+	defer ts.Close()
+	p := newStripe(t, ts)
+	if err := p.CancelSubscription(context.Background(), "sub_cancel_ok"); err != nil {
+		t.Fatalf("cancel: %v", err)
+	}
+}
+
+func TestCapabilitiesRecurring(t *testing.T) {
+	ts := fakeStripeAPI(t)
+	defer ts.Close()
+	c := newStripe(t, ts).Capabilities()
+	if !c.SupportsRecurring || c.RecurringKind != provider.RecurringKindGatewayScheduled {
+		t.Fatalf("caps = %+v", c)
+	}
+}
+
 func TestCreateCheckoutRedirect(t *testing.T) {
 	ts := fakeStripeAPI(t)
 	defer ts.Close()