feat(payments): explicit PayPal capture state handling (#377)

The PayPal capture path collapsed every non-COMPLETED status into a
single generic error, so callers could not tell a declined card from a
transient failure or a payment held for review.

Handle each documented PayPal capture status explicitly:
- COMPLETED -> success (guards against a missing capture id)
- DECLINED / FAILED -> explicit permanent-failure error, including
  PayPal's status_details.reason when present
- PENDING -> surfaced as requiresAction so it is persisted as pending
  and finalized by the webhook rather than reported as a hard success
- unknown -> generic fallback error

Adds status_details.reason to PayPalCaptureResponse and unit tests for
the DECLINED, FAILED, and PENDING branches.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: vibenedict

client/lib/__tests__/payment-service.test.ts

@@ -149,6 +149,89 @@ describe("PaymentService", () => {
       expect(result.requiresAction).toBeUndefined()
     })
 
+    it("should surface a DECLINED capture as an explicit failure", async () => {
+      const { getPayPalService } = await import("../paypal-service")
+      vi.mocked(getPayPalService).mockReturnValue({
+        captureOrder: vi.fn().mockResolvedValue({
+          id: "ORDER_ABC",
+          status: "COMPLETED",
+          purchase_units: [{
+            payments: {
+              captures: [{
+                id: "CAPTURE_DECLINED",
+                status: "DECLINED",
+                status_details: { reason: "INSTRUMENT_DECLINED" },
+              }],
+            },
+          }],
+        }),
+        createOrder: vi.fn(),
+        refundCapture: vi.fn(),
+        getOrder: vi.fn(),
+      } as any)
+
+      const service = new PaymentService({ provider: "paypal" })
+      const result = await service.processPayment(0, "usd", "order_ORDER_ABC")
+
+      expect(result.success).toBe(false)
+      expect(result.error).toContain("declined")
+      expect(result.error).toContain("INSTRUMENT_DECLINED")
+      // Falls back to the capture ID so callers can reconcile the attempt.
+      expect(result.transactionId).toBe("CAPTURE_DECLINED")
+    })
+
+    it("should surface a FAILED capture as an explicit failure", async () => {
+      const { getPayPalService } = await import("../paypal-service")
+      vi.mocked(getPayPalService).mockReturnValue({
+        captureOrder: vi.fn().mockResolvedValue({
+          id: "ORDER_ABC",
+          status: "COMPLETED",
+          purchase_units: [{
+            payments: { captures: [{ id: "CAPTURE_FAILED", status: "FAILED" }] },
+          }],
+        }),
+        createOrder: vi.fn(),
+        refundCapture: vi.fn(),
+        getOrder: vi.fn(),
+      } as any)
+
+      const service = new PaymentService({ provider: "paypal" })
+      const result = await service.processPayment(0, "usd", "order_ORDER_ABC")
+
+      expect(result.success).toBe(false)
+      expect(result.error).toContain("failed")
+    })
+
+    it("should treat a PENDING capture as pending (requiresAction), not success", async () => {
+      const { getPayPalService } = await import("../paypal-service")
+      vi.mocked(getPayPalService).mockReturnValue({
+        captureOrder: vi.fn().mockResolvedValue({
+          id: "ORDER_ABC",
+          status: "COMPLETED",
+          purchase_units: [{
+            payments: {
+              captures: [{
+                id: "CAPTURE_PENDING",
+                status: "PENDING",
+                status_details: { reason: "PENDING_REVIEW" },
+              }],
+            },
+          }],
+        }),
+        createOrder: vi.fn(),
+        refundCapture: vi.fn(),
+        getOrder: vi.fn(),
+      } as any)
+
+      const service = new PaymentService({ provider: "paypal" })
+      const result = await service.processPayment(0, "usd", "order_ORDER_ABC")
+
+      expect(result.success).toBe(false)
+      expect(result.requiresAction).toBe(true)
+      expect(result.error).toContain("pending")
+      expect(result.transactionId).toBe("CAPTURE_PENDING")
+    })
+
     it("should return error when PayPal is not configured", async () => {
       const { getPayPalService } = await import("../paypal-service")
       vi.mocked(getPayPalService).mockReturnValue(null)

client/lib/payment-service.ts

@@ -156,20 +156,53 @@ export class PaymentService {
         const orderId = paymentMethodId.replace('order_', '')
         const capture = await paypalService.captureOrder(orderId)
 
-        const captureId = capture.purchase_units[0]?.payments?.captures[0]?.id
-        const status = capture.purchase_units[0]?.payments?.captures[0]?.status
-
-        if (status === 'COMPLETED' && captureId) {
-          return {
-            success: true,
-            transactionId: captureId,
-          }
-        } else {
-          return {
-            success: false,
-            transactionId: orderId,
-            error: `Payment capture failed with status: ${status}`,
-          }
+        const captureDetails = capture.purchase_units[0]?.payments?.captures[0]
+        const captureId = captureDetails?.id
+        const status = captureDetails?.status
+        const reason = captureDetails?.status_details?.reason
+
+        // Handle every documented PayPal capture status explicitly so callers
+        // can distinguish a completed payment from a declined, failed, or
+        // pending-review one rather than collapsing them into one error.
+        // @see https://developer.paypal.com/docs/api/orders/v2/#definition-capture_status
+        switch (status) {
+          case 'COMPLETED':
+            if (!captureId) {
+              return {
+                success: false,
+                transactionId: orderId,
+                error: 'PayPal reported a completed capture but returned no capture ID',
+              }
+            }
+            return {
+              success: true,
+              transactionId: captureId,
+            }
+
+          case 'PENDING':
+            // Authorized but held for review (e.g. risk/AVS). Not yet a success —
+            // surface it and persist as pending so the webhook can finalize it.
+            return {
+              success: false,
+              transactionId: captureId || orderId,
+              requiresAction: true,
+              error: `PayPal capture is pending review${reason ? `: ${reason}` : ''}`,
+            }
+
+          case 'DECLINED':
+          case 'FAILED':
+            return {
+              success: false,
+              transactionId: captureId || orderId,
+              error: `PayPal capture ${status.toLowerCase()}${reason ? `: ${reason}` : ''}`,
+            }
+
+          default:
+            return {
+              success: false,
+              transactionId: orderId,
+              error: `Payment capture failed with status: ${status ?? 'UNKNOWN'}`,
+            }
         }
       }
 

client/lib/paypal-service.ts

@@ -51,6 +51,9 @@ export interface PayPalCaptureResponse {
                     currency_code: string
                     value: string
                 }
+                status_details?: {
+                    reason?: string
+                }
             }>
         }
     }>