Forter

Screen card payments with Forter 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

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

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

Load the Forter provider in the Payrails Web Fraud SDK with your site ID, or pass the Forter token from your own Forter integration in meta.risk.sessions.
Add a Fraud Check step with your Forter integration to your workflow. See Authorization with fraud screening.

Request fields for Forter

Send these fields in the authorize request, in addition to the standard authorize fields. 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

Authorize request

{
  "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" }
      }
    }
  }
}

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported operations

Decisions

Before you begin

Request fields for Forter

Send order updates

Example authorize request

​Supported operations

​Decisions

​Before you begin

​Request fields for Forter

​Send order updates

​Example authorize request

Supported operations

Decisions

Before you begin

Request fields for Forter

Send order updates

Example authorize request