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

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	Infrastructure or routing field; required for the request to be valid, with no separate performance signal beyond that.
—	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 — Managed MIT, Required if parent object included) — these clarify when the field is required, not a different rank tier.

Request parameters

Property Name	Type	Required?	Optimization Rank	Notes
`isDeclined`	bool	required	Required	Required: Send this as true for all requests to evaluate.
`transactionType`	enum	optional	Conditional — required for `Auth + Capture`	AUTHORIZATION \| PURCHASE 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.
`mid`	string	required	Required	FlexFactor Merchant Identification Number. Get your merchants' Mid
`orderId`	string	required	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`.
`attemptCount`	integer	optional	High	The authorization attempt number this request represents — tells FlexFactor which retry it is receiving from the merchant. `1` = the first/original authorization attempt, `2` = the first retry, and so on. Send the merchant's own attempt counter for the order.
`idempotencyKey`	guid/uuid	required	Required	You need to generate a unique GUID/UUID so that we can identify repeated requests.
`sequenceNumber`	string	required for batch via SFTP	Conditional — SFTP batch only	*SFTP ONLY:* Numerical position of that transaction within the batch.
`isMIT`	bool	required	Required	`true` for merchant-initiated transactions. When `true`, requires specific MIT fields.
`transaction`	object	required	Required	See transaction fields below.
`payer`	object	required	Required	See payer fields below.
`billingInformation`	object	required	Required by default, can be relaxed	See billingInformation fields below.
`paymentMethod`	object	required	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.

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

Additional parameters for MIT

A request for Merchant Initiated Transaction (e.g., subscriptions) requires the following additional fields:

Property Name	Type	Required?	Optimization Rank	Notes
`isRecurring`	bool	required	Required	`true` for subscriptions.
`expiryDateUtc`	datetime	optional	Conditional on the Merchant MIT configuration	Indicates the period during which FlexFactor will retry the transaction. - Required when your configuration is async MIT. - Default rescue window: up to 21 days from the original decline. Set this value to the merchant retry window, not beyond.
`subscription`	object	required when `isRecurring` is `true`	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

Required object, contains context and details of the declined transaction being sent to FlexFactor.

Property Name	Type	Required?	Optimization Rank	Notes
`id`	string	required	Required	External transaction identifier from the original decline.
`amount`	integer	required	Required	Amount of the transaction in `cents`
`currency`	string	required	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	required	Required	Date and time of the declined transaction.
`timezoneUtcOffset`	integer	optional	Low	UTC offset of the timezone.
`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	Required?	Optimization Rank	Notes
`cardNumber`	string	required	Required	Send the token that was returned with /tokenize.
`expirationYear`	integer	required	Required	Card expiration year
`expirationMonth`	integer	required	Required	Card expiration Month
`verificationValue`	string	optional	Critical	CVV value directly drives CIT rescue performance
`holderName`	string	required	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	required	Required	`CREDIT`, `DEBIT`, `PREPAID`
`cardBrand`	string	required	Required	`VISA` `Mastercard`
`cardCountry`	string	required	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	required	Required	6-character string.
`cardLast4Digits`	string	required	Required	4-character string.

billingInformation

Required object by default; can be relaxed by FlexFactor on request.

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

Payer

Required object

Property Name	Type	Required?	Optimization Rank	Noted
`email`	string	required	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	Required?	Optimization Rank	Notes
`Type`	string	required	Required if the parent object is included	CARD \| ACH (case-insensitive)
`Value`	object	required	Required if the parent object is included	Payment method-specific properties: `ACH` — bank transfer, see required values below `CARD` — credit card, see required 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	Required?	Optimization Rank	Notes
`AccountType`	string	required	Required if the parent object is included	Type of bank account. CHECKING \| SAVINGS (case-insensitive)
`AccountNumber`	string	required	Required if the parent object is included	Bank account number.
`RoutingNumber`	string	required	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 MIT field.

billingInformation

Optional

Same object as billingInformation

affiliate

optional object

Property Name	Type	Required?	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	Required?	Optimization Rank	Notes
`deviceType`	string	required if this object is provided	Required if the parent object is included	Type of device used for that transaction (e.g., 'mobile', 'laptop', 'tablet')
`deviceName`	string	required if this object is provided	Required if the parent object is included	Name of the device (e.g., 'iPhone 12', 'Samsung Galaxy S21')
`deviceOS`	string	required if this object is provided	Required if the parent object is included	Operating system of the device (e.g., 'iOS 14', 'Android 11')
`browser`	string	required if this object is provided	Required if the parent object is included	Name of the browser (e.g., 'Chrome', 'Safari')
`userAgent`	string	required if this object is provided	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	Required?	Optimization Rank	Notes
`id`	string	required if this object is provided	Required if the parent object is included	External ID
`name`	string	required if this object is provided	Required if the parent object is included	Name of the merchant
`mcc`	integer	required if this object is provided	Required if the parent object is included	MCC code that the merchant is enrolled with standard processing MID(s).
`country`	string	required if this object is provided	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	Required?	Optimization Rank	Notes
`subscriptionId`	string	required if this object is provided	Required — MIT	Should be unique per subscriber within the merchant platform. Combined with other subscription elements to make acceptance decisions.
`price`	int	required if this object is provided	Required — MIT	Amount in cents.
`currency`	string	required if this object is provided	Required — MIT
`interval`	string	required if this object is provided	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	Network Transaction Id. 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	Required?	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	required if this object is provided	Required if the parent object is included	The indication of an online commerce transaction.
`authenticationValue`	string	required if this object is provided	Required if the parent object is included	The encrypted code from the cardholder's bank.
`directoryServerTransactionId`	string	required if this object is provided	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	Required?	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`	string	optional	Low	The quantity of this item.

shippingInformation

Optional object.

Property Name	Type	Required?	Optimization Rank	Notes
`firstName`	string	required if this object is provided	Low
`lastName`	string	required if this object is provided	Low
`phone`	string	optional	Low
`country`	string	required if this object is provided	Required if the parent object is included
`countryCode`	string	required if this object is provided	Required if the parent object is included	ISO 3166-1 alpha-2 country code (2-letter)
`addressLine1`	string	required if this object is provided	Required if the parent object is included
`addressLine2`	string	optional	Required if the parent object is included
`state`	string	required if this object is provided	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	required if this object is provided	Required if the parent object is included
`zipCode`	string	required if this object is provided	Required if the parent object is included	5 or 9 digits

additionalFields

Optional array of objects. Max 50 objects

Property Name	Type	Required?	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

Property Name	Type	Notes
`result`	string	Result of the API request: `SUCCESS` \| `FAILED`. ⚠️ This is not the result of the transaction — see `status` below.
`status`	string	For sync calls: `APPROVED`, `DECLINED`, `CHALLENGE`, `CAPTUREREQUIRED`. For async calls: `SUBMITTED`.
`orderSessionKey`	guid/uuid	FlexFactor unique transaction identifier.
`senseKey`	string	Optional.

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 numeric status and a matching statusName.

/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.
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 a numeric status with a matching statusName:

`status`	`statusName`	Type of status	Description
0	Draft	⏳ Pending	The `MIT` order was picked up by the system, but is not yet being processed.
1	Onhold	⏳ Pending	The order is temporarily on hold.
2	Cancelled	❌ Fail	The order was cancelled (voided). An MIT order that passes its `expiryDateUtc` also resolves here — the `order.expired` webhook fires so you can distinguish expiry from a cancellation.
3	Problem	❌ Fail	A processing problem occurred.
4	Processing	⏳ Pending	The order is being processed.
5	Capturerequired	⚠️ Conditional	The rescue requires a /capture.
6	Returned	↩️ Returned	The order was refunded/returned.
7	Completed	✅ Success	The transaction was rescued — funds captured.

❕
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

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": "abcd1234",
  "customerIp": "203.0.113.42",
  "attemptCount": 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",
	"attemptCount": 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,	//In cents. must be >10 and <20000 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 4111111111111111 test card
    "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": "CA",
    "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": "abcd1234",
}
'

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",
	"attemptCount": 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, //In cents. must be >10 and <20000 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 4111111111111111 test card
    "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": "CA",
    "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": "abcd1234",
}
'

//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,
    "attemptCount": 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, //in cents, >$10 and <$200 for tests
      "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": "CA",
      "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": "abcd1234",
    "senseKey": "1234567890"
},
{ 
    "sequenceNumber": 2, // The numerical position of the transaction within the batch.
    "isMIT": true,
    "isRecurring": true,
    "isDeclined": true,
    "attemptCount": 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": "NY",
        "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": "NY",
        "zipcode": "10001"
      },
      
      "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09512", //must be unique even for test calls
      "idempotencyKey": "abcd1234",
      "senseKey": "1234567890"
}
  ]
}

Response example

{
  "result":"Success/Failed",
  "status": "APPROVED | DECLINED | CHALLENGE | SUBMITTED | CAPTUREREQUIRED",
  "orderSessionKey": "{{$guid}}", //FlexFactor unique transaction identifier
  "senseKey": "value that was present in evaluate request", //optional
}

How to use the Optimization Rank column

Start with the Required rows. Every field marked 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. Fields marked Required if parent object included only apply when you include the parent object — but when the parent is sent, those children become required.
Then add the Critical fields. Two fields are formally Critical: paymentMethod.verificationValue (CVV) for CIT and subscription.schemeTransactionId for MIT. Populate these on every applicable request.
Then High, then Medium. The transaction decline context (responseCode, responseCodeSource, processorName), the full deviceDetails block, and the root attemptCount (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 are required and should 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.