Juspay Hyperswitch supports standalone 3DS authentication, a model where 3D Secure authentication runs as a separate step from payment authorization. Supported external 3DS authenticators are Netcetera, Cardinal, 3dsecure.io, and Juspay's own 3DS Server. The external 3DS server handles the AReq/ARes exchange with the card network and issuer ACS. Hyperswitch then routes the authorization with the CAVV, ECI, and DS Transaction ID from the authentication, to the configured PSP. CAVV (Cardholder Authentication Verification Value) is a cryptographic value generated by the issuer's ACS proving the issuer authenticated the specific transaction. Together with the ECI and DS Transaction ID, it may carry a SCA liability shift when included in the PSP authorization request.

What is a standalone 3DS and why does it matter?

Standalone 3DS is a payment authentication model that decouples 3D Secure authentication from PSP authorization. Instead of delegating authentication to the payment processor, the merchant controls authentication independently choosing the 3DS server, managing exemption logic, and routing the authorization to any PSP after the cryptogram is generated.

Hyperswitch implements standalone 3DS to give merchants three capabilities traditional PSP-managed 3DS does not:

• Fine-grained API control over each authentication request and the checkout experience
• Greater visibility into issuer authentication responses - exemption outcomes, challenge rates, ACS behavior by BIN
• PSP-agnostic cryptograms - a CAVV generated by the external 3DS server is a standard EMV 3DS 2.X artifact accepted by any PSP. In Smart Retry flows, the same authentication cryptogram can be submitted across multiple PSP authorization attempts without re-authenticating the customer.

How does the authentication flow work?

Juspay Hyperswitch supports two distinct flows depending on where 3DS runs.

Flow 1: Standalone 3DS via Hyperswitch

The external 3DS server is configured in Hyperswitch. Authentication and authorization both run through Hyperswitch's orchestration layer.

The full sequence from payment initiation through PSP authorization is shown below:

Step 1 - Payments Create: Set request_external_three_ds_authentication: true in the Payments Create API call. The response returns a client_secret and status requires_customer_action.

Step 2 - Authenticate: Call the authentication endpoint with the client_secret:

Step 3 - Handle challenge or frictionless: If transStatus = C, render the challenge URL in the frontend. After completion (or on frictionless approval), Hyperswitch calls PostAuthenticate automatically and retrieves the CAVV, ECI, and DS Transaction ID.

Step 4 - Authorization: Hyperswitch routes the authorization to the configured PSP with the authentication data embedded in the request.

Flow 2: Import 3DS results

When 3DS authentication runs entirely outside Juspay Hyperswitch, using a third-party 3DS provider that is not configured as a Hyperswitch connector, the authentication result can be imported directly into the payment flow:

Pass the completed authentication result in three_ds_data on the Payments Create call. All standard Hyperswitch payment flows are supported with imported 3DS results.

Flow 3 : 3DS with the PSP

When 3DS authentication runs entirely via the PSP, the authentication and authorization legs are tied to each other. The underlying PSP needs to support 3DS flows and the merchant needs to only pass authentication_type": "three_ds. Data required for a 3DS authentication request is typically collected from the customer during the transaction. To minimize friction and reduce the likelihood of authentication failures, we may enrich the request using additional signals. These can include information gathered during the payment flow.

In case a challenge is required, Hyperswitch sends back the redirect_to_url where the customer needs to be sent to complete the transaction. Post a successful authentication, any retriable failure during authorization would mean that the customer would need to redo authentication with the next PSP once the transaction is retried. This is the scenario where the coupling of authentication and authorization hurts the customer experience and flow

Which 3DS authenticators does Hyperswitch support?

Juspay Hyperswitch supports four external 3DS authenticators, configured under Connectors → 3DS Authenticator in the Hyperswitch dashboard.

Netcetera

Netcetera uses CertificateAuth - mutual TLS with a PEM-formatted client certificate stored in the Hyperswitch connector configuration.

DER-encoded certificates must be converted before entry: openssl x509 -inform DER -outform PEM -in cert.der -out cert.pem.

For native mobile flows (device_channel: APP), Netcetera provides Android and iOS SDKs. Three additional fields are required in the authentication call: sdkReferenceNumber, sdkEncData, and netceteraSDKApiKey.

Netcetera boundary statement: Netcetera owns the AReq/ARes exchange with the Directory Server, ACS challenge coordination, and CAVV generation. Hyperswitch owns the exemption type decision (via the Intelligence Engine), the PreAuthenticate/PostAuthenticate sequencing, the PSP routing decision, and the authorization payload construction with the authentication data. The CAVV, ECI and transStatus are the key artifacts that cross this boundary in the direction that matters for liability shift. The CAVV is the proof of authentication, the combination of ECI and transStatus will decide the liability shift.

3dsecure.io

3dsecure.io uses a JSON REST API for 3DS verification. Endpoints:

Juspay 3DS Server

The Juspay 3DS Server is Hyperswitch's native 3DS solution - no external credential configuration required. It integrates directly with the 3DS Intelligence Engine and is the lowest-friction option for merchants who do not have an existing 3DS provider relationship.

How do you set up an external 3DS in Hyperswitch?

Setup involves three steps in the Hyperswitch dashboard:

• Configure the 3DS authenticator: Connectors → Setup 3DS Authenticator → select Netcetera, Cardinal, 3dsecure.io, or Juspay 3DS Server → add credentials
• Configure payment processors: Connectors → Setup payment providers → add PSP credentials for authorization
• Link the authentication connector: Developers → Payment Settings → Add Authentication Connector
• Select a Merchant Category Code (MCC) in Developers → Payment Settings

Enable per-payment via the Payments Create API:

{
"request_external_three_ds_authentication": true
}

Key fields across the authentication flow:

What breaks - and how do you diagnose it?

Issuer overrides the exemption with a challenge

Symptom: PreAuthenticate returns transStatus = C despite a TRA or low-value exemption indicator in the AReq.

Root cause: The issuer ACS is not obligated to honor exemption indicators. PSD2 RTS Article 18 preserves the issuer's right to require full authentication regardless. High-risk BINs, new-to-merchant cardholders, and transactions that push past cumulative thresholds are challenged even with exemption indicators present. This is expected behavior.

Fix: The frontend must render the challenge URL for any transStatus = C response. A checkout flow that abandons on challenge will silently drop a meaningful percentage of customers - the exact rate varies by BIN, market, and time of day.

PostAuthenticate returns without a CAVV

Symptom: PostAuthenticate completes but authenticationValue is absent. The PSP may accept the authorization request; the acquirer declines it.

Root cause: The CAVV is generated by the issuer ACS and returned in the final ARes. If the customer abandons the challenge - closes the OTP window or lets the session expire - the ACS generates no CAVV.

Fix: Check for the absence of authenticationValue in the PostAuthenticate response before routing to the PSP. Forwarding without a CAVV causes an acquiring-level decline even when the PSP accepts the request. Treat it as an authentication failure and allow the customer to retry.

Netcetera TLS handshake failure

Symptom: PreAuthenticate fails with a TLS error per request. No authentication result is returned.

Root cause: The client certificate in Hyperswitch's Netcetera configuration doesn't match the certificate registered in Netcetera's system. Common causes: certificate expired, rotated without updating Hyperswitch, or uploaded in DER format instead of PEM.

Fix: Verify the certificate fingerprint matches Netcetera's registered certificate. Confirm PEM format. Credential updates take effect on the next PreAuthenticate call - no restart required.

ECI values and liability shift

The Electronic Commerce Indicator returned by the issuer ACS determines the liability category for each transaction:

Hyperswitch passes the ECI from PostAuthenticate to the PSP without modification. A successful PSP authorization on ECI 06 does not guarantee liability shift - card network rules govern this independently of the authorization outcome.

The setup_future_usage: off_session flag on the Payments Create API instructs Hyperswitch to store the payment method and generate a payment_method_id after the first authenticated transaction. Without it, subsequent merchant-initiated charges against that card fail before reaching the 3DS server.

Key Takeaways

• Standalone 3DS in Hyperswitch decouples authentication from PSP authorization. The same CAVV generated by an external 3DS server can be used across multiple PSP retry attempts - without re-authenticating the customer.
• The 3DS Intelligence Engine makes the SCA exemption decision across 22 configurable parameters. The 3DS server (Netcetera, Cardinal, or 3dsecure.io) encodes the exemption indicator. The issuer ACS decides whether to honor it.
• Supported external 3DS authenticators: Netcetera, Cardinal, 3dsecure.io, and Juspay 3DS Server. Configure under Connectors → 3DS Authenticator in the Hyperswitch dashboard.
• If a customer abandons the challenge, no CAVV is generated. Detect the missing authenticationValue in PostAuthenticate before routing to the PSP - forwarding without it causes an acquiring-level decline even when the PSP accepts the request.
• ECI 05 carries liability shift. ECI 06 (authentication attempted, ACS not supported) does not guarantee it - card network rules govern independently of PSP authorization outcome.
• request_external_three_ds_authentication: true in Payments Create activates standalone 3DS routing. Importing 3DS results from a fully external provider uses the three_ds_data object in Payments Create instead.