3DS Integration Guide

Purpose: Entry point and taxonomy for 3DS / 2FA implementation in XAP.

1. Overview

ID: 3ds.overview
Purpose: Explain the two supported integration modes (embedded vs external / pass-through) and convergence on Resume Booking via paymentSessionId.

Key Points:

• Two modes: Embedded (Expedia JS library) vs External / Pass-through (partner or PSP performs full 3DS).
• Both end with Resume Booking using paymentSessionId.
• Choose based on effort, control, UX flexibility, PSP capabilities, internal compliance posture.

2. Decision Matrix

ID: 3ds.decision-matrix

3. Shared Core Flow

ID: 3ds.shared-flow

Steps:

1. Initiate booking (or pre-init) → platform may signal 3DS required.
2. Execute authentication journey (embedded or external).
3. Obtain final auth result (status + cryptogram / metadata).
4. Call Resume Booking with paymentSessionId (+ mapped fields if external).
5. Apply policy: confirm only on accepted statuses (e.g., Y, optionally A).
6. Persist audit fields.

Canonical Audit Fields: directoryResponse, authenticationResponse, threeDSTransactionId, threeDSVersion, eci, cavv (if present), transStatusReason.

4. Embedded (EG JS Library) Implementation

ID: 3ds.embedded.flow
Links: Implementing-3ds-eg-lib.md

Phases: A. Prepare: Include library early; decide always-init vs on-demand fallback.
B. Initialize: Booking (or pre-init) returns paymentSessionId + initConfig; library gathers browser/device data.
C. Frictionless: Library posts data → frictionless success → Resume Booking.
D. Challenge: Use encodedChallengeConfig → render issuer challenge in managed iFrame → await outcome events.
E. Resume: Call Resume Booking (idempotent) → finalize booking.

Failure Handling:

• Script load failure → emit structured fallback; optionally switch to on-demand.
• Challenge timeout / user dismiss → record abandonment.

Data Exposure Rules:

• Do not expose raw challenge HTML outside controlled iFrame.
• Restrict 3DS fields to backend after completion.

5. External / Pass-through Implementation

ID: 3ds.external.flow
Links: Implementing-3ds-pass-through.md, pci-porxy-3ds-fields-mapping.md

Flow:

1. Perform full 3DS (2.1/2.2) via PSP / DS / ACS.
2. Collect resulting auth values.
3. Map to canonical field set.
4. Supply mapped values in Resume (or continuation) call.

Required Mapping: eci, xid or dsTransId, cavv (if present), threeDSVersion, directoryResponse, authenticationResponse, threeDSTransactionId, cardHolderInfo (optional), transStatusReason (when provided).

Validation:

• Version format (2.1.0, 2.2.0).
• eci consistent with status.
• Presence of cryptogram on Y (if scheme requires).
• Challenge vs frictionless indicators not contradictory.

Audit: Persist raw PSP / DS payload securely (access-controlled).

6. Status Semantics

ID: 3ds.status.reference

Values:

• Y = Auth successful.
• A = Attempt (policy-dependent).
• C = Challenge in-progress (intermediate, not final).
• N = Not authenticated / failed.
• R = Rejected.
• U = Unable (system/issuer error).

Policy Examples:

• Approve: Y (always), A (conditional liability shift acceptance).
• Decline: N, R.
• Monitor / potential retry: U spikes.

7. Error & Resilience Patterns

ID: 3ds.resilience

Shared:

• Exponential backoff on transient network errors.
• Metrics: challenge rate, U rate, failure %, abandonment.
• Challenge idle timeout → classify as abandonment.

Embedded:

• Library load failure → deterministic fallback event.
• iFrame postMessage origin validation.

External:

• Normalize PSP proprietary codes to canonical statuses pre-submit.
• Ensure mandatory cryptogram fields on Y.

8. Operational Readiness

ID: 3ds.operations

Pre-Go-Live:

• Dashboards: success / challenge / failure / U / abandonment.
• Alerts: challenge spike, U surge, failure % threshold.
• Runbooks: issuer outage, PSP latency, rollback.
• Support playbook: user messaging per outcome.

Metadata Example:

9. File Placement Recommendation

ID: 3ds.files.structure

Keep detailed procedures in:

• ewsbooking-3ds-js.md
• ewsbooking-3ds-external.md
• pci-porxy-3ds-fields-mapping

This guide (3ds-integration-guide.md) serves as indexed overview + taxonomy.

10. Minimal Glossary

ID: 3ds.glossary

• paymentSessionId: Correlates booking attempt with 3DS context.
• initConfig: Configuration blob for embedded initialization.
• encodedChallengeConfig: Encoded parameters to render ACS challenge (embedded).
• Resume Booking API: Endpoint to finalize booking after authentication.