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

[vibenedict]

Summary

Relates to #377.

The real PayPal order/capture flow already exists in PaymentService (created in prior work — d718702, a1045c7), so this PR focuses on the one acceptance-criteria gap that was still weak: "Handle declined/failed states explicitly."

Previously the capture path treated every non-COMPLETED status as one generic error:

if (status === 'COMPLETED' && captureId) { /* success */ }
else { error: `Payment capture failed with status: ${status}` }

So a genuinely declined card, a transient failure, and a payment held for review (PENDING) were indistinguishable to UI/API callers.

Changes

client/lib/payment-service.ts — branch on the PayPal capture status explicitly:

Status	Result
COMPLETED	success (now also guards against a missing capture ID)
DECLINED / FAILED	explicit permanent-failure error, including PayPal's status_details.reason when present
PENDING	surfaced with requiresAction so it's persisted as pending and finalized by the webhook, instead of being reported as a hard success
unknown	generic fallback error

client/lib/paypal-service.ts — add status_details.reason to PayPalCaptureResponse so the decline reason can be surfaced.

Testing

vitest run lib/__tests__/payment-service.test.ts:

• Added 3 tests (DECLINED, FAILED, PENDING) — all pass.
• Verified no regressions: the pre-existing failures in the payment test files (Paystack feature-flag gating + a stale DB-log-prefix assertion) fail identically with and without this change — baseline 11 passed / 5 failed → 14 passed / 5 failed after adding the 3 new passing tests. Those pre-existing failures are unrelated to PayPal and out of scope here.

Note for maintainers: local npm install fails on macOS/arm64 because client/package.json pins the linux-only @rolldown/binding-linux-x64-gnu as a hard dependency and the lockfile omits the darwin binding — worth a separate fix so the vitest suite is runnable off-CI.

🤖 Generated with Claude Code