3DS Authentication Flow

A 3D Secure (3DS) Authentication Flow introduces an additional customer authentication step before authorization is finalized. This flow is typically required for regulatory compliance or when the issuer decides that step-up authentication is necessary based on risk signals. Unlike instant payments, the lifecycle temporarily pauses and waits for customer interaction before proceeding.

The flow begins with a standard payment creation call: POST /payments with authentication_type: "three_ds"

At this point, Hyperswitch attempts to confirm the payment. Instead of moving directly to Processing, the connector responds that additional authentication is required. The payment transitions:

RequiresConfirmation → RequiresCustomerAction

The response includes a redirect_url (or authentication payload) that the client must use to redirect the customer to the issuer’s 3DS challenge page.

The client then redirects the customer to the 3DS page, where the customer interacts directly with their issuing bank. This may involve:

• OTP entry

• Biometric approval

• Banking app confirmation

• Out-of-band authentication

Once the customer completes the 3DS challenge, the bank sends the authentication result back through the network. Hyperswitch resumes the payment lifecycle:

RequiresCustomerAction → Processing

From here, the authorization attempt continues. If the issuer approves the transaction after successful authentication, the payment moves to:

Processing → Successful

If authentication fails or the customer abandons the challenge, the payment transitions to:

RequiresCustomerAction → Failed (or potentially Cancelled or Expired, depending on timing and connector behavior)

Conceptually, the important distinction in 3DS flows is that the payment lifecycle becomes event-driven. Instead of a continuous synchronous flow, the system pauses in RequiresCustomerAction until an external event (authentication completion) triggers the next state transition.

Despite the added complexity, the lifecycle model remains consistent. The only additional state introduced is RequiresCustomerAction, which temporarily hands control to the customer before Hyperswitch resumes processing.