> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattildapayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted 3-D Secure

**Universal 3-D Secure** is also available without Embed as long as any payment
service has been [set up](./setup) for 3-D Secure. This integration equally supports
**Dynamic 3-D Secure** which can be set up using Flow rules, allowing you to dynamically
skip or force 3-D Secure based on anti-fraud decisions, cart items, or any other
transaction data.

## Usage

All you need to do to use 3-D Secure via the API is to [set up](./setup) 3-D
Secure on any of the enabled payment services and pass a `redirect_url` when
creating the transaction.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -i -X POST "https://api.mattildapayments.com/transactions" \
      -H "Authorization: Bearer [JWT_TOKEN]" \
      -H "Content-Type: application/json" \
      -d '{
            "amount": 1299,
            "currency": "MXN",
            "buyer_external_identifier": "user-1234",
            "payment_method": {
              "method": "card",
              "number": "4111111111111111",
              "expiration_date": "11/25",
              "security_code": "123",
              "redirect_url": "https://example.com/callback",
            }
          }'
  ```

  ```js Node theme={"dark"}
  var fetch = require("node-fetch");

  fetch("https://api.mattildapayments.com/transactions", {
    method: "POST",
    headers: {
      Authorization: "Bearer [JWT_TOKEN]",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 1299,
      currency: "MXN",
      buyer_external_identifier: "user-1234",
      payment_method: {
        method: "card",
        number: "4111111111111111",
        expiration_date: "11/21",
        security_code: "123",
        redirect_url: "https://example.com/callback",
      },
    }),
  });
  ```
</CodeGroup>

With 3-D Secure configured for a payment service, we will automatically detect
if it is required to get the buyer's approval for a transaction. If it is
required the API will return a transaction with the status
`buyer_approval_pending` and an `approval_url` that the buyer can be sent to.

```json theme={"dark"}
{
  "type": "transaction",
  "id": "869df4fc-a3db-43db-806a-14464d9e6920",
  "status": "buyer_approval_pending",
  "payment_method": {
    "approval_url": "https://embed.mattildapayments.com/...",
    ...
  },
  ...
}
```

You can then redirect the buyer to the `approval_url` and we will handle all
the intricacies of 3-D Secure. Once the buyer has approved (or rejected) the
transaction the browser is redirected back to the `redirect_url` that was set
when the transaction was created.

The `redirect_url` will be appended with both a transaction ID and status.

```
https://example.com/callback?transaction_id=123&transaction_status=capture_succeeded
```

We strongly recommend confirming the actual transaction status by fetching the
updated transaction by its `id`.

## Buyers & Billing Details

To optimize 3-D Secure it is highly recommended to provide a buyer with billing
details attached to Embed.

A buyer can be set up via our [`POST /buyers`](/reference/buyers/new-buyer)
API. The buyer can then be attached to Embed by using the `buyerId` or
`buyerExternalIdentifier` property. The buyer's name, email address, and billing
address will be used to help reduce buyers being requested to complete a 3-D
Secure challenge.

## Features

For every transaction, we will handle the following steps.

1. Detect if any Flow rule explicitly requires or skips 3-D Secure
2. Detect if the selected payment service for this transaction has 3-D Secure
   enabled
3. Detect if the card used in the transaction is enrolled for 3-D Secure
4. Handle the seamless frictionless 3-D Secure flow including the device finger
   printing once the user is redirected to the `approval_url`.
5. Handle the 3-D Secure challenge flow, where a buyer is directed to their bank
   to approve the transaction.