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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Forter

> Screen card payments with Forter in your Payrails workflow, and see the Portal setup, decisions and request fields Forter requires.

Screen card payments with [Forter](https://www.forter.com/) before or after authorization. Payrails sends Forter the order, customer, device and card details and maps Forter's decision to a Payrails decision your workflow acts on. Forter can also recommend a 3D Secure challenge instead of declining the payment.

## Supported operations

| Operation | Supported | Forter endpoint |
| - | - | - |
| Pre-authorization score | ✔ | Adaptive authentication order, `PRE_AUTHORIZATION` step |
| Post-authorization score | ✔ | Adaptive authentication order, `POST_AUTHORIZATION` step |
| Order updates | ✔ | Order status |
| Dispute reporting | ✖ | |

Forter returns its decision in the response, so the Fraud Check step completes straight away.

## Decisions

| Forter decision | Forter recommendation | Payrails decision |
| - | - | - |
| `APPROVE` | Any | `Allow` |
| `DECLINE` | `VERIFICATION_REQUIRED_3DS_CHALLENGE` | `Challenge` |
| `DECLINE` | Any other | `Prevent` |
| `NOT_REVIEWED` | Any | `Review` |

## Before you begin

1. In the Payrails Portal, go to **Settings → Integrations** and select **Add instance**.
2. Select the workspaces where Forter should be available.
3. Select **Fraud** as the integration type, then **Forter** as the provider.
4. Enter your Forter credentials and save:

| Field | Description |
| - | - |
| **Site ID** | The unique ID of your store registered with Forter. |
| **Key** | Your Forter secret key. |

5. Load the Forter provider in the [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk#forter) with your site ID, or pass the Forter token from your own Forter integration in `meta.risk.sessions`.
6. Add a **Fraud Check** step with your Forter integration to your workflow. See [Authorization with fraud screening](/docs/orchestration/workflow-studio/examples/authorization-with-fraud).

## Request fields for Forter

Send these fields in the authorize request, in addition to the standard [authorize fields](/reference/authorizeaction). **Required** fields must be present for the score to succeed. Payrails sends **Optional** fields to Forter when you include them.

| Field | Status | Description |
| - | - | - |
| `merchantReference` | Required | Set on the execution. Sent to Forter as the order ID, for the score and every order update. |
| `amount` | Required | Sent to Forter as the order total. The order lines, tax and discounts must add up to this amount. |
| Card details | Required | Payrails sends the card holder name, BIN, last four digits, expiry and issuing country from the payment instrument. |
| `meta.risk.sessions` | Required | An entry with `provider` set to `forter` and the Forter token as `sessionId`. Payrails falls back to `meta.risk.sessionId` when there's no Forter entry. |
| `meta.clientContext.ipAddress` | Required | Sent to Forter as the customer IP address. |
| `meta.clientContext.userAgent` | Required | Sent to Forter as the user agent. A browser user agent sets the order type to `WEB`. |
| `meta.customer.reference` | Required | Sent to Forter as the account ID. |
| `meta.customer.name`, `meta.customer.lastName` | Required | Sent to Forter as the account owner's name. |
| `meta.customer.email` | Required | Sent to Forter as the account owner's email. |
| `meta.order.shippingType` | Required | `physical`, `digital` or `hybrid`. Sent to Forter as the delivery type and method. |
| `meta.order.deliveryAddress` | Required | Needs `name`, `lastName`, `email`, `phone`, `street`, `doorNumber`, `city`, `state`, `postalCode` and `country.code`. Sent to Forter as the primary recipient. |
| `meta.order.billingAddress` | Required | Needs the same fields as the delivery address. Sent to Forter as the billing details. |
| `meta.order.lines` | Required | At least one line. Each line needs `name`, `type` (`lineItem`, `tax` or `discount`), `quantity` and `product.type`. Sent to Forter as the cart items. |
| `meta.customer.createdAt` | Optional | RFC 3339 date-time. Sent to Forter as the account creation date. |
| `meta.clientContext.osType` | Optional | Sets the order type to `ANDROID` or `IOS` for app payments. |
| `meta.clientContext.deviceFingerprint` | Optional | Sent to Forter as your device identifier. |
| `meta.order.shipping` | Optional | Sent to Forter as the delivery price. |

## Send order updates

Add a **Fraud Update** step after each lifecycle action and set its `orderStatus`. Payrails sends Forter the matching status.

| Payrails order status | Forter status |
| - | - |
| `pending`, `processing` | `PROCESSING` |
| `partiallyShipped`, `fullyShipped`, `partiallyDelivered` | `SENT` |
| `fullyDelivered`, `noShow` | `COMPLETED` |
| `partiallyReplaced`, `fullyReplaced` | `REPLACED` |
| `partiallyReturned`, `fullyReturned` | `RETURNED` |
| `merchantCancelled`, `failed` | `CANCELED_BY_MERCHANT` |
| `customerCancelled` | `CANCELED_BY_CUSTOMER` |

## Example authorize request

```json Authorize request theme={null}
{
  "amount": { "value": "120.00", "currency": "EUR" },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "card",
      "amount": { "value": "120.00", "currency": "EUR" }
    }
  ],
  "meta": {
    "customer": {
      "reference": "customer-1001",
      "name": "Lena",
      "lastName": "Fischer",
      "email": "lena.fischer@example.com",
      "createdAt": "2025-03-14T09:30:00Z"
    },
    "clientContext": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36"
    },
    "risk": {
      "sessions": [{ "provider": "forter", "sessionId": "2f6b1c84d0e94a7f9c3e5a1b7d2e8f40" }]
    },
    "order": {
      "shippingType": "physical",
      "lines": [
        {
          "id": "sku-204",
          "name": "Running shoes",
          "type": "lineItem",
          "quantity": 1,
          "unitPrice": { "value": "120.00", "currency": "EUR" },
          "product": { "type": "physical" }
        }
      ],
      "deliveryAddress": {
        "name": "Lena",
        "lastName": "Fischer",
        "email": "lena.fischer@example.com",
        "phone": { "countryCode": "+49", "number": "15123456789" },
        "street": "Torstraße",
        "doorNumber": "12",
        "city": "Berlin",
        "state": "BE",
        "postalCode": "10119",
        "country": { "code": "DE" }
      },
      "billingAddress": {
        "name": "Lena",
        "lastName": "Fischer",
        "email": "lena.fischer@example.com",
        "phone": { "countryCode": "+49", "number": "15123456789" },
        "street": "Torstraße",
        "doorNumber": "12",
        "city": "Berlin",
        "state": "BE",
        "postalCode": "10119",
        "country": { "code": "DE" }
      }
    }
  }
}
```


## Related topics

- [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk.md)
- [Fraud integrations](/docs/orchestration/fraud-integrations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.