> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integrations/prism/api-reference/payment-method-authentication-service/pre-authenticate.md).

# Pre-authenticate

## Overview

The `PreAuthenticate` RPC initiates the 3D Secure authentication flow. It collects device data and prepares the authentication context, determining whether the transaction qualifies for frictionless authentication or requires a customer challenge.

**Business Use Case:** Before processing a card payment, you need to check if 3DS authentication is required. This RPC communicates with the issuing bank to initiate the authentication session and determine the authentication path (frictionless or challenge).

## Purpose

**Why pre-authenticate?**

| Scenario                  | Outcome                                             |
| ------------------------- | --------------------------------------------------- |
| **Low risk transaction**  | Bank approves frictionlessly (no customer action)   |
| **High risk transaction** | Bank requires challenge (OTP, password)             |
| **SCA compliance**        | Meet EU Strong Customer Authentication requirements |
| **Liability shift**       | Enable fraud liability protection                   |

**Key outcomes:**

* Authentication session initialized
* Risk assessment performed
* Challenge URL (if required)
* Authentication data for payment

## Request Fields

| Field                      | Type               | Required | Description                          |
| -------------------------- | ------------------ | -------- | ------------------------------------ |
| `merchant_order_id`        | string             | Yes      | Your unique order reference          |
| `amount`                   | Money              | Yes      | Transaction amount                   |
| `payment_method`           | PaymentMethod      | Yes      | Card details for authentication      |
| `customer`                 | Customer           | No       | Customer information                 |
| `address`                  | PaymentAddress     | Yes      | Billing address                      |
| `enrolled_for_3ds`         | bool               | Yes      | Whether 3DS enrollment check passed  |
| `metadata`                 | SecretString       | No       | Additional metadata                  |
| `connector_feature_data`   | SecretString       | No       | Connector-specific metadata          |
| `return_url`               | string             | No       | URL to redirect after authentication |
| `continue_redirection_url` | string             | No       | URL to continue after redirect       |
| `browser_info`             | BrowserInformation | No       | Browser details for fraud detection  |

## Response Fields

| Field                      | Type                | Description                                    |
| -------------------------- | ------------------- | ---------------------------------------------- |
| `connector_transaction_id` | string              | Connector's authentication transaction ID      |
| `status`                   | PaymentStatus       | Current status: PENDING, AUTHENTICATED, FAILED |
| `error`                    | ErrorInfo           | Error details if authentication failed         |
| `status_code`              | uint32              | HTTP-style status code                         |
| `response_headers`         | map\<string,string> | Connector-specific response headers            |
| `redirection_data`         | RedirectForm        | Challenge URL/form (if challenge required)     |
| `network_transaction_id`   | string              | Card network transaction reference             |
| `merchant_order_id`        | string              | Your order reference (echoed back)             |
| `state`                    | ConnectorState      | State to pass to next authentication step      |
| `raw_connector_response`   | SecretString        | Raw response for debugging                     |
| `authentication_data`      | AuthenticationData  | 3DS authentication results                     |

## Example

### Request (grpcurl)

```bash
grpcurl -H "x-connector: stripe" \
  -H "x-connector-config: {\"config\":{\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}}" \
  -d '{
    "merchant_order_id": "order_001",
    "amount": {
      "minor_amount": 10000,
      "currency": "USD"
    },
    "payment_method": {
      "card": {
        "card_number": "4242424242424242",
        "expiry_month": "12",
        "expiry_year": "2027",
        "cvc": "123"
      }
    },
    "address": {
      "billing_address": {
        "line_1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94105",
        "country": "US"
      }
    },
    "enrolled_for_3ds": true,
    "return_url": "https://your-app.com/3ds/return",
    "browser_info": {
      "accept_header": "text/html",
      "user_agent": "Mozilla/5.0..."
    }
  }' \
  localhost:8080 \
  types.PaymentMethodAuthenticationService/PreAuthenticate
```

### Response (Frictionless)

```json
{
  "connector_transaction_id": "pi_3Oxxx...",
  "status": "AUTHENTICATED",
  "authentication_data": {
    "eci": "05",
    "cavv": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
  },
  "status_code": 200
}
```

### Response (Challenge Required)

```json
{
  "connector_transaction_id": "pi_3Oxxx...",
  "status": "PENDING",
  "redirection_data": {
    "form": {
      "form_method": "POST",
      "form_url": "https://bank.com/3ds/challenge",
      "form_fields": {
        "creq": "..."
      }
    }
  },
  "state": {
    "connector_state": "..."
  },
  "status_code": 200
}
```

## Next Steps

* [Authenticate](/integrations/prism/api-reference/payment-method-authentication-service/authenticate.md) - Execute challenge if required
* [PostAuthenticate](/integrations/prism/api-reference/payment-method-authentication-service/post-authenticate.md) - Validate authentication results


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hyperswitch.io/integrations/prism/api-reference/payment-method-authentication-service/pre-authenticate.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.