Pre-authenticate

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

Next Steps

• authenticate - Complete the 3DS flow

• authorize - Process payment with 3DS data