> 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 with `rel = threeds_redirect_url` and `method = REDIRECT`
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`.

The payment is pending while authentication is required. Its transaction currently includes the following result values:

```json
{
  "status": "pending",
  "resultCode": "2101",
  "sourceResultCode": "threeds-required",
  "resultMessage": "threeds-required"
}
```

Use the payment `status` and `actions` for flow control. Do not depend on `resultMessage` as the redirect signal.

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

if (threeDSAction) {
  window.location.href = threeDSAction.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)