Guides

Payload examples

Minimum (required fields only) and optimal (all fields) /evaluate request payloads for both CIT and MIT flows.


Four ready-to-adapt request payloads for /evaluate: a minimum payload with only the fields FlexFactor needs to evaluate an order, and an optimal payload with all applicable fields, for both Customer-Initiated (CIT) and Merchant-Initiated (MIT) transactions. The API schema does not enforce any of these fields, so the reference panel shows them as optional; the minimum payload is the smallest request FlexFactor can act on. Field-by-field definitions and Optimization Ranks live on the /evaluate page.

Notes that apply throughout:

  • All values are illustrative placeholders (sandbox-style tokens, example addresses).
  • payer.paymentMethods is not shown — it only applies to Customer Wallet integrations.
  • sequenceNumber is not shown — it applies to SFTP batch requests only.
  • transaction.amount and subscription.price are in cents.
  • idempotencyKey is optional but recommended: send a unique GUID/UUID per request and reuse it on retries.
  • cardNumber carries the token returned by /tokenize ("token": true). If sending raw PAN instead, token must be set to false.

Minimum payload — CIT (required fields only)

Root fields FlexFactor needs: isDeclined, mid, orderId, isMIT, plus the four objects it needs (transaction, payer, billingInformation, paymentMethod). idempotencyKey is included because we recommend it on every request.

  • billingInformation.state is included because this example is a US card; it can be omitted for non-US cards.
  • transactionType (root) omitted — only needed for Auth + Capture configurations.
  • siteId/siteUrl omitted — only needed for Site assignment when multiple sites/descriptors exist per MID.
  • customerIp is not part of the minimum payload but is ranked Critical for CIT — see the optimal payload.
  • transaction.timezoneUtcOffset omitted — it is optional.
  • The transaction decline-context fields (responseCode, responseCodeSource, cardNotPresent) are part of the minimum payload — populate them from the original decline response.
  • transaction.avsResultCode, cvvResultCode, and cavvResultCode omitted — they are optional, but avsResultCode and cvvResultCode are ranked High; see the optimal payload.
{
  "isDeclined": true,
  "isMIT": false,
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ORDER-100045",
  "idempotencyKey": "6f1c2b4e-8d3a-4f5b-9c7e-2a1d0e9f8b76",
  "transaction": {
    "id": "3478613",
    "amount": 15000,
    "currency": "USD",
    "timestampUtc": "2026-06-12T14:30:00Z",
    "responseCode": "203",
    "responseCodeSource": "NMI",
    "cardNotPresent": true
  },
  "payer": {
    "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": {
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t",
    "expirationYear": 2028,
    "expirationMonth": 12,
    "holderName": "John Doe",
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111"
  }
}

Minimum payload — MIT (required fields only)

Everything in the CIT minimum, plus isMIT: true, isRecurring: true, and the subscription object. FlexFactor needs the subscription object when both isMIT and isRecurring are true. Within it, FlexFactor needs subscriptionId, interval, price, and currency; schemeTransactionId, schemeBrand, intervalCount (default 1), paymentNumber, and totalPayments are optional.

  • expiryDateUtc omitted — it is optional on every MIT configuration. When omitted, the default expiry configured for the merchant in FlexFactor applies. Add it (within the merchant retry window, max 21 days) to set a window for a specific order.
  • subscription.schemeTransactionId is not part of the minimum payload but is ranked Critical for MIT and card-on-file — see the optimal payload.
{
  "isDeclined": true,
  "isMIT": true,
  "isRecurring": true,
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ORDER-100046",
  "idempotencyKey": "9b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c65",
  "subscription": {
    "subscriptionId": "sub_123456",
    "price": 2599,
    "currency": "USD",
    "interval": "monthly"
  },
  "transaction": {
    "id": "3478614",
    "amount": 2599,
    "currency": "USD",
    "timestampUtc": "2026-06-12T14:30:00Z",
    "responseCode": "204",
    "responseCodeSource": "NMI",
    "cardNotPresent": true
  },
  "payer": {
    "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": {
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t",
    "expirationYear": 2028,
    "expirationMonth": 12,
    "holderName": "John Doe",
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111"
  }
}

Optimal payload — CIT (all applicable fields)

Includes every field from the /evaluate request tables that applies to CIT. Highlights per the Optimization Rank column:

  • Critical: customerIp (cardholder browser/device IP, never the merchant server IP) and paymentMethod.verificationValue (CVV).
  • High: attemptNumber, the optional decline context (processorName, responseDescription, responseStatus, avsResultCode, cvvResultCode), the full deviceDetails block, and merchant. (responseCode, responseCodeSource, and cardNotPresent are part of the minimum payloads.)
  • threeDsecure is not included — it applies to the MIT additional parameters only.
  • orderItems and additionalFields are arrays — one example element each.
{
  "isDeclined": true,
  "isMIT": false,
  "transactionType": "PURCHASE",
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ORDER-100047",
  "idempotencyKey": "3c2d1e0f-9a8b-4c7d-6e5f-4a3b2c1d0e98",
  "siteId": "site_98765",
  "siteUrl": "https://shop.example.com",
  "customerIp": "203.0.113.42",
  "orderSource": "ecommerce",
  "attemptNumber": 2,
  "transaction": {
    "id": "3478615",
    "amount": 15000,
    "currency": "USD",
    "dynamicDescriptor": "MyShoesStore",
    "timestampUtc": "2026-06-12T14:30:00Z",
    "timezoneUtcOffset": -8,
    "transactionType": "Purchase",
    "responseCode": "203",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "responseSubStatus": "SoftDecline",
    "responseCodeSource": "NMI",
    "processorName": "Acme Payments",
    "avsResultCode": "M",
    "cvvResultCode": "M",
    "cavvResultCode": "2",
    "cardNotPresent": true
  },
  "payer": {
    "email": "[email protected]",
    "phone": "+1 555-123-4567",
    "id": "customer123",
    "birthdate": "1990-01-01"
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "addressLine2": "Apt 4B",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "paymentMethod": {
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t",
    "expirationYear": 2028,
    "expirationMonth": 12,
    "verificationValue": "123",
    "holderName": "John Doe",
    "token": true,
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardIssuer": "Acme Bank",
    "cardLevel": "CLASSIC",
    "cardFingerprint": "abcd1234",
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111"
  },
  "shippingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "addressLine2": "Apt 4B",
    "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": 5651,
    "country": "US"
  },
  "affiliate": {
    "id": "aff_123123123",
    "name": "Affiliate 1"
  },
  "orderItems": [
    {
      "sku": "SKU123",
      "name": "Running Shoes",
      "description": "Lightweight running shoes, size 10",
      "amount": 15000,
      "discountAmount": 1000,
      "tax": 1200,
      "discountType": "fixed",
      "quantity": 1
    }
  ],
  "additionalFields": [
    {
      "key": "checkoutVersion",
      "value": "v3.2-onepage"
    }
  ]
}

Optimal payload — MIT (all applicable fields)

Everything CIT-applicable plus the MIT additional parameters: isRecurring, expiryDateUtc, the full subscription object, and threeDsecure.

  • Critical: subscription.schemeTransactionId (network transaction ID / NTI — the single highest-leverage field for MIT and card-on-file rescue).
  • paymentMethod.verificationValue is omitted — CVV is a CIT signal and is not stored for recurring billing.
  • customerIp is omitted — there is no cardholder browser session on a merchant-initiated transaction. Same reasoning excludes deviceDetails; include them only if you captured them at original signup and your FlexFactor contact advises sending them.
  • expiryDateUtc, when sent, is the merchant retry window (max 21 days from the decline). It is optional; omit it to use the merchant default expiry.
  • Send the MIT the same day it declines, and do not retry it yourself before expiryDateUtc.
{
  "isDeclined": true,
  "isMIT": true,
  "isRecurring": true,
  "expiryDateUtc": "2026-06-26T14:30:00Z",
  "transactionType": "PURCHASE",
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ORDER-100048",
  "idempotencyKey": "7e6f5a4b-3c2d-4e1f-0a9b-8c7d6e5f4a32",
  "siteId": "site_98765",
  "siteUrl": "https://shop.example.com",
  "orderSource": "ecommerce",
  "attemptNumber": 3,
  "subscription": {
    "subscriptionId": "sub_123456",
    "price": 2599,
    "currency": "USD",
    "interval": "monthly",
    "intervalCount": 1,
    "schemeTransactionId": "987654321234567",
    "schemeBrand": "Visa",
    "paymentNumber": "4",
    "totalPayments": "12"
  },
  "threeDsecure": {
    "threeDsVersion": "2.2.0",
    "ecommerceIndicator": "02",
    "authenticationValue": "abcdefg12345",
    "directoryServerTransactionId": "ds_987654",
    "xid": "xid_246810",
    "authenticationValueAlgorithm": "SHA-256",
    "directoryResponseStatus": "Y",
    "authenticationResponseStatus": "Y",
    "enrolled": "Y"
  },
  "transaction": {
    "id": "3478616",
    "amount": 2599,
    "currency": "USD",
    "dynamicDescriptor": "MyShoesStore",
    "timestampUtc": "2026-06-12T14:30:00Z",
    "timezoneUtcOffset": -8,
    "transactionType": "Purchase",
    "responseCode": "204",
    "responseDescription": "Insufficient funds",
    "responseStatus": "DECLINED",
    "responseSubStatus": "SoftDecline",
    "responseCodeSource": "NMI",
    "processorName": "Acme Payments",
    "avsResultCode": "M",
    "cvvResultCode": "NA",
    "cavvResultCode": "2",
    "cardNotPresent": true
  },
  "payer": {
    "email": "[email protected]",
    "phone": "+1 555-123-4567",
    "id": "customer123",
    "birthdate": "1990-01-01"
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "addressLine2": "Apt 4B",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "paymentMethod": {
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t",
    "expirationYear": 2028,
    "expirationMonth": 12,
    "holderName": "John Doe",
    "token": true,
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardIssuer": "Acme Bank",
    "cardLevel": "CLASSIC",
    "cardFingerprint": "abcd1234",
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111"
  },
  "shippingInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "addressLine2": "Apt 4B",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "merchant": {
    "id": "merchant123",
    "name": "Acme Inc.",
    "mcc": 5651,
    "country": "US"
  },
  "affiliate": {
    "id": "aff_123123123",
    "name": "Affiliate 1"
  },
  "orderItems": [
    {
      "sku": "SKU123",
      "name": "Monthly Subscription",
      "description": "Monthly membership plan",
      "amount": 2599,
      "discountAmount": 0,
      "tax": 200,
      "discountType": "fixed",
      "quantity": 1
    }
  ],
  "additionalFields": [
    {
      "key": "billingPlatform",
      "value": "internal-subscriptions-v2"
    }
  ]
}

Updated 7 days ago

What’s Next

Did this page help you?