Transmit

Send completed transaction data to FlexFactor


* Request
* Response
* Payload examples


❗️ Prerequisites to invoke this API:
* Authenticate and send the bearer token for this call.

FlexFactor will build your custom risk model based on your successful transactions. POST /transmit doesn't require an answer, so this 'fire and forget' call doesn't add latency to your transaction.


You can alternatively send us copies of your transactions through a daily batch. Please note that copies of transactions must be sent within 24 hours maximum.

❕ When using SFTP batches:

* Each Merchant account will have unique SFTP credentials.
* SFTP keys will be available within your merchant portal.
* Limit each SFTP file to 2000 records or less.
* file name must contain the prefix transmit_ to be picked up



Request parameters

The API validation column shows only what the API schema enforces when it validates the request. On /transmit the schema enforces no field, so every row reads optional. The object descriptions and the Notes column say which fields FlexFactor needs to build your risk model.

Property NameTypeAPI validationNotes
isDeclinedbooloptionaltrue when the transaction was declined, false when it was approved.
orderIdstringoptionalYour internal order ID.
orderSourcestringoptionalSource of the order. Allowed values: ecommerce, terminal, vterminal. Defaults to ecommerce.
sequenceNumberstringoptionalFlexFactor needs it for SFTP batch. Numerical position of that transaction within the batch. Starting from 1.
customerIpstringoptionalThe customer's IP as captured on the checkout page. Must be the end-user / cardholder browser IP, not the merchant server IP.
isMITbooloptionaltrue for merchant-initiated transactions. When true, FlexFactor needs the MIT fields.
transactionobjectoptionalSee transaction fields below.
payerobjectoptionalSee payer fields below.
paymentMethodobjectoptionalSee paymentMethod fields below.
billingInformationobjectoptionalSee billingInformation fields below.
shippingInformationobjectoptionalSee shippingInformation fields below.
merchantobjectoptionalRecommended for partner/gateway calls. See merchant fields below
deviceDetailsobjectoptionalSee deviceDetails fields below
midstringoptionalFlexFactor needs it for partner integrations. Your FlexFactor Merchant Identification Number. Get your Mid
orderItemsobject arrayoptionalSee orderItems fields below.
additionalFieldsobject arrayoptionalSee additionalFields fields below.
userDefinedFieldsobject arrayoptionalArray of key/value objects with the same shape as additionalFields.
extraDatastringoptionalOpen-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 /transmit 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 NameTypeAPI validationNotes
isMITbooloptionaltrue for merchant-initiated transactions. When true, FlexFactor needs the MIT fields below.
isRecurringbooloptionalFlexFactor needs it for MIT. true for subscriptions.
siteUrlstringoptionalFlexFactor needs it for MIT. Website linked to the descriptor of the subscription.
subscriptionobjectoptionalFlexFactor needs it for MIT. See subscription fields below.

Detailed object parameters:

transaction

Object FlexFactor needs for every transmit.

Property NameTypeAPI validationNotes
idstringoptionalExternal transaction identifier in the format of a GUID
timestampUtcdatetimeoptionalDate and time of the transaction.
timezoneUtcOffsetintegeroptionalUTC offset of the timezone. Optional; you can omit it.
transactionTypestringoptionalE.g.: 'Auth', 'Capture', 'Void'
amountintegeroptionalAmount of the transaction in cents. E.g. $19.99 -> '1999'
currencystringoptionalISO 4217 currency code.
responseCodestringoptionalResponse code received from the gateway.
responseDescriptionstringoptionalDescription of the response.
responseStatusstringoptionalE.g.: Approved, Declined, Voided, Refunded, Chargeback, etc.
responseSubStatusstringoptionalSub-status of the response.
responseCodeSourcestringoptionalThis is the source of the code from the original transaction E.g.: "nmi", "Paypal". If this value cannot be provided, send null.
processorNamestringoptionalName of the processor.
avsResultCodestringoptionalAddress Verification Service result code.
cvvResultCodestringoptionalCard Verification Value result code.
cavvResultCodestringoptionalCardholder Authentication Verification Value result code.
cardNotPresentbooloptionalIndicates if the card was present during the transaction.

payer

Object FlexFactor needs for every transmit.

Property NameTypeAPI validationNotes
emailstringoptional
phonestringoptional
idstringoptionalExternal ID
birthdatedatetimeoptional

billingInformation

Optional object.

Property NameTypeAPI validationNotes
firstNamestringoptionalFlexFactor needs it when you send this object.
lastNamestringoptionalFlexFactor needs it when you send this object.
fullNamestringoptionalFull name of the cardholder.
phonestringoptional
countrystringoptionalFlexFactor needs it when you send this object.
countryCodestringoptionalFlexFactor needs it when you send this object. ISO 3166-1 alpha-2 country code (2-letter)
addressLine1stringoptionalFlexFactor needs it when you send this object.
addressLine2stringoptional
statestringoptional2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
citystringoptionalFlexFactor needs it when you send this object.
zipcodestringoptionalFlexFactor needs it when you send this object. 5 or 9 digits

paymentMethod

Object FlexFactor needs for every transmit.

Property NameTypeAPI validationNotes
holderNamestringoptional
cardTypestringoptionalE.g.: Credit, Debit, Prepaid Card
cardBrandstringoptionalE.g.: VISA, Mastercard
cardCountrystringoptionalISO 3166-1 alpha-2 country code (2-letter)
cardIssuerstringoptional
cardLevelstringoptional
cardFingerprintstringoptional
expirationMonthintegeroptional
expirationYearintegeroptional
cardBinNumberstringoptional6 character string.
cardLast4Digitsstringoptional4 character string.
tokenbooleanoptionalIndicates whether the payment method is a FlexFactor token.

merchant

Optional object. Recommended for partner/gateway calls.

Property NameTypeAPI validationNotes
idstringoptionalFlexFactor needs it when you send this object. External ID
namestringoptional
mccintegeroptionalFlexFactor needs it when you send this object. Merchant Category Codes used to identify the type of business in which a merchant is engaged.
countrystringoptionalFlexFactor needs it when you send this object.

deviceDetails

Optional object.

Property NameTypeAPI validationNotes
deviceTypestringoptionalFlexFactor needs it when you send this object. Type of device used for that transaction (e.g., 'mobile', 'laptop', 'tablet')
deviceNamestringoptionalFlexFactor needs it when you send this object. Name of the device (e.g., 'iPhone 12', 'Samsung Galaxy S21')
deviceOSstringoptionalFlexFactor needs it when you send this object. Operating system of the device (e.g., 'iOS 14', 'Android 11')
browserstringoptionalFlexFactor needs it when you send this object. Name of the browser (e.g., 'Chrome', 'Safari')
userAgentstringoptionalFlexFactor needs it when you send this object. User agent string (a detailed string provided by the browser that identifies the browser, its version, and the operating system)

subscription

Required object when*isMIT** andisRecurring are true.*

Property NameTypeAPI validationNotes
subscriptionIdstringoptionalFlexFactor needs it when you send this object.
schemeTransactionIdstringoptionalFlexFactor needs it when you send this object. Unique reference of the transaction returned by authorisation server of the issuer. Allows to chain a MIT (Merchant Initiated Transaction) to a initial CIT (Customer Initiated Transaction).
schemeBrandstringoptionalFlexFactor needs it when you send this object. Card/scheme brand associated with the subscription. Will generally be similar to the cardBrand value in most cases, but might be different in some edge cases. E.g.: Visa
intervalstringoptionalFlexFactor needs it when you send this object. E.g.: 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
priceintoptionalFlexFactor needs it when you send this object. Amount in cents
currencystringoptionalFlexFactor needs it when you send this object.
paymentNumberstringoptional
totalPaymentsstringoptional

orderItems

Optional object.

Property NameTypeAPI validationNotes
skustringoptionalThe SKU of the item.
namestringoptionalThe name of the item.
descriptionstringoptionalThe description of the item.
amountintegeroptionalThe amount of the item.
discountAmountintegeroptionalThe discount amount on the item.
taxintegeroptionalThe tax on the item.
discountTypestringoptionalThe discount type on the item.
quantityintegeroptionalThe quantity of this item.

shippingInformation

Optional object.

Property NameTypeAPI validationNotes
firstNamestringoptionalFlexFactor needs it when you send this object.
lastNamestringoptionalFlexFactor needs it when you send this object.
fullNamestringoptionalFull name of the recipient.
phonestringoptional
countrystringoptionalFlexFactor needs it when you send this object.
countryCodestringoptionalFlexFactor needs it when you send this object. ISO 3166-1 alpha-2 country code (2-letter)
addressLine1stringoptionalFlexFactor needs it when you send this object.
addressLine2stringoptional
statestringoptional2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
citystringoptionalFlexFactor needs it when you send this object.
zipcodestringoptionalFlexFactor needs it when you send this object. 5 or 9 digits

additionalFields

Optional array of object.

Property NameTypeAPI validationNotes
keystringoptionalDescription of the additional information.
valuestringoptionalContent of the additional information.

Response

Once transmitted, our API responds with the common FlexFactor envelope plus a transmitId. You can use that key to update the order object later, for example with its outcome. The envelope is defined in Workflows §3.5.

successbooleantrue when errors is empty.
resultstringNot populated on this endpoint; null.
statusstringNot populated on this endpoint; null.
statusCodestringNot populated on this endpoint; null. It is not the HTTP status code.
errorsarray of objectsError details; empty on success. Each item is serialized positionally: item1 message, item2 key, item3 error code, item4 friendly flag (boolean).
customPropertiesobjectOptional. Additional properties.
transmitIdguid/uuidResponse transaction key.


HTTP status codes

SituationHTTPBody
The copy was recorded200Envelope with success: true and transmitId
Invalid or expired bearer token401—
Not found404Problem details
An internal error occurred500—

Payload examples

Request example


curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/transmit \
     --header 'Authorization: Bearer abc123def456' \ //replace with bearer returned by oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "isDeclined": true,
  "isMIT": false,
  "transaction": {
    "id": "3478613",
    "timestampUtc": "0001-01-01T00:00:00Z",
    "timezoneUtcOffset": 0,
    "amount": 19975,
    "currency": "USD",
    "responseCode": "203",
    "avsResultCode": "M",
    "cardNotPresent": true,
    "processorName": "Acme Payments",
    "cavvResultCode": "2",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "transactionType": "CAPTURE"
  },
  "payer": {
    "id": "customer123",
    "email": "[email protected]",
    "phone": "+1 555-123-4567",
    "birthdate": "1990-01-01"
  },
  "orderItems": [
    {
      "sku": "SKU123",
      "name": "Product 1",
      "description": "Description of Product 1",
      "amount": 20000,
      "discountAmount": 0,
      "tax": 100,
      "quantity": 2
    },
    {
      "sku": "SKU456",
      "name": "Product 2",
      "description": "Description of Product 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."
  },
  "deviceDetails": {
    "deviceType": "mobile",
    "deviceName": "iPhone 12",
    "deviceOS": "iOS 14",
    "browser": "Safari",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1"
  },
  "paymentMethod": {
    "holderName": "John Doe",
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "United States",
    "cardIssuer": "Acme Bank",
    "cardFingerprint": "abcd1234",
    "expirationMonth": 12,
    "expirationYear": 2028,
    "cardBinNumber": "123456",
    "cardLast4Digits": "7890"
  },
  "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"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511"
}
'
curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/transmit \
     --header 'Authorization: Bearer abc123def456' \ //replace with bearer returned by oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{

	"isMIT": true,
	"isRecurring": true,
	"siteUrl": "https://www.example-store.com",
	"subscription": {
		"subscriptionId": "sub_123456",
		"schemeTransactionId": "txn_789012",
		"schemeBrand": "Visa",
		"interval": "Monthly",
		"price": 2599,
		"currency": "USD",
		"paymentNumber": "2",
		"totalPayments": "12"
	}, 
  "transaction": {
    "id": "3478613",
    "timestampUtc": "0001-01-01T00:00:00Z",
    "timezoneUtcOffset": 0,
    "amount": 19975,
    "currency": "USD",
    "responseCode": "203",
    "avsResultCode": "M",
    "cvvResultCode": "NA",
    "processorName": "Acme Payments",
    "cavvResultCode": "2",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "transactionType": "CAPTURE"
  },
  "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"
  },
  "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"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511"
}
'
//file name: 'transmit_{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
  "requests": [
    {
      //first transaction copy: approved MIT
      "sequenceNumber": 1, // The numerical position of the transaction within the batch.
      "IsDeclined": false,
      "OrderId": "123456789", //must be unique even for test calls
      "OrderSource": null,
      "IsMIT": true,
      "IsRecurring": true,
      "SiteUrl": "https://example.com", //Website linked to the descriptor of the subscription.
      "Transaction": {
        "Id": "6463077f894b1f71280001eb",
        "TimestampUtc": "2023-01-01T00:00:00Z",
        "TimezoneUtcOffset": 0,
        "TransactionType": null,
        "Amount": 10000, //in cents
        "Currency": "USD",
        "ResponseCode": "100",
        "AvsResultCode": "Y",
        "CvvResultCode": "M",
        "ProcessorName": null,
        "CardNotPresent": true,
        "CavvResultCode": "NA",
        "ResponseStatus": "APPROVED",
        "ResponseSubStatus": null,
        "ResponseCodeSource": "NMI",
        "ResponseDescription": null
      },
      "Payer": {
        "Id": "6463077d894b1f71280001e6",
        "Email": "[email protected]",
        "Phone": null,
        "Birthdate": null
      },
      "Subscription": {
        "Price": 5000, //in cents
        "Currency": "USD",
        "Interval": "30",
        "SchemeBrand": "Visa",
        "PaymentNumber": null,
        "TotalPayments": null,
        "SubscriptionId": "123456789",
        "SchemeTransactionId": "6463077f894b1f71280001eb" //Unique reference of the transaction returned by authorization server of the issuer. 
      },
      "PaymentMethod": {
        "HolderName": "John Doe",
        "CardType": "CREDIT",
        "CardBrand": "VISA",
        "CardLevel": null,
        "CardIssuer": null,
        "CardCountry": "US",
        "CardBinNumber": "123456",
        "ExpirationYear": 2025,
        "CardFingerprint": null,
        "CardLast4Digits": "7890",
        "ExpirationMonth": 12
      },
      "BillingInformation": {
        "City": "New York",
        "Phone": null,
        "State": null,
        "Country": "US",
        "zipcode": "12345",
        "LastName": "Doe",
        "FirstName": "John",
        "CountryCode": "US",
        "AddressLine1": "123 Main Street",
        "AddressLine2": null
      },
      "ShippingInformation": null,
      "merchant": {
        "country": "US",
        "mcc": 5678,
        "id": "merchant456",
        "name": "XYZ Inc."
      },
      "OrderItems": null,
      "AdditionalFields": null
    },
    
    {
      //second transaction copy: declined CIT
      "sequenceNumber": 2, // The numerical position of the transaction within the batch.
      "IsDeclined": true,
      "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09512", //must be unique even for test calls
      "OrderSource": null,
      "isMIT": false,
      "SiteUrl": "https://example.com",
      "transaction": {
        "id": "1234567",
        "timestampUtc": "0001-01-01T00:00:00Z",
        "timezoneUtcOffset": 0,
        "amount": 14999, //in cents
        "currency": "USD",
        "responseCode": "204",
        "avsResultCode": "N",
        "cvvResultCode": "M",
        "processorName": "XYZ Payments",
        "cavvResultCode": "1",
        "responseCodeSource": "ABC Payments",
        "responseDescription": "Insufficient funds",
        "responseStatus": "DECLINED",
        "transactionType": "AUTHORIZE"
      },
      "payer": {
        "id": "customer456",
        "email": "[email protected]",
        "phone": "+1 555-987-6543",
        "birthdate": "1985-05-05"
      },
      "paymentMethod": {
        "holderName": "Jane Doe",
        "cardType": "CREDIT",
        "cardBrand": "MASTERCARD",
        "cardCountry": "United States",
        "cardIssuer": "XYZ Bank",
        "cardFingerprint": "efgh5678",
        "expirationMonth": 12,
        "expirationYear": 2028,
        "cardBinNumber": "123456",
        "cardLast4Digits": "7890"
      },
      "billingInformation": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1 555-987-6543",
        "country": "United States",
        "countryCode": "US",
        "addressLine1": "456 Oak St.",
        "city": "New York",
        "zipcode": "10001"
      },
      "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."
      },
      "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
        }
      ],
      "AdditionalFields": null
    }
  ]
}


Response example


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

{
  "success": true,
  "result": null,
  "status": null,
  "statusCode": null,
  "errors": [],
  "customProperties": {},
  "transmitId": "{{$guid}}"
}


Did this page help you?