feat(payment): add SePay gateway (VietQR bank transfer, VND)

.gitignore

@@ -136,6 +136,8 @@ docs/*
 !docs/PAYMENT_CN.md
 !docs/ADMIN_PAYMENT_INTEGRATION_API.md
 !docs/ASYNC_IMAGE_TASKS.md
+!docs/superpowers/
+!docs/superpowers/**
 !docs/legal/
 !docs/legal/*.md
 .serena/

backend/internal/handler/admin/setting_handler.go

@@ -356,6 +356,7 @@ func (h *SettingHandler) GetSettings(c *gin.Context) {
 		PaymentBalanceDisabled:                                 paymentCfg.BalanceDisabled,
 		PaymentBalanceRechargeMultiplier:                       paymentCfg.BalanceRechargeMultiplier,
 		PaymentSubscriptionUSDToCNYRate:                        paymentCfg.SubscriptionUSDToCNYRate,
+		PaymentSubscriptionUSDToVNDRate:                        paymentCfg.SubscriptionUSDToVNDRate,
 		PaymentRechargeFeeRate:                                 paymentCfg.RechargeFeeRate,
 		PaymentLoadBalanceStrat:                                paymentCfg.LoadBalanceStrategy,
 		PaymentProductNamePrefix:                               paymentCfg.ProductNamePrefix,

backend/internal/handler/admin/setting_handler_update.go

@@ -308,6 +308,7 @@ type UpdateSettingsRequest struct {
 	PaymentBalanceDisabled           *bool    `json:"payment_balance_disabled"`
 	PaymentBalanceRechargeMultiplier *float64 `json:"payment_balance_recharge_multiplier"`
 	PaymentSubscriptionUSDToCNYRate  *float64 `json:"payment_subscription_usd_to_cny_rate"`
+	PaymentSubscriptionUSDToVNDRate  *float64 `json:"payment_subscription_usd_to_vnd_rate"`
 	PaymentRechargeFeeRate           *float64 `json:"payment_recharge_fee_rate"`
 	PaymentLoadBalanceStrat          *string  `json:"payment_load_balance_strategy"`
 	PaymentProductNamePrefix         *string  `json:"payment_product_name_prefix"`
@@ -2048,6 +2049,7 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 			BalanceDisabled:               req.PaymentBalanceDisabled,
 			BalanceRechargeMultiplier:     req.PaymentBalanceRechargeMultiplier,
 			SubscriptionUSDToCNYRate:      req.PaymentSubscriptionUSDToCNYRate,
+			SubscriptionUSDToVNDRate:      req.PaymentSubscriptionUSDToVNDRate,
 			RechargeFeeRate:               req.PaymentRechargeFeeRate,
 			LoadBalanceStrategy:           req.PaymentLoadBalanceStrat,
 			ProductNamePrefix:             req.PaymentProductNamePrefix,
@@ -2324,6 +2326,7 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		PaymentBalanceDisabled:                                 updatedPaymentCfg.BalanceDisabled,
 		PaymentBalanceRechargeMultiplier:                       updatedPaymentCfg.BalanceRechargeMultiplier,
 		PaymentSubscriptionUSDToCNYRate:                        updatedPaymentCfg.SubscriptionUSDToCNYRate,
+		PaymentSubscriptionUSDToVNDRate:                        updatedPaymentCfg.SubscriptionUSDToVNDRate,
 		PaymentRechargeFeeRate:                                 updatedPaymentCfg.RechargeFeeRate,
 		PaymentLoadBalanceStrat:                                updatedPaymentCfg.LoadBalanceStrategy,
 		PaymentProductNamePrefix:                               updatedPaymentCfg.ProductNamePrefix,
@@ -2395,6 +2398,7 @@ func hasPaymentFields(req UpdateSettingsRequest) bool {
 		req.PaymentOrderTimeoutMin != nil || req.PaymentMaxPendingOrders != nil ||
 		req.PaymentEnabledTypes != nil || req.PaymentBalanceDisabled != nil ||
 		req.PaymentBalanceRechargeMultiplier != nil || req.PaymentSubscriptionUSDToCNYRate != nil ||
+		req.PaymentSubscriptionUSDToVNDRate != nil ||
 		req.PaymentRechargeFeeRate != nil ||
 		req.PaymentLoadBalanceStrat != nil || req.PaymentProductNamePrefix != nil ||
 		req.PaymentProductNameSuffix != nil || req.PaymentHelpImageURL != nil ||

backend/internal/handler/dto/settings.go

@@ -273,6 +273,7 @@ type SystemSettings struct {
 	PaymentBalanceDisabled           bool     `json:"payment_balance_disabled"`
 	PaymentBalanceRechargeMultiplier float64  `json:"payment_balance_recharge_multiplier"`
 	PaymentSubscriptionUSDToCNYRate  float64  `json:"payment_subscription_usd_to_cny_rate"`
+	PaymentSubscriptionUSDToVNDRate  float64  `json:"payment_subscription_usd_to_vnd_rate"`
 	PaymentRechargeFeeRate           float64  `json:"payment_recharge_fee_rate"`
 	PaymentLoadBalanceStrat          string   `json:"payment_load_balance_strategy"`
 	PaymentProductNamePrefix         string   `json:"payment_product_name_prefix"`

backend/internal/handler/payment_handler.go

@@ -148,6 +148,7 @@ func (h *PaymentHandler) GetCheckoutInfo(c *gin.Context) {
 		BalanceDisabled:               cfg.BalanceDisabled,
 		BalanceRechargeMultiplier:     cfg.BalanceRechargeMultiplier,
 		SubscriptionUSDToCNYRate:      cfg.SubscriptionUSDToCNYRate,
+		SubscriptionUSDToVNDRate:      cfg.SubscriptionUSDToVNDRate,
 		RechargeFeeRate:               cfg.RechargeFeeRate,
 		HelpText:                      cfg.HelpText,
 		HelpImageURL:                  cfg.HelpImageURL,
@@ -165,6 +166,7 @@ type checkoutInfoResponse struct {
 	BalanceDisabled               bool                            `json:"balance_disabled"`
 	BalanceRechargeMultiplier     float64                         `json:"balance_recharge_multiplier"`
 	SubscriptionUSDToCNYRate      float64                         `json:"subscription_usd_to_cny_rate"`
+	SubscriptionUSDToVNDRate      float64                         `json:"subscription_usd_to_vnd_rate"`
 	RechargeFeeRate               float64                         `json:"recharge_fee_rate"`
 	HelpText                      string                          `json:"help_text"`
 	HelpImageURL                  string                          `json:"help_image_url"`

backend/internal/handler/payment_webhook_handler.go

@@ -67,6 +67,12 @@ func (h *PaymentWebhookHandler) AirwallexWebhook(c *gin.Context) {
 	h.handleNotify(c, payment.TypeAirwallex)
 }
 
+// SepayNotify handles SePay transaction webhooks.
+// POST /api/v1/payment/webhook/sepay
+func (h *PaymentWebhookHandler) SepayNotify(c *gin.Context) {
+	h.handleNotify(c, payment.TypeSePay)
+}
+
 // handleNotify is the shared logic for all provider webhook handlers.
 func (h *PaymentWebhookHandler) handleNotify(c *gin.Context, providerKey string) {
 	var rawBody string
@@ -164,6 +170,13 @@ func extractOutTradeNo(rawBody, providerKey string) string {
 		if err := json.Unmarshal([]byte(rawBody), &payload); err == nil {
 			return strings.TrimSpace(payload.Data.Object.MerchantOrderID)
 		}
+	case payment.TypeSePay:
+		var payload struct {
+			Code *string `json:"code"`
+		}
+		if err := json.Unmarshal([]byte(rawBody), &payload); err == nil && payload.Code != nil {
+			return strings.TrimSpace(*payload.Code)
+		}
 	}
 	// For other providers (Stripe, Alipay direct, WxPay direct), the registry
 	// typically has only one instance, so no instance lookup is needed.
@@ -210,6 +223,9 @@ func writeSuccessResponse(c *gin.Context, providerKey string) {
 		c.JSON(http.StatusOK, wxpaySuccessResponse{Code: wxpaySuccessCode, Message: wxpaySuccessMessage})
 	case payment.TypeStripe, payment.TypeAirwallex:
 		c.String(http.StatusOK, "")
+	case payment.TypeSePay:
+		// SePay requires exactly {"success":true} with HTTP 200/201.
+		c.JSON(http.StatusOK, gin.H{"success": true})
 	default:
 		c.String(http.StatusOK, "success")
 	}

backend/internal/handler/payment_webhook_handler_test.go

@@ -54,6 +54,13 @@ func TestWriteSuccessResponse(t *testing.T) {
 			wantContentType: "text/plain",
 			wantBody:        "",
 		},
+		{
+			name:            "sepay returns JSON success body",
+			providerKey:     payment.TypeSePay,
+			wantCode:        http.StatusOK,
+			wantContentType: "application/json",
+			wantBody:        `{"success":true}`,
+		},
 		{
 			name:            "easypay returns plain text success",
 			providerKey:     "easypay",
@@ -178,6 +185,18 @@ func TestExtractOutTradeNo(t *testing.T) {
 			rawBody:     `{"name":"payment_intent.succeeded","data":{"object":{"merchant_order_id":"sub2_awx_123"}}}`,
 			want:        "sub2_awx_123",
 		},
+		{
+			name:        "sepay json payload with code",
+			providerKey: payment.TypeSePay,
+			rawBody:     `{"code":"sub2_20260814aB3kX9mQ","transferType":"in","transferAmount":50000}`,
+			want:        "sub2_20260814aB3kX9mQ",
+		},
+		{
+			name:        "sepay json payload with null code",
+			providerKey: payment.TypeSePay,
+			rawBody:     `{"code":null,"transferType":"in","transferAmount":50000}`,
+			want:        "",
+		},
 	}
 
 	for _, tt := range tests {

backend/internal/payment/currency.go

@@ -9,6 +9,9 @@ import (
 
 const DefaultPaymentCurrency = "CNY"
 
+// CurrencyVND is the only currency SePay bank transfers support.
+const CurrencyVND = "VND"
+
 type paymentCurrencyAmountUnit struct {
 	apiMinorUnit      int
 	maxFractionDigits int

backend/internal/payment/provider/factory.go

@@ -19,6 +19,8 @@ func CreateProvider(providerKey string, instanceID string, config map[string]str
 		return NewStripe(instanceID, config)
 	case payment.TypeAirwallex:
 		return NewAirwallex(instanceID, config)
+	case payment.TypeSePay:
+		return NewSePay(instanceID, config)
 	default:
 		return nil, fmt.Errorf("unknown provider key: %s", providerKey)
 	}

backend/internal/payment/provider/factory_test.go

@@ -0,0 +1,20 @@
+package provider
+
+import (
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/payment"
+)
+
+func TestCreateProviderSePay(t *testing.T) {
+	p, err := CreateProvider(payment.TypeSePay, "7", sepayTestConfig())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.ProviderKey() != payment.TypeSePay {
+		t.Fatalf("provider key = %q", p.ProviderKey())
+	}
+	if _, err := CreateProvider(payment.TypeSePay, "7", map[string]string{}); err == nil {
+		t.Fatal("expected config validation error from factory")
+	}
+}