> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/payments/3ds-integration.md).

# 3D Secure Integration Guide

Use 3D Secure to add cardholder authentication when your merchant configuration requires it.

## Overview

In the current public contract, 3DS behavior is driven by merchant payment-method configuration and the payment context you submit. The payment request itself does not use a dedicated `use3DS` flag.

For card-not-present payments, send complete browser context and handle redirect actions if Plexo returns them.

## How the Public Flow Works

1. Configure 3DS rules on the merchant payment method
2. Create the payment with `POST /v1/payments`
3. If the transaction is frictionless, the payment continues without customer interaction
4. If a challenge is required, the response includes an `actions` entry such as `approval_url`
5. Redirect the customer to the issuer challenge page
6. Poll `GET /v1/payments/{paymentId}` or consume your callback to observe the final state

## Configure 3DS on the Merchant Payment Method

The public spec exposes merchant payment-method 3DS endpoints:

* `GET /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds`
* `POST /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds`
* `PUT /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds`

Use those endpoints, or the Dashboard, to enable and tune 3DS before testing payment flows.

## Create a Payment That Can Trigger 3DS

```http
POST /v1/payments
Authorization: Basic {credentials}
Content-Type: application/json

{
  "merchantId": 12345,
  "referenceId": "order-1001",
  "invoiceNumber": "INV-1001",
  "amount": {
    "total": 10000,
    "currency": "UYU"
  },
  "paymentMethod": {
    "source": "card",
    "card": {
      "number": "4000000000003063",
      "expMonth": 12,
      "expYear": 2028,
      "cvc": "123",
      "cardholder": {
        "firstName": "Test",
        "lastName": "User",
        "email": "customer@example.com"
      }
    }
  },
  "browserDetails": {
    "ipAddress": "203.0.113.10",
    "userAgent": "Mozilla/5.0"
  },
  "capture": {
    "method": "automatic"
  },
  "callbackUrl": "https://merchant.example.com/callbacks/payments"
}
```

## Handle Redirect Actions

When a challenge is required, the payment response includes redirect instructions in `actions`.

```javascript
const approvalAction = payment.actions?.find(
  (action) => action.rel === 'approval_url' && action.method === 'REDIRECT'
);

if (approvalAction) {
  window.location.href = approvalAction.href;
}
```

If no redirect action is present, continue with your normal success or pending-payment handling based on the payment status.

## Track Authentication Outcomes

Use these contract-backed sources to track 3DS results:

* `GET /v1/payments/{paymentId}` for the payment resource and `threeDS` details
* `GET /v1/threeds/sessions` for 3DS session reporting
* `callbackUrl` on the payment request for asynchronous payment updates

### Query 3DS sessions

Use `GET /v1/threeds/sessions` when you need reporting across many authentication attempts.

```http
GET /v1/threeds/sessions?status=step-up-required&minDate=2024-12-01&page=1&size=20
Authorization: Basic {credentials}
```

Common filters include `merchants`, `sessionId`, `status`, `paymentMethodId`, `currency`, `minAmount`, `maxAmount`, `minDate`, and `maxDate`.

The response includes both paginated results and a `summary` object, which is useful for operational dashboards and reconciliation.

## Best Practices

* Configure 3DS at the merchant payment-method level before integration testing
* Always send `browserDetails` for browser-based card payments
* Treat `actions` as the source of truth for challenge redirects
* Keep callback and redirect URLs stable and reachable over HTTPS
* Test both frictionless and challenge cards in the testing environment

## Related Resources

* [3DS Statuses](/rest-api/reference/3ds-statuses.md)
* [Payment Processing](/rest-api/payments/payment-processing.md)
* [PaymentActions](/rest-api/api-reference/models.md#paymentactions)


---

# 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://plexo.gitbook.io/rest-api/payments/3ds-integration.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.