open-standards/openpay/docs/30-3ds-resume-progress.md

# Phase 30 — 3DS / SCA resume primitive

**Status**: Draft v0.30
**Date**: 2026-05-22

## Why

Until Phase 30, when a card auth returned
`AttemptOutcome::RequiresAction { url }`, the flow stopped. The HTTP
intent endpoint returned the URL and the `psp_payment_id`, but
there was no way to *resume* the intent once the customer
completed the 3DS challenge. That made the card rail
half-functional for any SCA-regulated region: Europe (PSD2),
India, parts of LATAM.

Phase 30 closes that loop. It adds:

1. A `CardAcquirer::confirm_after_challenge` method (default
   `UnsupportedMethod` so old gateways stay correct).
2. A `RailAdapter::resume` method (default soft-failure so
   adapters without a challenge flow stay correct).
3. An `Orchestrator::resume(intent, rail, driver, psp_payment_id)`
   entry point that reclassifies the resumed outcome and updates
   the idempotency cache.
4. An HTTP `POST /v1/intents/resume` endpoint.
5. `DeterministicCardAcquirer` support for challenge-then-confirm
   so operators can integration-test the flow without a live PSP.

Last phase of the sequenced 28 → 29 → 30 trio. Webhooks, FX,
3DS — the three highest-impact operator-facing gaps from the
post-Phase-27 stack — all closed.

## What shipped

| # | Item | Where |
|--:|---|---|
| 1 | `CardAcquirer::confirm_after_challenge(psp_payment_id, idempotency_key)` trait method with default `Err(UnsupportedMethod)` | `op-rails-card/src/acquirer.rs` |
| 2 | `RailAdapter::resume(intent, psp_payment_id) -> AdapterResult` with default `SoftFailure { code: "resume_not_supported" }` | `op-orchestrator/src/engine.rs` |
| 3 | `CardAdapter::resume` override — calls `confirm_after_challenge` and reuses `classify_decision` to map back to `AttemptOutcome` | `op-orchestrator/src/adapters/card.rs` |
| 4 | `Orchestrator::resume(intent, rail, driver, psp_payment_id) -> Result<OrchestrationOutcome>` — looks up the adapter, runs resume, commits the resolved outcome to the idempotency cache | `op-orchestrator/src/engine.rs` |
| 5 | `DeterministicCardAcquirer::confirm_after_challenge` — synthetic post-challenge settle for integration tests | `op-driver-sdk/src/card.rs` |
| 6 | `POST /v1/intents/resume` HTTP endpoint — takes the same intent body + `rail` + `driver` + `psp_payment_id` | `op-server/src/handlers/intent.rs`, `routes.rs` |
| 7 | Tracing span `orchestrator.resume` with `idempotency_key`, `driver`, `rail` fields | `op-orchestrator/src/engine.rs` |
| 8 | Emitted webhook events: `intent.resumed.approved`, `intent.resumed.declined`, `intent.resumed.requires_action` | `op-server/src/handlers/intent.rs` |
| 9 | Integration tests: orchestrator-level (challenge then resume → approved; resume against unknown driver → error) + HTTP-level (`POST /v1/intents` → `POST /v1/intents/resume`) | `op-driver-sdk/tests/`, `op-server/tests/` |

Workspace at the end of Phase 30:

| Check | Result |
|---|---|
| `cargo build --workspace --all-targets` | **0 errors, 0 warnings** |
| `cargo test --workspace` | **1050 passing, 0 failing** (+3 vs Phase 29) |
| `cargo clippy --workspace --all-targets` | **0 warnings** |

## Flow

```text
   1. POST /v1/intents
        intent → orchestrator.run() → adapter.attempt()
                                       → AuthStatus::RequiresCustomerAction
        ─► outcome.terminal_status = RequiresCustomerAction
        ─► response carries (psp_payment_id, redirect_url)

   2. Customer completes the 3DS challenge out-of-band.
      PSP knows. OpenPay doesn't (yet).

   3. POST /v1/intents/resume
        body: original intent + rail + driver + psp_payment_id
        → orchestrator.resume()
            → adapter.resume(intent, psp_payment_id)
                → acquirer.confirm_after_challenge(psp_payment_id, idem_key)
                → AuthStatus::Settled (or whatever the PSP reports)
            → classify_decision → AttemptOutcome::Success
        ─► outcome.terminal_status = Approved
        ─► idempotency cache committed
```

The resume primitive is **stateless on the server side**: the
caller hands back the same intent body. We chose this over
server-side intent persistence because:

- The orchestrator already has the idempotency cache; that's the
  source-of-truth for "this intent was previously run."
- Persisting the intent body would duplicate the idempotency
  store with a new "pending intents" table that has the same
  contents.
- Operators with stronger "we don't trust the client to remember"
  requirements layer in their own pending-intents store on top —
  small wedge, opinionated, kept out of the reference path.

## Backward compatibility

Both new trait methods have default implementations:

- `CardAcquirer::confirm_after_challenge` defaults to
  `Err(UnsupportedMethod)`. Existing PSP drivers compile
  unchanged; calling resume against them surfaces a clean error.
- `RailAdapter::resume` defaults to `SoftFailure { code:
  "resume_not_supported" }`. A2A and Crypto adapters that don't
  have a challenge concept inherit this and the resume call
  returns a soft-failure decline rather than panicking.

No existing tests broke. The 1047 tests from Phase 29 still
pass; the 3 new tests are pure additions.

## Idempotency semantics

`Orchestrator::resume` calls `self.idempotency.commit(&intent_key,
&outcome)` after a successful resume. That means:

- A duplicate `POST /v1/intents` with the same idempotency key
  (after resume completed) returns the cached **resumed**
  outcome, not the original `RequiresCustomerAction`.
- A retry of `POST /v1/intents/resume` with the same intent +
  psp_payment_id calls the PSP again. PSPs that honor the
  idempotency-key header (Stripe, Adyen, Hyperswitch) return the
  cached decision; PSPs that don't get a new call but should
  return the same status since the challenge is one-shot.

The idempotency cache is committed only after a successful
classify; if the resume itself transport-fails (`SoftFailure`),
the cache is updated with the soft-failure outcome — re-running
the same intent body will get the cached soft-fail rather than
re-attempting authorization. Operators with stricter "always
re-attempt on soft fail" requirements call `release()` on the
idempotency store before re-running.

## HTTP surface

```
POST /v1/intents/resume
{
  "idempotency_key": "intent-3ds-1",
  "amount_minor": 1500,
  "currency": "USD",
  "method": { "type": "vault", "token": "tok_v7_3ds" },
  "rail": "card",
  "driver": "hyperswitch",
  "psp_payment_id": "psp_42abcd..."
}
```

Response shape is identical to `POST /v1/intents` — same
`IntentResponse` JSON. Operators can write a single handler for
both endpoints on the consumer side.

Emitted events use distinct types (`intent.resumed.approved`
etc.) so webhook consumers can distinguish first-attempt vs
post-challenge approval if they care.

## Honest concerns (carry-forward)

- **No server-side pending-intent store.** The caller carries
  the intent body across the challenge window. Operators wanting
  server-tracked challenges add a thin `PendingIntent` store on
  top (one table keyed on intent idempotency key, expires after
  72 hours).
- **A2A and Crypto adapters have no resume.** Their challenge
  models are different — A2A "challenges" are typically bank-app
  approvals that complete asynchronously via webhook; crypto
  flows don't have a customer-side challenge in the same sense.
  The default `SoftFailure { code: "resume_not_supported" }`
  surfaces the situation cleanly when operators try.
- **No challenge-window enforcement.** A `psp_payment_id` that's
  been pending for six weeks will still be accepted by the
  endpoint; the PSP returns the appropriate "expired" error and
  we surface it as a `SoftFailure`. Operators with strict
  windows reject at the HTTP layer (a tower middleware that
  checks elapsed time before forwarding).
- **No 3DS-on-retry escalator.** Phase 28's option mentioned a
  per-attempt 3DS preference escalator (force 3DS on the second
  attempt of a soft-declined intent). That's a smaller adjacent
  wedge — the `attempt_number` parameter is already on
  `RailAdapter::attempt`, operators can read it in their adapter
  and escalate. Shipping a built-in policy would push opinion
  onto every operator.
- **No customer-facing UI.** That's frontend. The HTTP endpoints
  support whatever flow the operator builds.

## Test totals

```
op-driver-sdk    +2  (orchestrator resume happy path, unknown driver error)
op-server        +1  (HTTP create → resume end-to-end)
                                                              ----
                                                              +3 net
```

`cargo test --workspace`: **1050 passing, 0 failing.**
`cargo build --workspace --all-targets`: **0 warnings.**
`cargo clippy --workspace --all-targets`: **0 warnings.**

## Status of the project after Phase 30

The 28 → 29 → 30 trio closed the last large operator-facing gaps:

| Capability | Phase |
|---|---|
| Webhook delivery, end-to-end | 28 |
| Multi-currency / FX primitives | 29 |
| 3DS / SCA resume | **30** |

Combined with everything before (Phases 11–27), OpenPay is now a
complete reference payment-acceptance stack with:

- Card + A2A + Crypto rails
- Refunds, disputes, settlement, subscriptions
- Single-file Minigraf persistence
- HTTP API server, driver SDK with conformance harness
- FX conversion, webhook delivery, 3DS resume
- Bi-temporal time-travel, graph-backed audit reports

A vendor can write their own driver, point `op-server` at a
single `.graph` file, wire their HTTP transport + FX feed, and
serve a SaaS-shaped payment stack — no external database, no
queue, no auxiliary service. Margin stays with the vendor.