Overview

Pre-evaluate is a lightweight mode of POST /evaluate — the same API: same endpoint, authentication, and payload. You opt in by setting the root-level transactionType field to PREEVALUATE; there is no separate URL. Values are accepted case-insensitively, but PREEVALUATE is the canonical casing.

Environment	URL
Sandbox	`https://api-sandbox.flexfactor.io/v1/evaluate`
Production	`https://api.flexfactor.io/v1/evaluate`

Rather than running the full rescue flow, FlexFactor performs an upfront screening pass and returns one of two outcomes:

PRE_EVALUATION_PASSED — the transaction will be evaluated by FlexFactor for rescue.
PRE_EVALUATION_REJECTED — the transaction does not meet the requirements for evaluation and is excluded from processing, returning a DECLINED response.

When to use it

Run preevaluate as a screening step ahead of a real /evaluate call when you want an early read on a transaction. It is fast and side-effect free — no order is created, no rescue is attempted, and no funds move.

Request

A pre-evaluation accepts the entire standard /evaluate payload. The only required fields are:

Property Name	Type	Required?	Notes
`transactionType`	string	required	Must be `PREEVALUATE`.
`transaction.amount`	integer	required	Amount of the transaction in `cents`.
`transaction.currency`	string	required	ISO 4217 currency code. E.g.: 'USD', 'EUR'

Every other field is optional. Sending the same payload you would use for a real /evaluate gives the most representative result, since FlexFactor screens against the same data it would see on a full evaluation.

Response

A pre-evaluation returns one of two statuses:

Status	Meaning
`PRE_EVALUATION_PASSED`	FlexFactor would take this transaction on for full evaluation. Proceed with a standard `/evaluate`.
`PRE_EVALUATION_REJECTED`	FlexFactor would block this transaction. A full `/evaluate` is not expected to be attempted.

Payload examples

Minimal request

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/evaluate \
     --header 'Authorization: Bearer {bearer_token_returned_by_oauth2}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "transactionType": "PREEVALUATE",
  "transaction": {
    "amount": 15000,
    "currency": "USD"
  }
}
'

Full request

The example below includes every object the standard /evaluate payload supports. All of it except transaction.amount and transaction.currency is optional.

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/evaluate \
     --header 'Authorization: Bearer {bearer_token_returned_by_oauth2}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "transactionType": "PREEVALUATE",
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "isDeclined": true,
  "isMIT": true,
  "isRecurring": true,
  "expiryDateUtc": "2026-06-29T12:30:20Z",
  "orderId": "987-654-321",
  "idempotencyKey": "abcd1234",
  "customerIp": "203.0.113.42",
  "attemptCount": 2,
  "siteId": "site_12345",
  "siteUrl": "https://example.com",
  "orderSource": "ecommerce",
  "transaction": {
    "id": "3478613",
    "amount": 15000,
    "currency": "USD",
    "dynamicDescriptor": "MyShoesStore",
    "timestampUtc": "2026-06-01T12:30:00Z",
    "timezoneUtcOffset": 0,
    "transactionType": "AUTHORIZATION",
    "responseCode": "203",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "responseSubStatus": "limit",
    "responseCodeSource": "NMI",
    "processorName": "Acme Payments",
    "avsResultCode": "M",
    "cvvResultCode": "M",
    "cavvResultCode": "2",
    "cardNotPresent": true
  },
  "subscription": {
    "subscriptionId": "sub_123456",
    "price": 2599,
    "currency": "USD",
    "interval": "Monthly",
    "schemeTransactionId": "txn_789012",
    "schemeBrand": "Visa",
    "paymentNumber": 2,
    "totalPayments": 12
  },
  "threeDSecure": {
    "threeDsVersion": "2.1.0",
    "ecommerceIndicator": "02",
    "authenticationValue": "abcdefg12345",
    "directoryServerTransactionId": "ds_987654",
    "xid": "xid_246810",
    "authenticationValueAlgorithm": "SHA-256",
    "directoryResponseStatus": "Y",
    "authenticationResponseStatus": "Y",
    "enrolled": "Y"
  },
  "payer": {
    "id": "customer123",
    "email": "[email protected]",
    "phone": "+1 555-123-4567",
    "birthdate": "1990-01-01",
    "paymentMethods": [
      {
        "Type": "card",
        "Value": {
          "holderName": "John Doe",
          "cardType": "CREDIT",
          "cardBrand": "VISA",
          "cardCountry": "United States",
          "cardIssuer": "Acme Bank",
          "cardFingerprint": "abcd1234",
          "expirationMonth": 12,
          "expirationYear": 2028,
          "cardBinNumber": "411111",
          "cardLast4Digits": "1111",
          "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t"
        },
        "BillingInformation": {
          "firstName": "John",
          "lastName": "Doe",
          "phone": "+1 555-123-4567",
          "country": "United States",
          "countryCode": "US",
          "addressLine1": "123 Main St.",
          "state": "CA",
          "city": "San Francisco",
          "zipcode": "94111"
        }
      }
    ]
  },
  "paymentMethod": {
    "holderName": "John Doe",
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "US",
    "expirationMonth": 12,
    "expirationYear": 2028,
    "verificationValue": "123",
    "cardIssuer": "Acme Bank",
    "cardLevel": "PLATINUM",
    "cardFingerprint": "abcd1234",
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111",
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t",
    "token": true
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "addressLine2": "Suite 200",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "shippingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "addressLine2": "Suite 200",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "deviceDetails": {
    "deviceType": "laptop",
    "deviceName": "MacBook Pro",
    "deviceOS": "macOS 14",
    "browser": "Chrome",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"
  },
  "merchant": {
    "id": "merchant123",
    "name": "Acme Inc.",
    "mcc": 1234,
    "country": "US"
  },
  "affiliate": {
    "id": "123123123",
    "name": "Affiliate 1"
  },
  "orderItems": [
    {
      "sku": "SKU123",
      "name": "Subscription 1",
      "description": "Description of Subscription 1",
      "amount": 20000,
      "discountAmount": 0,
      "tax": 100,
      "discountType": "none",
      "quantity": 1
    }
  ],
  "additionalFields": [
    {
      "key": "loyaltyTier",
      "value": "gold"
    }
  ]
}
'

Response example

{
  "status": "PRE_EVALUATION_PASSED | PRE_EVALUATION_REJECTED"
}