External 3DS (Pass-Through) for EWSBooking {#ewsbooking-3ds-external}

Overview

Use this mode when you (or your PSP) fully perform 3DS outside Expedia (e.g., Datatrans) and obtain MPI authentication values. You then pass those values to EWSBooking so EGPayment can authorize against the issuer. No Expedia iFrame, no encoded init/challenge configs. Core Flow: External 3DS (frictionless or challenge) → receive MPI data → submit booking with MPI data → EGPayment validates with issuer → booking result. Key Artifacts (you supply): eci, authenticationValue (CAVV/AAV), directoryServerTransactionId, transStatus, optional xid, cavvAlgorithm, acsTransactionId, 3DSVersion, messageVersion.

High-Level Sequence

sequenceDiagram
    autonumber
    actor Client
    participant PartnerUI
    participant PSP as Datatrans (PSP)
    participant XAP as XAPBooking
    participant EGP as EGPayment
    participant Issuer as Card Issuer

    Client->>PartnerUI: Book with payment details
    PartnerUI->>PSP: Request 3DS authentication
    PSP->>Issuer: Initiate 3DS
    Issuer-->>PSP: Challenge
    PSP-->>PartnerUI: Challenge
    PartnerUI-->>Client: Present challenge
    Client->>PartnerUI: Execute challenge
    PartnerUI->>Issuer: Authenticate
    Issuer-->>PSP: Auth result
    PSP-->>PartnerUI: Auth result (MPI data)
    PartnerUI->>XAP: Book + MPI data
    XAP->>EGP: Authorize using MPI data
    note right of EGP: EGPayment uses Cardinal as provider
    EGP->>Issuer: Verify CAVV/ECI/DS Trans ID
    Issuer-->>EGP: Confirm
    EGP-->>XAP: Confirm
    XAP-->>PartnerUI: Booking response
    PartnerUI-->>Client: Confirmation page

Required MPI Data

Field Name	Description	Required	Example
`3DSVersion`	3DS protocol version	Yes	`2.2.0`
`eci`	Electronic Commerce Indicator	Yes	`05`
`authenticationValue`	CAVV or AAV	Yes	`AAABBBCCC...`
`directoryServerTransactionId`	DS Transaction ID	Yes	`b2a1f3e0-1234-5678-9abc-def123456789`
`transStatus`	Transaction status code	Yes	`Y`
`xid`	3DS v1 Transaction ID	No	`1234567890abcdef...`
`cavvAlgorithm`	CAVV algorithm indicator	No	`2`
`acsTransactionId`	ACS transaction ID	No	`abcdef12-3456-7890-abcd-ef1234567890`
`messageVersion`	3DS message protocol version	No	`2.2.0`

Steps

Step 1 — Perform External 3DS Authentication

Purpose: Obtain validated MPI data.

Collect card data (ensure PCI compliance).
Run frictionless or challenge through PSP.
On completion capture all returned MPI fields.
Ensure success criteria: transStatus Y or acceptable fallback (A), valid eci, non-empty authenticationValue.

Please refer to pci-proxy-3ds-fields-mapping for field definitions and meanings.

Step 2 — Submit Booking With MPI Data

Purpose: Pass MPI data for issuer authorization via EGPayment. Example request fragment:

{
  "TwoStepPaymentDetails": {
    "MpiData": {
      "3DSVersion": "2.2.0",
      "eci": "05",
      "authenticationValue": "AAABBBCCC...",
      "directoryServerTransactionId": "b2a1f3e0-1234-5678-9abc-def123456789",
      "transStatus": "Y",
      "xid": "1234567890abcdef...",
      "cavvAlgorithm": "2",
      "acsTransactionId": "abcdef12-3456-7890-abcd-ef1234567890",
      "messageVersion": "2.2.0"
    }
  },
  // other booking fields...
}

Step 3 — Handle Booking Response

Purpose: Surface confirmation or recover gracefully on auth issues.

Success: proceed to confirmation.
Decline / 3DS failure: offer retry or alternate payment method.
Distinguish issuer decline vs. field validation errors for correct UX.

Troubleshooting

code / condition	where	meaning	fix
INVALID_ARGUMENT	booking request	missing/invalid MPI fields	verify `eci`, `authenticationValue`, `directoryServerTransactionId`
FAILED_3DS_STATUS	EGPayment auth	`transStatus` not acceptable (e.g., `N`)	re-run 3DS; present fallback option
UNAUTHORIZED	EWS/booking call	token invalid/expired	refresh token
DUPLICATE_REQUEST	booking call	idempotency collision	send a new `Idempotency-Key`
PAYMENT_DECLINED	issuer auth	issuer declined	offer another card / retry later