3cd82ba5be
Every outbound POST /payments and POST /refunds from the Hyperswitch
client now carries an Idempotency-Key HTTP header. Key values are
explicit parameters at every call site — no context-carrier magic,
no auto-generation. An empty key is a loud error from the client
(not silent header omission) so a future new call site that forgets
to supply one fails immediately, not months later under an obscure
replay scenario.
Key choices, both stable across HTTP retries of the same logical
call:
* CreatePayment → order.ID.String() (GORM BeforeCreate populates
order.ID before the PSP call in ConfirmOrder).
* CreateRefund → pendingRefund.ID.String() (populated by the
Phase 1 tx.Create in RefundOrder, available for the Phase 2 PSP
call).
Scope note (reproduced here for the next reader who grep-s the
commit log for "Idempotency-Key"):
Idempotency-Key covers HTTP-transport retry (TLS reconnect,
proxy retry, DNS flap) within a single CreatePayment /
CreateRefund invocation. It does NOT cover application-level
replay (user double-click, form double-submit, retry after crash
before DB write). That class of bug requires state-machine
preconditions on VEZA side — already addressed by the order
state machine + the handler-level guards on POST
/api/v1/payments (for payments) and the partial UNIQUE on
`refunds.hyperswitch_refund_id` landed in v1.0.6.1 (for refunds).
Hyperswitch TTL on Idempotency-Key: typically 24h-7d server-side
(verify against current PSP docs). Beyond TTL, a retry with the
same key is treated as a new request. Not a concern at current
volumes; document if retry logic ever extends beyond 1 hour.
Explicitly out of scope: item D does NOT add application-level
retry logic. The current "try once, fail loudly" behavior on PSP
errors is preserved. Adding retries is a separate design exercise
(backoff, max attempts, circuit breaker) not part of this commit.
Interfaces changed:
* hyperswitch.Client.CreatePayment(ctx, idempotencyKey, ...)
* hyperswitch.Client.CreatePaymentSimple(...) convenience wrapper
* hyperswitch.Client.CreateRefund(ctx, idempotencyKey, ...)
* hyperswitch.Provider.CreatePayment threads through
* hyperswitch.Provider.CreateRefund threads through
* marketplace.PaymentProvider interface — first param after ctx
* marketplace.refundProvider interface — first param after ctx
Removed:
* hyperswitch.Provider.Refund (zero callers, superseded by
CreateRefund which returns (refund_id, status, err) and is the
only method marketplace's refundProvider cares about).
Tests:
* Two new httptest.Server-backed tests (client_test.go) pin the
Idempotency-Key header value for CreatePayment and CreateRefund.
* Two new empty-key tests confirm the client errors rather than
silently sending no header.
* TestRefundOrder_OpensPendingRefund gains an assertion that
f.provider.lastIdempotencyKey == refund.ID.String() — if a
future refactor threads the key from somewhere else (paymentID,
uuid.New() per call, etc.) the test fails loudly.
* Four pre-existing test mocks updated for the new signature
(mockRefundPaymentProvider in marketplace, mockPaymentProvider
in tests/integration and tests/contract, mockRefundPayment
Provider in tests/integration/refund_flow).
Subscription's CreateSubscriptionPayment interface declares its own
shape and has no live Hyperswitch-backed implementation today —
v1.0.6.2 noted this as the payment-gate bypass surface, v1.0.7
item G will ship the real provider. When that lands, item G's
implementation threads the idempotency key through in the same
pattern (documented in v107-plan.md item G acceptance).
CHANGELOG v1.0.7-rc1 entry updated with the full item D scope note
and the "out of scope: retries" caveat.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .. | ||
| adr | ||
| archive | ||
| audit-2026-04 | ||
| audits | ||
| runbooks | ||
| API_REFERENCE.md | ||
| API_VERSIONING_POLICY.md | ||
| ASVS_CHECKLIST_v0.12.6.md | ||
| BOOT_MODE_STATUS.md | ||
| BUDGETS.md | ||
| BUG_BASH_V0981.md | ||
| CHAT_FEATURE_PARITY.md | ||
| DB_MIGRATIONS_AUDIT_V1.md | ||
| DB_MIGRATIONS_ORIGIN_DIFF.md | ||
| DB_MIGRATIONS_STRATEGY_FINAL.md | ||
| DB_MIGRATIONS_V1_VALIDATION.md | ||
| DB_TRANSACTION_PLAN.md | ||
| DISCOVERY_ALGORITHM.md | ||
| ENV_CONFIG.md | ||
| ENV_VARIABLES.md | ||
| ENVIRONMENT_REAL_SETUP.md | ||
| FEATURE_STATUS.md | ||
| FRONTEND_AUDIT_VISUAL.md | ||
| FRONTEND_DEEP_DIVE_AUDIT.md | ||
| FRONTEND_ROADMAP_SPOTIFY_DISCORD_QUALITY.md | ||
| FRONTEND_SETUP.md | ||
| FRUGALITY.md | ||
| GLOBAL_PROJECT_STATE_2026.md | ||
| GO_NO_GO_CHECKLIST_v1.0.0.md | ||
| MIGRATION_CONSOLIDATION.md | ||
| MIGRATIONS.md | ||
| MINIMAL_WEB.md | ||
| MONITORING_SETUP.md | ||
| MONOREPO_ORCHESTRATION.md | ||
| ONBOARDING.md | ||
| PAYMENTS_SETUP.md | ||
| PAYOUT_MANUAL.md | ||
| PENTEST_REPORT_VEZA_v0.12.6.md | ||
| PERFORMANCE_BASELINE.md | ||
| PR_READY_CHECKLIST.md | ||
| PRIVACY_POLICY.md | ||
| PRODUCTION_DEPLOYMENT.md | ||
| PROJECT_STATE.md | ||
| PWA_OFFLINE_VERIFICATION.md | ||
| README.md | ||
| REMEDIATION_MATRIX_v0.12.6.md | ||
| REMOTE_DEV_R720.md | ||
| REPORT_FRONTEND_PHASE1.md | ||
| RGPD_CCPA_VERIFICATION.md | ||
| ROADMAP_V09XX_TO_V1.md | ||
| SCOPE_CONTROL.md | ||
| SECRET_ROTATION.md | ||
| SECRETS_AUDIT.md | ||
| SECRETS_VERIFICATION.md | ||
| SECURITY_SCAN_RC1.md | ||
| STAGING_DEPLOYMENT.md | ||
| STORYBOOK_CONTRACT.md | ||
| STRATEGIE_COUVERTURE_ET_TMT_2025_02.md | ||
| TEST_PROTOCOL_BOOT.md | ||
| TODO_TRIAGE_VEZA.md | ||
| TRANSACTION_TESTS_PHASE3.md | ||
| TRIAGE_REPORT.md | ||
| UUID_DB_CARTOGRAPHY.md | ||
| UUID_DB_MIGRATION_PLAN.md | ||
| V1_LIMITATIONS.md | ||
| V1_MVP_SCOPE.md | ||
| V1_SIGNOFF.md | ||
| VEZA_PROJECT_DOCUMENTATION.md | ||
| VISUAL_TESTING_STRATEGY.md | ||
Documentation Veza
Index de la documentation principale du monorepo.
Démarrage
- Onboarding — Setup, architecture, conventions, troubleshooting
- Frontend Setup — Configuration du frontend React
- Environment Config — Variables d'environnement et connexion Docker
Architecture & Déploiement
- Production Deployment — Déploiement en production
- Monorepo Orchestration — Organisation du monorepo
- Monitoring Setup — Configuration du monitoring
Développement
- Remote Dev R720 — Développement sur serveur R720 via Cursor Remote-SSH
- Scope v0.201 — Périmètre de la version courante (référence prioritaire)
- État du projet — Où en sommes-nous, prochaines étapes
- Contrôle du scope — Processus anti-scope-creep
- Feature Status — Statut des fonctionnalités
- Storybook Contract — Conventions Storybook
- Visual Testing Strategy — Stratégie des tests visuels
- PR Ready Checklist — Checklist avant merge
Base de données & Migrations
- DB Migrations Strategy — Stratégie des migrations
- UUID Migration Plan — Plan de migration UUID
Sécurité & Opérations
- Secrets Verification — Vérification des secrets
- Secret Rotation — Rotation des secrets
- Payments Setup — Configuration des paiements
Remédiation & Progression
- Remediation Progress — Suivi de la remédiation
- Global Project State — État global du projet
Archives
Les audits et rapports historiques sont dans docs/archive/.
Documentation par composant
- Frontend :
apps/web/docs/(FULL_LAYOUT_PAGE, DESIGN_TOKENS, etc.) - Backend :
veza-backend-api/docs/