fix(sca): re-fetch payment intent when error response omits next_action

* feat(sca): add order status endpoint adn SCA error code mapping

adds server-side infra for the upcoming SCA / 3DS challenge flow im
working on. No behavior change to existing checkout paths.

* fix(sca): suppress unused lint on SCA scaffolding helpers

.gitignore

@@ -5,6 +5,9 @@
 .env.example
 .env.prod
 
+docs/sca-psd2-compliance.md
+accept-a-payment/
+
 
 FULFILLMENT.md
 .tmp-gocache/

api/handlers/cart.go

@@ -24,11 +24,12 @@ import (
 
 type CartHandler struct {
 	stripeKey string
+	appURL    string
 }
 
 // NewCartHandler creates a new cart handler with the Stripe secret key
-func NewCartHandler(stripeSecretKey string) *CartHandler {
-	return &CartHandler{stripeKey: stripeSecretKey}
+func NewCartHandler(stripeSecretKey, appURL string) *CartHandler {
+	return &CartHandler{stripeKey: stripeSecretKey, appURL: appURL}
 }
 
 // getOrCreateCart finds the users cart or creates one.
@@ -391,16 +392,15 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 	// Charge the card. The idempotency key is tied to the order ID so retries
 	// never produce a double charge.
 	piParams := &stripe.PaymentIntentParams{
-		Amount:        stripe.Int64(int64(total)),
-		Currency:      stripe.String(string(stripe.CurrencyUSD)),
-		Customer:      stripe.String(user.StripeCustomerID),
-		PaymentMethod: stripe.String(paymentMethodID),
-		AutomaticPaymentMethods: &stripe.PaymentIntentAutomaticPaymentMethodsParams{
-			Enabled:        stripe.Bool(true),
-			AllowRedirects: stripe.String("never"),
-		},
-		Confirm:     stripe.Bool(true),
-		Description: stripe.String(fmt.Sprintf("terminal.shop order #%d", order.ID)),
+		Amount:             stripe.Int64(int64(total)),
+		Currency:           stripe.String(string(stripe.CurrencyUSD)),
+		Customer:           stripe.String(user.StripeCustomerID),
+		PaymentMethod:      stripe.String(paymentMethodID),
+		OffSession:         stripe.Bool(true),
+		PaymentMethodTypes: stripe.StringSlice([]string{"card"}),
+		ReturnURL:          stripe.String(h.appURL + "/post-3ds"),
+		Confirm:            stripe.Bool(true),
+		Description:        stripe.String(fmt.Sprintf("terminal.shop order #%d", order.ID)),
 		Shipping: &stripe.ShippingDetailsParams{
 			Name: stripe.String(address.Name),
 			Address: &stripe.AddressParams{
@@ -423,13 +423,17 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 	stripeDur := time.Since(stripeStart).Seconds()
 	if err != nil {
 		middleware.ObserveStripeRequest("payment_intent_create", "error", stripeDur)
-		db.Model(&order).Update("status", models.OrderStatusFailed)
 		if stripeErr, ok := err.(*stripe.Error); ok {
+			if stripeErr.Code == stripe.ErrorCodeAuthenticationRequired && stripeErr.PaymentIntent != nil {
+				h.respondRequiresAction(w, &order, stripeErr.PaymentIntent)
+				return
+			}
+			db.Model(&order).Update("status", models.OrderStatusFailed)
 			switch stripeErr.Type {
 			case stripe.ErrorTypeCard:
 				middleware.RecordCartConversion("card_declined")
 				audit.OrderFailed(userID, order.ID, total, stripeErr.Msg)
-				utils.RespondError(w, http.StatusPaymentRequired, "CARD_DECLINED", stripeErr.Msg, nil)
+				utils.RespondError(w, http.StatusPaymentRequired, mapStripeCardErrCode(stripeErr.Code), stripeErr.Msg, nil)
 			case stripe.ErrorTypeInvalidRequest:
 				middleware.RecordCartConversion("stripe_invalid_request")
 				audit.OrderFailed(userID, order.ID, total, stripeErr.Msg)
@@ -441,6 +445,7 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 			}
 			return
 		}
+		db.Model(&order).Update("status", models.OrderStatusFailed)
 		middleware.RecordCartConversion("stripe_error")
 		audit.OrderFailed(userID, order.ID, total, err.Error())
 		utils.RespondError(w, http.StatusInternalServerError, "PAYMENT_FAILED", "payment failed", nil)
@@ -448,6 +453,11 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 	}
 	middleware.ObserveStripeRequest("payment_intent_create", "success", stripeDur)
 
+	if pi.Status == stripe.PaymentIntentStatusRequiresAction {
+		h.respondRequiresAction(w, &order, pi)
+		return
+	}
+
 	// Commit payment ID and clear cart in a single transaction.
 	txErr := db.Transaction(func(tx *gorm.DB) error {
 		order.StripePaymentID = pi.ID
@@ -489,3 +499,86 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 		"order": order,
 	})
 }
+
+// respondRequiresAction handles a PaymentIntent that needs 3DS auth
+// The order stays pending. the webhook flips it to paid once the customer
+// completes the bank-hosted challenge, the tui polls /api/v1/orders/{id}/status
+func (h *CartHandler) respondRequiresAction(w http.ResponseWriter, order *models.Order, pi *stripe.PaymentIntent) {
+	db := database.GetDB()
+
+	// PaymentIntents returned inside a *stripe.Error are partial — next_action
+	// is often nil. Re-fetch from Stripe to get the canonical PI with the 3DS
+	// challenge URL populated.
+	if pi.NextAction == nil || pi.NextAction.RedirectToURL == nil || pi.NextAction.RedirectToURL.URL == "" {
+		fresh, ferr := paymentintent.Get(pi.ID, nil)
+		if ferr == nil && fresh != nil {
+			pi = fresh
+		}
+	}
+
+	if pi.NextAction == nil || pi.NextAction.RedirectToURL == nil || pi.NextAction.RedirectToURL.URL == "" {
+		middleware.RecordCartConversion("sca_missing_next_action")
+		db.Model(order).Update("status", models.OrderStatusFailed)
+		audit.OrderFailed(order.UserID, order.ID, order.Total, "stripe returned requires_action without redirect url")
+		utils.RespondError(w, http.StatusBadGateway, "PAYMENT_FAILED", "stripe did not return a 3ds url", nil)
+		return
+	}
+
+	// persist the paymentIntent id before responding so the reconciliation jon
+	// and webhook can match the eventual succeeded/failed event to this order
+	// even if the customer drops off mid-auth
+	if err := db.Model(order).Update("stripe_payment_id", pi.ID).Error; err != nil {
+		utils.RespondError(w, http.StatusInternalServerError, "DATABASE_ERROR", "failed to save payment id", nil)
+		return
+	}
+
+	token, err := storeRedirect(pi.NextAction.RedirectToURL.URL)
+	if err != nil {
+		utils.RespondError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to allocate redirect token", nil)
+		return
+	}
+
+	middleware.RecordCartConversion("requires_action")
+	audit.OrderRequiresAction(order.UserID, order.ID, pi.ID)
+
+	utils.RespondSuccess(w, http.StatusAccepted, map[string]any{
+		"order_id":          order.ID,
+		"payment_intent_id": pi.ID,
+		"status":            "requires_action",
+		"redirect_token":    token,
+		"redirect_url":      fmt.Sprintf("%s/pay/%s", h.appURL, token),
+	})
+}
+
+func mapStripeCardErrCode(code stripe.ErrorCode) string {
+	switch code {
+	case stripe.ErrorCodeAuthenticationRequired:
+		return "AUTHENTICATION_REQUIRED"
+	case "authentication_not_supported":
+		return "AUTHENTICATION_NOT_SUPPORTED"
+	case "card_declined", "":
+		return "CARD_DECLINED"
+	case "expired_card":
+		return "CARD_EXPIRED"
+	case "incorrect_cvc":
+		return "CARD_CVC_FAILED"
+	case "insufficient_funds":
+		return "CARD_INSUFFICIENT_FUNDS"
+	case "processing_error":
+		return "CARD_PROCESSING_ERROR"
+	}
+	return "CARD_DECLINED"
+}
+
+//nolint:unused // wired into Convert cart later
+func appURLForHandler(r *http.Request) string {
+	scheme := "http"
+	if r.TLS != nil || r.Header.Get("X-Forwarded-Proto") == "https" {
+		scheme = "https"
+	}
+	host := r.Host
+	if fh := r.Header.Get("X-Forwarded-Host"); fh != "" {
+		host = fh
+	}
+	return fmt.Sprintf("%s://%s", scheme, host)
+}

api/handlers/cart_test.go

@@ -65,7 +65,7 @@ func TestGetCartEmpty(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	req := authRequest("GET", "/api/v1/cart", nil, user.ID)
 	w := httptest.NewRecorder()
@@ -104,7 +104,7 @@ func TestSetItemAndGetCart(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Add item (CoffeeID=1, Quantity=2)
 	body, _ := json.Marshal(map[string]interface{}{
@@ -160,7 +160,7 @@ func TestSetItemUpdateQuantity(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Add item
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 1, "quantity": 2})
@@ -205,7 +205,7 @@ func TestSetItemRemove(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Add item
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 1, "quantity": 3})
@@ -244,7 +244,7 @@ func TestSetItemInvalidProduct(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 999, "quantity": 1})
 	req := authRequest("PUT", "/api/v1/cart/item", body, user.ID)
@@ -261,7 +261,7 @@ func TestSetItemMissingCoffeeID(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	body, _ := json.Marshal(map[string]interface{}{"quantity": 1})
 	req := authRequest("PUT", "/api/v1/cart/item", body, user.ID)
@@ -278,7 +278,7 @@ func TestClearCart(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Add two items
 	for _, coffeeID := range []uint{1, 2} {
@@ -334,7 +334,7 @@ func TestSetAddress(t *testing.T) {
 	}
 	db.Create(&addr)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	body, _ := json.Marshal(map[string]interface{}{"address_id": addr.ID})
 	req := authRequest("PUT", "/api/v1/cart/address", body, user.ID)
@@ -388,7 +388,7 @@ func TestSetAddressWrongUser(t *testing.T) {
 	}
 	db.Create(&addr)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	body, _ := json.Marshal(map[string]interface{}{"address_id": addr.ID})
 	req := authRequest("PUT", "/api/v1/cart/address", body, user.ID)
@@ -416,7 +416,7 @@ func TestSetCard(t *testing.T) {
 	}
 	db.Create(&card)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	body, _ := json.Marshal(map[string]interface{}{"card_id": card.ID})
 	req := authRequest("PUT", "/api/v1/cart/card", body, user.ID)
@@ -468,7 +468,7 @@ func TestSetCardWrongUser(t *testing.T) {
 	}
 	db.Create(&card)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	body, _ := json.Marshal(map[string]interface{}{"card_id": card.ID})
 	req := authRequest("PUT", "/api/v1/cart/card", body, user.ID)
@@ -485,7 +485,7 @@ func TestConvertCartMissingAddress(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Add item but no address or card
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 1, "quantity": 1})
@@ -508,7 +508,7 @@ func TestConvertCartMissingCard(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 	db := database.GetDB()
 
 	// Add item and address
@@ -539,7 +539,7 @@ func TestConvertCartEmpty(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Empty cart convert
 	req := authRequest("POST", "/api/v1/cart/convert", nil, user.ID)
@@ -556,7 +556,7 @@ func TestMultipleItems(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 
 	// Add three different items
 	for i := uint(1); i <= 3; i++ {
@@ -605,7 +605,7 @@ func TestCartIsolation(t *testing.T) {
 	}
 	db.Create(&user2)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "")
 	r := chi.NewRouter()
 	r.Put("/cart/item", handler.SetItem)
 	r.Get("/cart", handler.GetCart)

api/handlers/orders.go

@@ -145,6 +145,29 @@ func (h *OrderHandler) GetOrders(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+func (h *OrderHandler) GetOrderStatus(w http.ResponseWriter, r *http.Request) {
+	db := database.GetDB().WithContext(r.Context())
+	userID := middleware.UserIDFromContext(r.Context())
+
+	idStr := chi.URLParam(r, "id")
+	id, err := strconv.ParseUint(idStr, 10, 32)
+	if err != nil {
+		utils.RespondError(w, http.StatusBadRequest, "INVALID_ID", "invalid order id", nil)
+		return
+	}
+
+	var order models.Order
+	if err := db.Where("id = ? AND user_id = ?", id, userID).First(&order).Error; err != nil {
+		utils.RespondError(w, http.StatusNotFound, "ORDER_NOT_FOUND", "order not found", nil)
+		return
+	}
+
+	utils.RespondSuccess(w, http.StatusOK, map[string]any{
+		"id":     order.ID,
+		"status": string(order.Status),
+	})
+}
+
 // RefundOrder issues a full refund for an order via Stripe and marks it as
 // refunded. Only orders in paid or shipped status can be refunded.
 func (h *OrderHandler) RefundOrder(w http.ResponseWriter, r *http.Request) {

api/routes/routes.go

@@ -46,7 +46,7 @@ func SetupRoutes(
 	healthHandler := handlers.NewHealthHandler(version)
 	productHandler := handlers.NewProductHandler()
 	authHandler := handlers.NewAuthHandler(jwtManager, authFingerprintKey)
-	cartHandler := handlers.NewCartHandler(stripeSecretKey)
+	cartHandler := handlers.NewCartHandler(stripeSecretKey, appURL)
 	cardHandler := handlers.NewCardHandler(stripeSecretKey, appURL)
 	orderHandler := handlers.NewOrderHandler(stripeSecretKey, bringAPIUID, bringAPIKey, bringCustomerNumber)
 	addressHandler := handlers.NewAddressHandler(shippoAPIKey, bringAPIUID, bringAPIKey)
@@ -61,6 +61,10 @@ func SetupRoutes(
 		w.Header().Set("Content-Type", "text/html")
 		_, _ = w.Write([]byte(`<!DOCTYPE html><html><body style="font-family:monospace;text-align:center;padding:4rem"><h2>Card added.</h2><p>You can close this tab.</p></body></html>`))
 	})
+	r.Get("/post-3ds", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		_, _ = w.Write([]byte(`<!DOCTYPE html><html><body style="font-family:monospace;text-align:center;padding:4rem"><h2>Authentication complete.</h2><p>Return to your terminal.</p></body></html>`))
+	})
 	r.Handle("/metrics", middleware.MetricsHandler())
 
 	r.Route("/api/v1", func(r chi.Router) {
@@ -126,6 +130,7 @@ func SetupRoutes(
 
 			// Orders
 			r.Get("/orders", orderHandler.GetOrders)
+			r.Get("/orders/{id}/status", orderHandler.GetOrderStatus)
 			r.Post("/orders/{id}/refund-request", orderHandler.CreateRefundRequest)
 			r.Post("/orders/{id}/refund", orderHandler.RefundOrder)
 

pkg/api/client.go

@@ -56,7 +56,6 @@ type TokenResponse struct {
 }
 
 func (c *Client) GetOrCreateToken(fingerprint, pubKeyStr, clientSecret string) (string, models.PublicUser, error) {
-
 	url := fmt.Sprintf("%s/api/v1/auth/token", c.BaseURL)
 
 	reqBody := TokenRequest{
@@ -497,6 +496,40 @@ func (c *Client) ConvertCart() (*models.Order, error) {
 	return &convertResp.Data.Order, nil
 }
 
+type OrderStatusResponse struct {
+	Success bool `json:"success"`
+	Data    struct {
+		ID     uint   `json:"id"`
+		Status string `json:"status"`
+	} `json:"data"`
+	Error *APIError `json:"error,omitempty"`
+}
+
+func (c *Client) GetOrderStatus(id uint) (string, error) {
+	url := fmt.Sprintf("%s/api/v1/orders/%d/status", c.BaseURL, id)
+	req, err := http.NewRequest("GET", url, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	resp, err := c.doRequest(req)
+	if err != nil {
+		return "", fmt.Errorf("failed to fetch order status: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var sResp OrderStatusResponse
+	if err := json.NewDecoder(resp.Body).Decode(&sResp); err != nil {
+		return "", fmt.Errorf("failed to decode order status response: %w", err)
+	}
+	if !sResp.Success {
+		if sResp.Error != nil {
+			return "", fmt.Errorf("%s: %s", sResp.Error.Code, sResp.Error.Message)
+		}
+		return "", fmt.Errorf("failed to fetch order status")
+	}
+	return sResp.Data.Status, nil
+}
+
 // GetCards fetches all saved cards for the user.
 func (c *Client) GetCards() ([]models.Card, error) {
 	url := fmt.Sprintf("%s/api/v1/cards", c.BaseURL)

pkg/audit/audit.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+
 	"terminalShop/pkg/models"
 
 	"gorm.io/gorm"
@@ -21,6 +22,7 @@ const (
 	eventOrderPaid              eventType = "order_paid"
 	eventOrderShipped           eventType = "order_shipped"
 	eventOrderFailed            eventType = "order_failed"
+	eventOrderRequiresAction    eventType = "order_requires_action"
 	eventOrderRefunded          eventType = "order_refunded"
 	eventPaymentCritical        eventType = "payment_critical"
 	eventLabelPurchased         eventType = "label_purchased"
@@ -298,3 +300,15 @@ func attrsToMap(a []any) map[string]any {
 	}
 	return m
 }
+
+//nolint:unused // called from ConvertCart in the next update
+func OrderRequiresAction(userID, orderID uint, paymentIntentID string) {
+	e := event{
+		Event:    eventOrderRequiresAction,
+		UserID:   userID,
+		OrderID:  orderID,
+		StripeID: paymentIntentID,
+	}
+	slog.Info("audit", e.attrs()...)
+	persist(orderID, eventOrderRequiresAction, e)
+}

pkg/tui/confirmation.go

@@ -3,6 +3,7 @@ package tui
 import (
 	"fmt"
 	"strings"
+
 	"terminalShop/pkg/models"
 
 	"charm.land/bubbles/v2/viewport"
@@ -192,7 +193,7 @@ func (m Model) ReviewUpdate(msg tea.Msg) (Model, tea.Cmd) {
 		m.CheckingOut = false
 		if msg.Err != nil {
 			m = m.SwitchPage(paymentPage)
-			m.error = &VisibleError{message: fmt.Sprintf("checkout failed: %v", msg.Err)}
+			m.error = &VisibleError{message: friendlyCheckoutError(msg.Err)}
 			m.review.cardJustAdded = false
 			m.payment.view = 0
 			m.payment.form = nil
@@ -234,3 +235,24 @@ func (m Model) ReviewUpdate(msg tea.Msg) (Model, tea.Cmd) {
 	}
 	return m, nil
 }
+
+func friendlyCheckoutError(raw error) string {
+	s := raw.Error()
+	switch {
+	case strings.Contains(s, "AUTHENTICATION_REQUIRED"):
+		return "your bank wants to verify this charge, authentication step coming soon."
+	case strings.Contains(s, "AUTHENTICATION_NOT_SUPPORTED"):
+		return "this card doesn't support online authentication. Try another card"
+	case strings.Contains(s, "CARD_EXPIRED"):
+		return "card expired. Add a new card and try again"
+	case strings.Contains(s, "CARD_CVC_FAILED"):
+		return "card cvc incorrect. Check the back of the card and try again"
+	case strings.Contains(s, "CARD_INSUFFICIENT_FUNDS"):
+		return "insufficient funds on this card"
+	case strings.Contains(s, "CARD_PROCESSING_ERROR"):
+		return "card processing error. Try again in a moment"
+	case strings.Contains(s, "CARD_DECLINED"):
+		return "card declined"
+	}
+	return "checkout failed, try again."
+}

pkg/tui/views.go

@@ -82,6 +82,10 @@ func (m Model) renderString() string {
 		content = loadingStyle.Render("Loading products from API...")
 	} else if m.error != nil {
 		errorStyle := m.theme.PanelError().Padding(0, 1).MarginBottom(1)
+		// soft-wrap long messages instead of clipping.
+		if m.widthContent > 4 {
+			errorStyle = errorStyle.Width(m.widthContent - 4)
+		}
 		errorBanner := errorStyle.Render(m.error.message)
 		content = errorBanner + "\n" + m.buildPageContent(availableContentHeight)
 	} else if m.notice != nil {