preAuthenticate Method

Overview

The preAuthenticate method initiates the 3D Secure authentication flow. It collects device data and prepares the authentication context, determining whether frictionless or challenge-based verification is needed.

Business Use Case: Before processing a high-value transaction, initiate 3DS to reduce fraud liability and comply with Strong Customer Authentication (SCA) requirements.

Purpose

Scenario	Benefit
Fraud prevention	Shift liability to card issuer
SCA compliance	Meet European regulatory requirements
Risk-based auth	Frictionless flow for low-risk transactions

Request Fields

Field	Type	Required	Description
merchantOrderId	string	Yes	Your unique order reference
amount	Money	Yes	Transaction amount
paymentMethod	PaymentMethod	Yes	Card details
customer	Customer	No	Customer information
returnUrl	string	Yes	URL to redirect after 3DS

Response Fields

Field	Type	Description
connectorTransactionId	string	Connector's 3DS transaction ID
status	string	AUTHENTICATION_REQUIRED, FRICTIONLESS
authenticationData	object	Device data for next step
redirectionData	object	Challenge URL if required
statusCode	number	HTTP status code

Example

SDK Setup

const { PaymentMethodAuthenticationClient } = require('hyperswitch-prism');

const authClient = new PaymentMethodAuthenticationClient({
    connector: 'stripe',
    apiKey: 'YOUR_API_KEY',
    environment: 'SANDBOX'
});

Request

const request = {
    merchantOrderId: "order_001",
    amount: {
        minorAmount: 10000,
        currency: "USD"
    },
    paymentMethod: {
        card: {
            cardNumber: { value: "4242424242424242" },
            cardExpMonth: { value: "12" },
            cardExpYear: { value: "2027" }
        }
    },
    returnUrl: "https://your-app.com/3ds/return"
};

const response = await authClient.preAuthenticate(request);

Response - Frictionless

{
    connectorTransactionId: "pi_3Oxxx...",
    status: "FRICTIONLESS",
    authenticationData: {
        eci: "05",
        cavv: "AAABBIIFmA=="
    },
    statusCode: 200
}

Response - Challenge Required

{
    connectorTransactionId: "pi_3Oxxx...",
    status: "AUTHENTICATION_REQUIRED",
    redirectionData: {
        url: "https://acs.bank.com/3ds/challenge",
        method: "POST"
    },
    statusCode: 200
}

3DS Flow

sequenceDiagram
    participant App as Your App
    participant CS as Prism
    participant Bank as Issuer Bank

    App->>CS: preAuthenticate
    CS->>Bank: Check 3DS eligibility
    Bank-->>CS: Return: frictionless or challenge
    CS-->>App: Return authentication data
    alt Challenge Required
        App->>Bank: Redirect customer to challenge
        Bank-->>App: Customer completes challenge
    end
    App->>CS: authenticate
    CS-->>App: Final authentication result

Next Steps

• authenticate - Complete the 3DS flow
• authorize - Process payment with 3DS data