feat(payments): end-to-end Redsys hosted-redirect for Spain

[telivity-otaip]

Summary

Completes the Redsys (Spanish TPV) hosted-redirect payment path end-to-end.

Status

Approved by Agus after re-review. Head 2bc2c61 matches his independently reviewed tip (faaa96f). EUR sandbox auth/cancel + duplicate signed-callback replay verified; CI green (5/5).

Remediation (on PR head)

1. Atomic verified finalization — Pending checkout creates no deposit; signature-verified success records the deposit and applies configured confirmation once.
2. Server-authoritative return recovery — Full-page hosted return restores from payment state without React memory/storage.
3. URL-length-safe return relay — Compact capability-bound API relay keeps provider return URLs within the 250-character limit while preserving the validated hotel page.
4. Credentials & lifecycle hardening — Fail closed without credentials; correct currency minor units; valid void amounts; signed operation-bound REST results; encrypt/mask per-property secrets; PostgreSQL regressions in CI.

Deploy before payment traffic

Schedule before merge/enablement:

1. Provision the credential-encryption key ring
2. Run the idempotent Redsys credential backfill
3. Apply migrations 0024–0026

Out of scope

Embedded inSite checkout — tracked in #366.

Test plan

• EUR sandbox: pending / success / cancel / fresh-browser recovery / dual signed-callback replay
• Tracked suite: 2,392 tests / 280 files (Agus)
• CI green on 2bc2c61

  

[agustinjch]

I exercised the booking flow against the real Redsys sandbox and am requesting changes for three reproduced correctness failures:

1. Booking return cannot recover the checkout. The generated OK/KO URLs return to origin-root routes, while the booking app uses an in-memory router and loses its state on the full-page round trip. A pathname-only correction is insufficient: the return must bootstrap from a durable, opaque booking/payment reference.
2. A deposit is recorded before authorization. recordDeposit() runs as soon as Redsys returns a hosted-checkout action, while the payment is still pending. Cancelling or abandoning checkout leaves an actionable deposit ledger entry for money that was never authorized.
3. Verified success does not complete auto-confirmation. Booking creation skips confirmation while redirect is pending, but the signed callback updates only the payment. With auto-confirm enabled, the payment becomes authorized while the reservation remains pending.

The browser return must be treated only as navigation. A signature-verified provider result must be the authority for payment state, deposit creation, and reservation confirmation, with an idempotent finalizer for duplicate/out-of-order callback and return delivery.

Non-blocking follow-up: Redsys inSite could provide a smoother embedded checkout, but it is a different REST/3DS integration and does not remove the need for the authoritative lifecycle fix above. I recommend evaluating it separately after this hosted-redirect path is made correct.

[agustinjch]

The requested remediation is implemented and independently reviewed. The four reviewed commits have now been applied directly to this PR, ending at 2bc2c614fc5b34b700a3cb28f8e44958b68cf657.

The superseded non-atomic finalizer was reverted before applying them, so the PR contains one finalization path. The current PR tree is byte-for-byte identical to the independently reviewed tree. The temporary helper PR #367 is therefore obsolete and has been closed.

Commits to bring onto this PR head, in order:

• 5c80e9e — finalize verified redirect booking authorization atomically; pending checkout creates no deposit, verified success records the deposit and applies configured confirmation exactly once.
• c452650 — recover a full-page hosted return from minimal server-authoritative payment state without React memory/storage.
• 577384b — use a compact capability-bound API relay so provider return URLs remain within the 250-character limit while preserving the exact validated hotel page.
• 2bc2c61 — fail closed without credentials; correct currency minor units; send valid void amounts; require signed operation-bound REST results; encrypt/mask per-property secrets; run PostgreSQL regressions in CI; refresh dashboard coverage and test counts.

Real EUR sandbox verification on the first three commits covered authorization and provider cancellation:

• Before provider completion: payment pending, reservation pending, zero deposits.
• Verified success: payment authorized, one EUR 1.00 held deposit, reservation confirmed.
• Provider cancellation: payment failed, zero deposits, reservation remained pending.
• A fresh browser recovered the success screen without prior booking state.
• Two exact replays of the original signed success callback returned 200 and changed no payment, deposit, reservation, or audit rows.

After the final security/lifecycle commit, the tracked-tree run passed 2,392 tests across 280 files, including the PostgreSQL callback and encrypted-credential suites. An independent final review found all blocking findings addressed and no new breakage. Build and typecheck pass; lint has zero errors (existing warnings remain).

Deployment prerequisite: provision the documented credential-encryption key ring and run the idempotent Redsys credential backfill before enabling payment traffic. Migrations 0024–0026 must also be applied before the API/widget rollout.

The embedded inSite checkout remains deliberately separate and non-blocking: #366 tracks merchant activation, multi-tenant domain registration/CSP, iframe choice, idOper lifecycle, embedded EMV 3-D Secure, accessibility, fallback, and reuse of the same authoritative finalizer.

[agustinjch]

Re-reviewed after the four remediation commits were applied directly. The current head tree exactly matches the independently reviewed implementation. Real EUR sandbox authorization/cancellation and duplicate signed-callback replay passed; the tracked suite reports 2,392 passing tests, and all current GitHub checks are green. Ready to merge after the documented deployment prerequisite is scheduled: provision the credential-encryption key ring, run the idempotent Redsys credential backfill, and apply migrations 0024–0026 before payment traffic.

[telivity-otaip]

Gracias hermano.