ℹ️ For details on how these APIs work together, please refer to the Workflows document.

📘
Idempotency
idempotencyKey is optional on /evaluate, and we recommend sending it on every request because it is the primary safety net for timeouts and network errors. A request without a key is accepted and processed, but it has no replay protection. Reusing the same key on a retry replays the original response within a 24-hour window instead of running a second evaluation. The same key with a different payload returns 409, and a value that is not a GUID returns 400. See the Idempotency reference (§3.4) for replay-window, conflict-detection, and retry behavior.

Payload Optimization - Rank scale

The Optimization Rank column on each table below indicates that field's contribution to rescue performance once required fields are in place. Use it as a prioritization list when tuning an existing integration.

Rank	Meaning
Critical	Directly drives rescue performance. Absence has a measurable negative impact.
High	Significantly improves rescue performance when present.
Medium	Contributes a useful signal; recommended to include.
Low	Informational or analytics value; minimal direct rescue impact.
Required	FlexFactor needs this field to evaluate the order. The API schema does not enforce it, so the reference panel shows it as optional.
—	Optional field. We recommend providing all data where available for a complete context.

Some rows carry a scoped qualifier (e.g. Required — CIT, Required — MIT, Required if parent object included) — these clarify when the field is required, not a different rank tier.

The API validation column shows only what the API schema enforces when it validates the request. On /evaluate the schema enforces no field, so every row reads optional and the reference panel shows the same. Read the Optimization Rank column for what FlexFactor needs in a real integration.

Request parameters

Property Name	Type	API validation	Optimization Rank	Notes
`isDeclined`	bool	optional	Required	Send this as `true` for all requests to evaluate.
`transactionType`	enum	optional	Conditional — required for `Auth + Capture`	AUTHORIZATION \| PURCHASE \| PREEVALUATE By default, accounts are configured for `purchase` only, and this parameter can be omitted. If you request to be able to use `authorization` you *must* provide a value. `PREEVALUATE` runs a lightweight screening pass instead of a full evaluation — see Pre-evaluate.
`mid`	string	optional	Required	FlexFactor Merchant Identification Number. Get your merchants' Mid
`orderId`	string	optional	Required — must be the same for every retry of a Sync MIT attempt so the retry matches the original request	Your internal order ID. This will reference your system of record with FlexFactor.
`siteId`	string	optional	Conditional — either `siteId` or `siteUrl` for Site assignment	Unique FlexFactor ID of the website/campaign generating this transaction. `siteId` is an explicit mapping to a FlexFactor site and Descriptor. `siteUrl` and `dynamicDescriptor` can be used to dynamically assign a FlexFactor site to an order if multiple descriptors are needed per FlexFactor MID. Retrieve your merchant's `siteId`
`customerIp`	string	optional	Critical for CIT — directly drives rescue performance	The customer's IP as captured on the checkout page. Must be the end-user / cardholder browser IP, not the merchant server IP.
`siteUrl`	string	optional	—	The URL can be specified if multiple domains share the same `siteId`.
`orderSource`	enum	optional	Low	Source of the order. If not sent, the default is `ecommerce`. Allowed values: `ecommerce`, `terminal`, `vterminal`.
`attemptNumber`	integer	optional	High	The authorization attempt number this request represents: `1` for the original attempt, `2` for the first retry, and so on. Send the merchant's own attempt counter for the order.
`idempotencyKey`	guid/uuid	optional, recommended	High — replay safety on retries	Generate a unique GUID/UUID so we can identify repeated requests. A request without a key is processed without replay protection. Reuse the same key when retrying after a timeout to replay the original response (24h window) instead of running a fresh evaluation; a reused key carrying a different payload returns a `409` conflict, and a value that is not a GUID returns `400`. See Idempotency.
`sequenceNumber`	string	optional	Conditional — SFTP batch only	*SFTP ONLY:* Numerical position of that transaction within the batch.
`senseKey`	string	optional	—	SenseJS session key; echoed back in the response. See SenseJS.
`isMIT`	bool	optional	Required	`true` for merchant-initiated transactions. When `true`, FlexFactor needs the MIT fields.
`caller`	enum	optional	—	Channel that submitted the order. Allowed values: `Api`, `Adapter`, `Webhook`, `Sftp`. Omit it on direct API calls.
`transaction`	object	optional	Required	See transaction fields below.
`payer`	object	optional	Required	See payer fields below.
`billingInformation`	object	optional	Required by default, can be relaxed	See billingInformation fields below.
`paymentMethod`	object	optional	Required	See paymentMethod fields below.
`shippingInformation`	object	optional	Low	See shippingInformation fields below.
`deviceDetails`	object	optional	High — significantly improves rescue performance	See deviceDetails fields below.
`merchant`	object	optional	High	See merchant fields below.
`orderItems`	object array	optional	Medium	See orderItems fields below.
`additionalFields`	object array	optional	Low	See additionalFields fields below.
`userDefinedFields`	object array	optional	Low	Array of key/value objects with the same shape as `additionalFields`.
`extraData`	string	optional	—	Open-ended string that accepts a serialized JSON array of objects with any additional context you want stored with the order.

Try it right now: check out the /evaluate Reference. or the Postman Collection

Additional parameters for MIT

For a Merchant Initiated Transaction (for example, a subscription rebill), FlexFactor needs the following additional fields:

Property Name	Type	API validation	Optimization Rank	Notes
`isRecurring`	bool	optional	Required	`true` for subscriptions.
`expiryDateUtc`	datetime	optional	—	Indicates the period during which FlexFactor will retry the transaction. ISO 8601 format in UTC. E.g.: `2026-06-22T12:30:00Z` - When omitted, the default expiry configured for the merchant in FlexFactor applies. - Rescue window: up to 21 days from the original decline. If you send it, set it to the merchant retry window, not beyond.
`subscription`	object	optional	Required — MIT	Required when both `isMIT` and `isRecurring` are `true`. See subscription fields below.
`threeDsecure`	object	optional	High — significantly improves rescue performance	See 3DSecure fields below.

❗️
Send only MIT that have just failed
The FlexFactor service is optimized to work with failed Merchant Initiated Transactions (MIT) that have just failed. These need to be passed to FlexFactor on that day (and not after a few days or weeks) and should not be retried by the Merchant up to the set expiry date.

Detailed object parameters:

transaction

Object FlexFactor needs for every evaluation. It carries the context and details of the declined transaction.

Property Name	Type	API validation	Optimization Rank	Notes
`id`	string	optional	Required	External transaction identifier from the original decline.
`amount`	integer	optional	Required	Amount of the transaction in `cents`
`currency`	string	optional	Required	ISO 4217 currency code. E.g.: 'USD', 'EUR'
`dynamicDescriptor`	string	optional	Conditional	Required only if enabled by FlexFactor for your configuration. Pass the descriptor from the MID that declined the transaction.
`timestampUtc`	datetime	optional	Required	Date and time of the declined transaction. ISO 8601 format in UTC. E.g.: `2026-06-01T12:30:00Z`
`timezoneUtcOffset`	integer	optional	—	UTC offset of the timezone. Optional; you can omit it.
`transactionType`	string	optional	High	E.g.: 'Auth', 'Capture', 'Void'
`responseCode`	string	optional	High	Response code received from the gateway.
`responseDescription`	string	optional	High	Description of the response, usually the response message.
`responseStatus`	string	optional	High	E.g.: Approved, Declined, Voided, Refunded, Chargeback, etc.
`responseSubStatus`	string	optional	Medium	Sub-status of the response.
`responseCodeSource`	string	optional	High	This is the source of the code from the original transaction. E.g.: "nmi", "Paypal"
`processorName`	string	optional	High	Name of the processor.
`avsResultCode`	string	optional	High	Address Verification Service result code.
`cvvResultCode`	string	optional	High	Card Verification Value result code.
`cavvResultCode`	string	optional	Medium	Cardholder Authentication Verification Value result code.
`cardNotPresent`	bool	optional	High	Indicates if the card was present during the transaction.

paymentMethod

Property Name	Type	API validation	Optimization Rank	Notes
`cardNumber`	string	optional	Required	Send the token that was returned with /tokenize.
`expirationYear`	integer	optional	Required	Card expiration year
`expirationMonth`	integer	optional	Required	Card expiration Month
`verificationValue`	string	optional	Critical	CVV value directly drives CIT rescue performance
`holderName`	string	optional	Required	Card Holder Name
`token`	boolean	optional	Required if sending PCI data — set value to `false`	`true` indicates `cardnumber` is a token. `false` indicates it is `PAN` data.
`cardType`	string	optional	Required	`CREDIT`, `DEBIT`, `PREPAID`
`cardBrand`	string	optional	Required	`VISA` `Mastercard`
`cardCountry`	string	optional	Required	ISO 3166-1 alpha-2 country code (2-letter).
`cardIssuer`	string	optional	Medium	E.g., MY BANK
`cardLevel`	string	optional	Low
`cardFingerprint`	string	optional	Low
`cardBinNumber`	string	optional	Required	6-character string.
`cardLast4Digits`	string	optional	Required	4-character string.

billingInformation

Object FlexFactor needs by default; it can be relaxed on request.

Property Name	Type	API validation	Optimization Rank	Notes
`firstName`	string	optional	Required	Cardholder First Name
`lastName`	string	optional	Required	Cardholder Last Name
`fullName`	string	optional	—	Full name of the cardholder.
`phone`	string	optional	—	Cardholder Contact Phone
`country`	string	optional	Required	Cardholder Billing Country
`countryCode`	string	optional	Required	ISO 3166-1 alpha-2 country code (2-letter)
`addressLine1`	string	optional	Required	Cardholder Billing Address
`addressLine2`	string	optional	—
`state`	string	optional	Required (US)	2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
`city`	string	optional	Required	Cardholder Billing City
`zipcode`	string	optional	Required	5 or 9 digit Billing Zip Code

Payer

Object FlexFactor needs for every evaluation.

Property Name	Type	API validation	Optimization Rank	Notes
`email`	string	optional	Required	Customer's email
`phone`	string	optional	Medium	Customer's phone
`id`	string	optional	Low	Customer's ID in your system
`birthdate`	datetime	optional	Low	Customer's birthdate
`paymentMethods`	array	optional	Only applicable for Customer Wallet integrations	Customer's additional payment methods information on file. See details below.

PaymentMethods

Optional array within the Payer object.

NOTE This is for integrations leveraging wallet-style decline recovery where a customer may have multiple stored payment methods. This allows the merchant to send all payment methods at once, allowing FlexFactor to optimize the recovery and manage which payment instruments can be rescued.

Contains an array of payment method information (ACH, credit cards). Each payment method follows a consistent structure with a type identifier, payment-specific data, and optional billing information.

Property Name	Type	API validation	Optimization Rank	Notes
`type`	string	optional	Required if the parent object is included	CARD \| ACH (case-insensitive)
`value`	object	optional	Required if the parent object is included	Payment method-specific properties: `ACH` — bank transfer, see the values below `CARD` — credit card, see the values below
`billingInformation`	object	optional	High	Optional billing details per payment method. Applicable if the Payment Method AVS Value differs. See values below.

ACH

value object when 'type':'ACH' in PaymentMethods

Property	Type	API validation	Optimization Rank	Notes
`accountType`	string	optional	Required if the parent object is included	Type of bank account. CHECKING \| SAVINGS (case-insensitive)
`accountNumber`	string	optional	Required if the parent object is included	Bank account number.
`routingNumber`	string	optional	Required if the parent object is included	Bank routing number.
`accountHolderType`	string	optional	—	Type of account holder. Allowed values: "company", "individual" (case-insensitive)

Card

value object when 'type':'card' in PaymentMethods

Same format as paymentMethod object. Optimization Ranks for each property carry over from the paymentMethod table above — most notably, verificationValue is Critical for rescue performance and schemeTransactionId on the parent subscription remains the single highest-leverage field for MIT and card-on-file rescue.

billingInformation

Optional

Same object as billingInformation

affiliate

optional object

Property Name	Type	API validation	Optimization Rank	Notes
`id`	string	optional	Low	This is an internal identifier for the affiliate. It's typically used for backend or database purposes to uniquely identify affiliates within a system.
`name`	string	optional	Low	This is a friendly name or label associated with the affiliate.

deviceDetails

Optional object. The parent object is High rank — significantly improves rescue performance when present.

Property Name	Type	API validation	Optimization Rank	Notes
`deviceType`	string	optional	Required if the parent object is included	Type of device used for that transaction (e.g., 'mobile', 'laptop', 'tablet')
`deviceName`	string	optional	Required if the parent object is included	Name of the device (e.g., 'iPhone 12', 'Samsung Galaxy S21')
`deviceOS`	string	optional	Required if the parent object is included	Operating system of the device (e.g., 'iOS 14', 'Android 11')
`browser`	string	optional	Required if the parent object is included	Name of the browser (e.g., 'Chrome', 'Safari')
`userAgent`	string	optional	Required if the parent object is included	User-agent string (a detailed string provided by the browser that identifies the browser, its version, and the operating system)

merchant

Optional object for partners only.

Property Name	Type	API validation	Optimization Rank	Notes
`id`	string	optional	Required if the parent object is included	External ID
`name`	string	optional	Required if the parent object is included	Name of the merchant
`mcc`	integer	optional	Required if the parent object is included	MCC code that the merchant is enrolled with standard processing MID(s).
`country`	string	optional	Required if the parent object is included	The country in which the merchant operates

subscription

Required object when isMIT and isRecurring are true.

Property Name	Type	API validation	Optimization Rank	Notes
`subscriptionId`	string	optional	Required — MIT	Should be unique per subscriber within the merchant platform. Combined with other subscription elements to make acceptance decisions.
`price`	int	optional	Required — MIT	Amount in cents.
`currency`	string	optional	Required — MIT
`interval`	string	optional	Required — MIT	E.g.: 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
`intervalCount`	int	optional	Low	Number of `interval` units between payments. Defaults to `1`. E.g.: `interval: 'monthly'` with `intervalCount: 3` = a charge every 3 months.
`schemeTransactionId`	string	optional	Critical for MIT and card-on-file	Network Transaction Id (NTI). Send on MIT rebills and on any card-on-file transaction. Visa example Transaction ID: `987654321234567`. Mastercard example Trace ID: `MCCABC1XY0107`. Note: This is not MC `TLID`
`schemeBrand`	string	optional	Low	Card/scheme brand associated with the subscription. Will generally be similar to the `cardBrand` value, but might differ in some edge cases. E.g.: Visa
`paymentNumber`	string	optional	Low	The sequential number indicates the specific payment within the subscription cycle. E.g., Customer subscribed monthly on Jan 15: Jan 15 is `paymentNumber: 1`, Feb 15 is `paymentNumber: 2`, Mar 15 is `paymentNumber: 3`.
`totalPayments`	string	optional	Low	Total number of payments for that subscription. E.g., Customer subscribed monthly for 6 months: `totalPayments: 6`. Leave null if the subscription is indefinite.

threeDsecure

Optional passthrough object. Provide when the original transaction carried a 3DS authentication so FlexFactor can pass it on to the issuer. The parent object is High rank — significantly improves rescue performance when present.

Property Name	Type	API validation	Optimization Rank	Notes
`threeDsVersion`	string	optional	—	Protocol version for the card payment authentication. E.g.: '1.0.2' '2.1.0' '2.2.0'
`ecommerceIndicator`	string	optional	Required if the parent object is included	The indication of an online commerce transaction.
`authenticationValue`	string	optional	Required if the parent object is included	The encrypted code from the cardholder's bank.
`directoryServerTransactionId`	string	optional	Required if the parent object is included	The unique ID for the transaction with the bank.
`xid`	string	optional	—	Transaction identifier generated by the 3D Secure system.
`authenticationValueAlgorithm`	string	optional	—	The encryption algorithm used to secure the payment. E.g.: SHA-256
`directoryResponseStatus`	string	optional	—	The response status code from the bank's directory. E.g.: 'Y'
`authenticationResponseStatus`	string	optional	—	The response status code for the payment authentication. E.g.: 'Y'
`enrolled`	string	optional	—	The card's enrollment status in 3D Secure. E.g.: 'Y'

orderItems

Optional object.

Property Name	Type	API validation	Optimization Rank	Notes
`sku`	string	optional	Low	The SKU of the item.
`name`	string	optional	Low	The name of the item.
`description`	string	optional	Low	The description of the item.
`amount`	integer	optional	Low	The amount of the item.
`discountAmount`	integer	optional	Low	The discount amount on the item.
`tax`	integer	optional	Low	The tax on the item.
`discountType`	string	optional	Low	The discount type on the item.
`quantity`	integer	optional	Low	The quantity of this item.

shippingInformation

Optional object.

Property Name	Type	API validation	Optimization Rank	Notes
`firstName`	string	optional	Low
`lastName`	string	optional	Low
`fullName`	string	optional	—	Full name of the recipient.
`phone`	string	optional	Low
`country`	string	optional	Required if the parent object is included
`countryCode`	string	optional	Required if the parent object is included	ISO 3166-1 alpha-2 country code (2-letter)
`addressLine1`	string	optional	Required if the parent object is included
`addressLine2`	string	optional	Required if the parent object is included
`state`	string	optional	Required if the parent object is included	2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
`city`	string	optional	Required if the parent object is included
`zipcode`	string	optional	Required if the parent object is included	5 or 9 digits

additionalFields

Optional array of objects. Max 50 objects

Property Name	Type	API validation	Optimization Rank	Notes
`key`	string	optional	Low	Max 40 characters, Description of the additional information.
`value`	string	optional	Low	Max 500 characters, Content of the additional information.

Response status

The /evaluate response uses the common FlexFactor response envelope: result describes the API request, and status describes the transaction outcome. The envelope, the rules for reading the HTTP status code, and the full transaction state model are defined once in Workflows §3.5.

Property Name	Type	Notes
`result`	string	Result of the API request: `Success` \| `Failed` (mixed case). ⚠️ This is not the result of the transaction — see `status` below. A declined rescue is `result: Success` with `status: DECLINED`. `Failed` is returned only when the evaluation did not complete (an evaluation timeout, a concurrent evaluation of the same order, or an unexpected error); `status` is then `DECLINED` as a fallback and `success` is `false`.
`status`	string	For sync calls: `APPROVED`, `DECLINED`, `CHALLENGE`, `CAPTUREREQUIRED`. For async calls: `SUBMITTED`.
`success`	boolean	`true` when `errors` is empty — `false` only on the `Failed` paths above.
`orderId`	guid/uuid	FlexFactor order identifier. Preferred — easier to read and aligns with common vernacular. Use it for order lookup, capture, refund, and cancel.
`orderSessionKey`	guid/uuid	FlexFactor unique transaction identifier. Returned alongside `orderId`; prefer `orderId`.
`senseKey`	string	Optional. Echoes the value sent in the request.
`statusCode`	string	Never populated on this endpoint; always `null`. It is not the HTTP status code.
`errors`	array of objects	Error details; empty on success. Each item is serialized positionally: `item1` message, `item2` key, `item3` error code, `item4` friendly flag (boolean).
`metadata`	array of objects	Optional. Key/value entries with additional data about the outcome, for example `SchemeTransactionId` on `APPROVED` and `CAPTUREREQUIRED` outcomes when your account has opted in. Omitted when empty.
`customProperties`	object	Optional. Additional properties.

Order status

A transaction moves through the statuses below. The /evaluate response reports the status synchronously (see Response status); the order lifecycle is then tracked with GET /orders, which returns a string status and a coarser state.

/evaluate response statuses

Status	Type of status	Description
Challenge	⚠️ Conditional	The transaction rescue requires an action from the customer. This action can be performed via the UI Widget. If the UI Widget is not embedded, treat as a decline.
Capture required	⚠️ Conditional	The transaction rescue requires a /capture. For Authorize flows the capture must be called within 5 minutes of the authorize response by default. If no capture arrives in time, the order expires to status `cancelled` and `order.expired` fires.
Approved	✅ Success	The transaction was rescued (synchronous CIT / Sync MIT).
Declined	❌ Fail	The transaction could not be rescued (synchronous).
Submitted	⏳ Pending	The transaction was received for asynchronous processing. Track the outcome with GET /orders or webhooks.

GET /orders order statuses

GET /orders and GET /orders/{id} return status as a lowercase string. GET /orders/{id} also returns state, a coarser grouping with the values Processing, Cancelled, CaptureRequired, and Completed. The older statusName field is deprecated; read status instead, or state on GET /orders/{id}.

`status`	Type of status	Description
`draft`	⏳ Pending	The `MIT` order was picked up by the system, but is not yet being processed.
`onhold`	⏳ Pending	The order is temporarily on hold.
`cancelled`	❌ Fail	The order was cancelled (voided). An MIT order that passes its rescue window (its `expiryDateUtc`, or the merchant default expiry) also resolves here — the `order.expired` webhook fires so you can distinguish expiry from a cancellation. An authorization that is not captured within its capture window also resolves here with `order.expired`.
`problem`	❌ Fail	A processing problem occurred.
`processing`	⏳ Pending	The order is being processed.
`capturerequired`	⚠️ Conditional	The rescue requires a /capture.
`returned`	↩️ Returned	Defined in the status enum. A refund does not move an order here — a refunded order stays `completed` and `refundsAmount` increases.
`completed`	✅ Success	The transaction was rescued — funds captured. A refunded order stays here; read `refundsAmount`.
`disputed`	⚠️ Conditional	The order has an open dispute.

❕
Update the order status with GET /orders
Immediate response from /evaluate cannot cover all scenarios, please update the order status with

GET /orders/[id] or GET /orders

webhooks subscription

HTTP status codes

Situation	HTTP	Body
The evaluation ran	`200`	Envelope. Read `status` for the transaction outcome and `result` for the API outcome; `result: Failed` means the evaluation did not complete
`idempotencyKey` is not a GUID, or the request failed validation	`400`	Problem details naming the fields in error — see Error Handling
Invalid or expired bearer token	`401`	Problem details
Not found	`404`	Problem details
Same `idempotencyKey` reused with a different body, or the first request is still running	`409`	Problem details — see Idempotency §3.4
An internal error occurred	`500`	—
Idempotency store temporarily unavailable — honor `Retry-After` and retry	`503`	Problem details

Payload examples

For minimum (required-fields-only) and optimal (all-fields) request payloads for both CIT and MIT, see the dedicated Payload examples page.

Request example

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 '
{
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "isDeclined": true,
  "isMIT": false,
  "orderId": "987-654-321",
  "idempotencyKey": "0b7a1c2e-4f5d-4a6b-8c9d-1e2f3a4b5c6d",
  "customerIp": "203.0.113.42",
  "attemptNumber": 2,
  "transaction": {
    "id": "3478613",
    "amount": 15000,
    "currency": "USD",
    "timestampUtc": "2026-06-01T12:30:00Z",
    "responseCode": "203",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "processorName": "Acme Payments",
    "avsResultCode": "M",
    "cvvResultCode": "M",
    "transactionType": "Purchase"
  },
  "payer": {
    "id": "customer123",
    "email": "[email protected]"
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "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",
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111",
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t",
    "token": true
  },
  "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"
  }
}
'

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/evaluate \
     --header 'Authorization: Bearer {bearer_token_returned_by_oauth2}' \ //replace with bearer returned by oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{

	"isMIT": true,
	"isRecurring": true,
	"expiryDateUtc": "2023-05-24T12:30:20Z",
	"attemptNumber": 3, //which retry this is for the order; 1 = first/original attempt
	"subscription": {
    //Required fields
		"subscriptionId": "sub_123456",
    "interval": "Monthly",
		"price": 2599,
		"currency": "USD",
    //Optional metadata to improve cure rate
		"schemeTransactionId": "txn_789012",
		"schemeBrand": "Visa",
		"paymentNumber": "2",
		"totalPayments": "12"
	}, 
  
   "transaction": {
    //Required fields
    "amount": 15000,	//must be greater than 1000 and less than 20000 (amount is in cents, i.e. between $10 and $200) for test calls
    "currency": "USD",
    "id": "3478613",
    "dynamicDescriptor": "MyShoesStore",
    //Optional metadata to improve cure rate
    "timestampUtc": "0001-01-01T00:00:00Z",
    "timezoneUtcOffset": 0,
    "responseCode": "203",
    "avsResultCode": "M",
    "processorName": "Acme Payments",
    "cavvResultCode": "2",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "transactionType": "AUTHORIZATION"
  },
  
	"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]", //must be this exact address mail if using the Visa test card ending 1111
    "phone": "+1 555-123-4567",
    "birthdate": "1990-01-01",
    "paymentMethods": [
    {
      "type": "card",
      "value": {
        "holderName": "Jane Doe",
    		"cardType": "CREDIT",
    		"cardBrand": "VISA",
        "cardCountry": "United States",
        "cardIssuer": "Acme Bank",
        "cardFingerprint": "abcd1234",
        "expirationMonth": 12,
        "expirationYear": 2028,
        "cardBinNumber": "411111",
        "cardLast4Digits": "1111",
        "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear if you are not PCI complipant, send token returned by /tokenize	
      },
      "billingInformation": {
        "firstName": "Jane",
        "lastName": "Doenowitz",
        "phone": "+1 555-123-4567",
        "country": "United States",
        "countryCode": "US",
        "addressLine1": "123 Main St.",
        "state": "CA",
        "city": "San Francisco",
        "zipcode": "94111"
      }
    }
  ]

  },
  "orderItems": [
    {
      "sku": "SKU123",
      "name": "Subscription 1",
      "description": "Description of Subscription 1",
      "amount": 20000,
      "discountAmount": 0,
      "tax": 100,
      "quantity": 1
    },
    {
      "sku": "SKU456",
      "name": "Subscription 2",
      "description": "Description of Subscription 2",
      "amount": 10000,
      "discountAmount": 0,
      "tax": 50,
      "quantity": 1
    }
  ],
  "shippingInformation": {
    "firstName": "John",
    "lastName": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "city": "Los Angeles",
    "zipcode": "94111"
  },
  "merchant": {
    "country": "US",
    "mcc": 1234,
    "id": "merchant123",
    "name": "Acme Inc."
  },
  "affiliate": {
    "id": "123123123",
    "name": "Affiliate 1"
  },
  "paymentMethod": {
    "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" //Do not send credit card number in clear, send token returned by /tokenize
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45", //replace with your mid
  "isDeclined": true,
  "orderId": "987-654-321", //must be unique even for test calls
  "idempotencyKey": "6f9a2b3c-1d4e-4f5a-9b8c-7d6e5f4a3b2c"
}
'

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/evaluate \
     --header 'Authorization: Bearer abc123def456' \ //replace with bearer returned by oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{

	"isMIT": true,
	"isRecurring": true,
	"expiryDateUtc": "2023-05-24T12:30:20Z",
	"attemptNumber": 3, //which retry this is for the order; 1 = first/original attempt
	"subscription": {
		"subscriptionId": "sub_123456",
		"schemeTransactionId": "txn_789012",
		"schemeBrand": "Visa",
		"interval": "Monthly",
		"price": 2599,
		"currency": "USD",
		"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"
	},
  "transaction": {
    "id": "3478613",
    "timestampUtc": "0001-01-01T00:00:00Z",
    "timezoneUtcOffset": 0,
    "amount": 19975, //must be greater than 1000 and less than 20000 (amount is in cents, i.e. between $10 and $200) for test calls
    "currency": "USD",
    "responseCode": "203",
    "avsResultCode": "M",
    "cvvResultCode": "NA",
    "processorName": "Acme Payments",
    "cavvResultCode": "2",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "transactionType": "CAPTURE",
    "dynamicDescriptor": "MyShoesStore"
  },
  "payer": {
    "id": "customer123",
    "email": "[email protected]", //must be this exact address mail if using the Visa test card ending 1111
    "phone": "+1 555-123-4567",
    "birthdate": "1990-01-01"
  },
  "orderItems": [
    {
      "sku": "SKU123",
      "name": "Subscription 1",
      "description": "Description of Subscription 1",
      "amount": 20000,
      "discountAmount": 0,
      "tax": 100,
      "quantity": 1
    },
    {
      "sku": "SKU456",
      "name": "Subscription 2",
      "description": "Description of Subscription 2",
      "amount": 10000,
      "discountAmount": 0,
      "tax": 50,
      "quantity": 1
    }
  ],
  "shippingInformation": {
    "firstName": "John",
    "lastName": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "city": "Los Angeles",
    "zipcode": "94111"
  },
  "merchant": {
    "country": "US",
    "mcc": 1234,
    "id": "merchant123",
    "name": "Acme Inc."
  },
  "affiliate": {
    "id": "123123123",
    "name": "Affiliate 1"
  },
  "paymentMethod": {
    "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" //Do not send credit card number in clear, send token returned by /tokenize
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45", //replace with your mid
  "isDeclined": true,
  "orderId": "987-654-321", //must be unique even for test calls
  "idempotencyKey": "3c2b1a0d-9e8f-4a5b-8c7d-6e5f4a3b2c1d"
}
'

//file name: 'evaluate_{yourfilename}'
//any file without the prefix will not be picked up

{
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45", //replace with your mid
  "authorizationToken": "Bearer abc123def456", //replace with bearer returned by oauth2
  "expiryDateUtc": "2023-04-05T01:23:45.678Z", //default expiry date and time for the whole batch, you can specify individual expiryDate within each transaction
  "requests": [
    {
    
    "sequenceNumber": 1, // The numerical position of the transaction within the batch.
    "isDeclined": true,
    "isMIT": true,
    "isRecurring": true,
    "attemptNumber": 2, //which retry this is for the order; 1 = first/original attempt
    "SiteUrl": "https://example.com", //Website linked to the descriptor of the subscription.
    "subscription": {
      "subscriptionId": "sub_123456",
      "schemeTransactionId": "txn_789012",
      "schemeBrand": "Visa",
      "interval": "Monthly",
      "price": 2599,
      "currency": "USD",
      "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"
    },
    "transaction": {
      "id": "3478613",
      "timestampUtc": "0001-01-01T00:00:00Z",
      "timezoneUtcOffset": 0,
      "amount": 19975, //must be greater than 1000 and less than 20000 (amount is in cents, i.e. between $10 and $200) for test calls
      "currency": "USD",
      "responseCode": "203",
      "avsResultCode": "M",
      "cvvResultCode": "NA",
      "processorName": "Acme Payments",
      "cavvResultCode": "2",
      "responseCodeSource": "NMI",
      "responseDescription": "Activity limit exceeded",
      "responseStatus": "DECLINED",
      "transactionType": "CAPTURE",
      "dynamicDescriptor": "MyShoesStore"
    },
    "payer": {
      "id": "customer123",
      "email": "[email protected]",
      "phone": "+1 555-123-4567",
      "birthdate": "1990-01-01"
    },
    "orderItems": [
      {
        "sku": "SKU123",
        "name": "Subscription 1",
        "description": "Description of Subscription 1",
        "amount": 20000,
        "discountAmount": 0,
        "tax": 100,
        "quantity": 1
      },
      {
        "sku": "SKU456",
        "name": "Subscription 2",
        "description": "Description of Subscription 2",
        "amount": 10000,
        "discountAmount": 0,
        "tax": 50,
        "quantity": 1
      }
    ],
    "shippingInformation": {
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1 555-123-4567",
      "country": "United States",
      "countryCode": "US",
      "addressLine1": "123 Main St.",
      "city": "Los Angeles",
      "zipcode": "94111"
    },
    "merchant": {
      "country": "US",
      "mcc": 1234,
      "id": "merchant123",
      "name": "Acme Inc."
    },
    "paymentMethod": {
      "holderName": "John Doe",
      "cardType": "CREDIT",
      "cardBrand": "VISA",
      "cardCountry": "United States",
      "cardIssuer": "Acme Bank",
      "cardFingerprint": "abcd1234",
      "expirationMonth": 12,
      "expirationYear": 2028,
      "cardBinNumber": "123456",
      "cardLast4Digits": "7890",
      "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
    },
    "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"
    },

    "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511", //must be unique even for test calls
    "idempotencyKey": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "senseKey": "1234567890"
},
{ 
    "sequenceNumber": 2, // The numerical position of the transaction within the batch.
    "isMIT": true,
    "isRecurring": true,
    "isDeclined": true,
    "attemptNumber": 4, //which retry this is for the order; 1 = first/original attempt
    "SiteUrl": "https://example.com", //Website linked to the descriptor of the subscription
    "subscription": {
        "subscriptionId": "sub_654321",
        "schemeTransactionId": "txn_210987",
        "schemeBrand": "Mastercard",
        "interval": "Weekly",
        "price": 1599,
        "currency": "USD",
        "paymentNumber": "3",
        "totalPayments": "52"
    },
      "threeDsecure": {
        "threeDsVersion": "2.2.0",
        "ecommerceIndicator": "01",
        "authenticationValue": "hijklm67890",
        "directoryServerTransactionId": "ds_456789",
        "xid": "xid_135790",
        "authenticationValueAlgorithm": "SHA-512",
        "directoryResponseStatus": "A",
        "authenticationResponseStatus": "C",
        "enrolled": "Y"
    },
      "transaction": {
        "id": "1234567",
        "timestampUtc": "0001-01-01T00:00:00Z",
        "timezoneUtcOffset": 0,
        "amount": 14999,
        "currency": "USD",
        "responseCode": "204",
        "avsResultCode": "N",
        "cvvResultCode": "M",
        "processorName": "XYZ Payments",
        "cavvResultCode": "1",
        "responseCodeSource": "Braintree",
        "responseDescription": "Insufficient funds",
        "responseStatus": "DECLINED",
        "transactionType": "AUTHORIZE"
    },
      "payer": {
        "id": "customer456",
        "email": "[email protected]",
        "phone": "+1 555-987-6543",
        "birthdate": "1985-05-05"
    },
      "orderItems": [
    {
        "sku": "SKU789",
        "name": "Product 3",
        "description": "Description of Product 3",
        "amount": 30000,
        "discountAmount": 0,
        "tax": 150,
        "quantity": 2
    },
    {
        "sku": "SKU012",
        "name": "Product 4",
        "description": "Description of Product 4",
        "amount": 25000,
        "discountAmount": 0,
        "tax": 125,
        "quantity": 1
    }
    ],
      "shippingInformation": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1 555-987-6543",
        "country": "United States",
        "countryCode": "US",
        "addressLine1": "456 Oak St.",
        "city": "New York",
        "zipcode": "10001"
    },
      "merchant": {
        "country": "US",
        "mcc": 5678,
        "id": "merchant456",
        "name": "XYZ Inc."
    },
    "affiliate": {
   		 "id": "123123123",
   		 "name": "Affiliate 1"
 		 },
      "paymentMethod": {
        "holderName": "Jane Doe",
        "cardType": "CREDIT",
        "cardBrand": "MASTERCARD",
        "cardCountry": "United States",
        "cardIssuer": "XYZ Bank",
        "cardFingerprint": "efgh5678",
        "expirationMonth": 12,
        "expirationYear": 2028,
        "cardBinNumber": "123456",
        "cardLast4Digits": "7890",
        "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
    },

      "billingInformation": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1 555-987-6543",
        "country": "United States",
        "countryCode": "US",
        "addressLine1": "456 Oak St.",
        "city": "New York",
        "zipcode": "10001"
      },
      
      "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09512", //must be unique even for test calls
      "idempotencyKey": "d4c3b2a1-6f5e-4b7a-9d8c-0f1e2a3b4c5d",
      "senseKey": "1234567890"
}
  ]
}

Response example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": "Success | Failed",
  "status": "APPROVED | DECLINED | CHALLENGE | CAPTUREREQUIRED | SUBMITTED",
  "orderId": "{{$guid}}",
  "orderSessionKey": "{{$guid}}",
  "senseKey": "value that was present in the evaluate request",
  "success": true,
  "statusCode": null,
  "errors": [],
  "metadata": [
    { "key": "SchemeTransactionId", "value": "987654321234567" }
  ],
  "customProperties": {}
}

HTTP 200 means FlexFactor processed the request. Read status for the transaction outcome — a declined rescue is HTTP 200 with status: DECLINED. See Workflows §3.5.

How to use the Optimization Rank column

Start with the Required rows. Every field ranked Required (or Required — CIT / Required — MIT for your flow, or qualified variants like Required (cents) / Required (US) / Required (partners)) must be in the payload before optimization work begins. The API schema does not enforce these fields, so the reference panel shows them as optional; FlexFactor still needs them to evaluate the order. Fields ranked Required if parent object included only apply when you include the parent object — but when the parent is sent, FlexFactor needs those children too.
Then add the Critical fields. Two fields are formally Critical: paymentMethod.verificationValue (CVV) for CIT and subscription.schemeTransactionId for MIT and card-on-file transactions. Populate these on every applicable request.
Then High, then Medium. The transaction decline context (responseCode, responseCodeSource, processorName), the full deviceDetails block, and the root attemptNumber (which retry FlexFactor is receiving) are the largest non-Critical lifts. The Medium tier sharpens routing on harder declines.
Low fields are analytics-grade. Send when readily available.
Do not hard-code fields. paymentMethod.cardType, cardBrand, cardCountry, and holderName must come from your BIN lookup and checkout data — not defaults. customerIp (CIT) must be the cardholder browser or device IP, not the merchant server IP.

Idempotency

Payload Optimization - Rank scale

Request parameters

Additional parameters for MIT

Send only MIT that have just failed

transaction

paymentMethod

billingInformation

Payer

PaymentMethods

ACH

Card

billingInformation

affiliate

deviceDetails

merchant

subscription

threeDsecure

orderItems

shippingInformation

additionalFields

Response status

Order status

Update the order status with GET /orders

HTTP status codes

Payload examples

Request example

Response example

How to use the Optimization Rank column

What’s Next