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

# Hosted 3-D Secure

**Hosted 3-D Secure** is available when using the API or [Secure Fields](/guides/payments/secure-fields/),
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 dynamic skipping or forcing of 3-D Secure based on anti-fraud decisions, cart items, or any other
transaction data.

## Usage

To use 3-D Secure via the API, [set up](./setup) 3-D
Secure on any of the enabled payment services and pass a `redirect_url` when
creating the transaction.

```json POST /transactions theme={"system"}
{
  "amount": 1299,
  "currency": "AUD",
  "buyer_external_identifier": "user-1234",
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "security_code": "123",
    "redirect_url": "https://example.com/callback",
  }
}
```

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

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

Redirect the buyer to the `approval_url` and all
the intricacies of 3-D Secure are handled. 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
```

<Warning>
  Confirming the actual transaction status by fetching the
  updated transaction by its `id` is strongly recommended.
</Warning>

## Buyers and billing details

To optimize 3-D Secure it is highly recommended to provide a buyer with billing
details attached when making an API call. A buyer can be set up via the API or
provided as an [in-line guest buyer](/reference/transactions/new-transaction#body-buyer).

## Features

For every transaction, the following steps are handled.

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.