/transmit

On successful transactions, queue POST /transmit.


❗️

Prerequisites to invoke this API:

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 the 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

isDeclinedboolrequired
orderIdstringrequiredYour internal order ID.
orderSourcestringoptionalSource of the order
E.g.: ecommerce, installment, etc.
sequenceNumberstringrequired
for batch via SFTP
Numerical position of that transaction within the batch.
Starting from 1.
isMITboolrequiredtrue for merchant-initiated transactions.
When true, requires specific MIT fields.
transactionobjectrequiredSee transaction fields below.
payerobjectrequiredSee payer fields below.
paymentMethodobjectrequiredSee paymentMethod fields below.
billingInformationobjectoptionalSee billingInformation fields below.
shippingInformationobjectoptionalSee shippingInformation fields below.
merchantobjectrequired
for partners
See merchant fields below
deviceDetailsobjectoptionalSee deviceDetails fields below
midstringrequired
for partners
Your FlexFactor Merchant Identification Number. Get your Mid
orderItemsobject arrayoptionalSee orderItems fields below.
additionalFieldsobject arrayoptionalSee additionalFields fields below.

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


Additional parameters for MIT

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

isMITboolrequiredtrue for merchant-initiated transactions.
When true, requires specific MIT fields below.
isRecurringboolrequired
for MIT
true for subscriptions.
siteUrlstringrequired
for MIT
Website linked to the descriptor of the subscription.
subscriptionobjectrequired
for MIT
See subscription fields below.
threeDSecureobjectrequired
for MIT
See 3DSecure fields below.

Detailed object parameters:

transaction

Required object

idstringrequiredExternal transaction identifier in the format of a GUID
timestampUtcdatetimerequiredDate and time of the transaction.
timezoneUtcOffsetintegerrequiredUTC offset of the timezone.
transactionTypestringoptionalE.g.: 'Auth', 'Capture', 'Void'
amountintegerrequiredAmount of the transaction in cents.
E.g. $19.99 -> '1999'
currencystringrequiredISO 4217 currency code.
responseCodestringrequiredResponse code received from the gateway.
responseDescriptionstringoptionalDescription of the response.
responseStatusstringoptionalE.g.: Approved, Declined, Voided, Refunded, Chargeback, etc.
responseSubStatusstringoptionalSub-status of the response.
responseCodeSourcestringrequired
(*)
This is the source of the code from the original transaction
E.g.: "nmi", "Paypal"
processorNamestringoptionalName of the processor.
avsResultCodestringrequiredAddress Verification Service result code.
cvvResultCodestringrequiredCard Verification Value result code.
cavvResultCodestringrequired
(*)
Cardholder Authentication Verification Value result code.
cardNotPresentboolrequiredIndicates if the card was present during the transaction.

(*) If this value cannot be provided, send 'NA'

payer

Required object

emailstringrequired
phonestringoptional
idstringoptionalExternal ID
birthdatedatetimeoptional

billingInformation

Optional object.

firstNamestringrequired
if this object is provided
lastNamestringrequired
if this object is provided
phonestringoptional
countrystringrequired
if this object is provided
countryCodestringrequired
if this object is provided
ISO 3166-1 alpha-2 country code (2-letter)
addressLine1stringrequired
if this object is provided
addressLine2stringoptional
statestringoptional2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
citystringrequired
if this object is provided
zipCodestringrequired
if this object is provided
5 or 9 digits

paymentMethod

Required object.

holderNamestringrequired
cardTypestringrequiredE.g.: Credit, Debit, Prepaid Card
cardBrandstringrequiredE.g.: VISA, Mastercard, AMEX, etc.
cardCountrystringrequiredISO 3166-1 alpha-2 country code (2-letter)
cardIssuerstringoptional
cardLevelstringoptional
cardFingerprintstringoptional
expirationMonthintegerrequired
expirationYearintegerrequired
cardBinNumberstringrequired6 character string.
cardLast4Digitsstringrequired4 character string.

merchant

Required object for partners only.

idstringrequired
if this object is provided
External ID
namestringoptional
mccintegerrequired
if this object is provided
Merchant Category Codes used to identify the type of business in which a merchant is engaged.
countrystringrequired
if this object is provided

deviceDetails

Optional object.

deviceTypestringrequired
if this object is provided
Type of device used for that transaction (e.g., 'mobile', 'laptop', 'tablet')
deviceNamestringrequired
if this object is provided
Name of the device (e.g., 'iPhone 12', 'Samsung Galaxy S21')
deviceOSstringrequired
if this object is provided
Operating system of the device (e.g., 'iOS 14', 'Android 11')
browserstringrequired
if this object is provided
Name of the browser (e.g., 'Chrome', 'Safari')
userAgentstringrequired
if this object is provided
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 and isRecurring are true.

subscriptionIdstringrequired
if this object is provided
schemeTransactionIdstringrequired
if this object is provided
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).
schemeBrandstringrequired
if this object is provided
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
intervalstringrequired
if this object is provided
E.g.: 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
priceintrequired
if this object is provided
Amount in cents
currencystringrequired
if this object is provided
paymentNumberintegeroptional
totalPaymentsintegeroptional

threeDSecure

Required object when isMIT and isRecurring are true.

threeDsVersionstringoptionalProtocol version for the card payment authentication.
E.g.: '1.0.2' '2.1.0' '2.2.0'
ecommerceIndicatorstringrequired
if this object is provided
The indication of an online commerce transaction.
authenticationValuestringrequired
if this object is provided
The encrypted code from the cardholder's bank.
directoryServerTransactionIdstringrequired
if this object is provided
The unique ID for the transaction with the bank.
xidstringoptionalTransaction identifier generated by the 3D Secure system.
authenticationValueAlgorithmstringoptionalThe encryption algorithm used to secure the payment.
E.g.: SHA-256
directoryResponseStatusstringoptionalThe response status code from the bank's directory.
E.g.: 'Y'
authenticationResponseStatusstringoptionalThe response status code for the payment authentication.
E.g.: 'Y'
enrolledstringoptionalThe card's enrollment status in 3D Secure.
E.g.: 'Y'

orderItems

Optional object.

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.
quantitystringoptionalThe quantity of this item.

shippingInformation

Optional object.

firstNamestringrequired
if this object is provided
lastNamestringrequired
if this object is provided
phonestringoptional
countrystringrequired
if this object is provided
countryCodestringrequired
if this object is provided
ISO 3166-1 alpha-2 country code (2-letter)
addressLine1stringrequired
if this object is provided
addressLine2stringoptional
statestringoptional2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
citystringrequired
if this object is provided
zipCodestringrequired
if this object is provided
5 or 9 digits

additionalFields

Optional array of object.

keystringoptionalDescription of the additional information.
valuestringoptionalContent of the additional information.

Response

Once transmitted, our API will respond with a transaction key.
This key can be used to update the order object, for example with its outcome.

transmitIdResponse transaction key.



Payload examples

Request example


curl --request POST \
     --url https://api-sandbox.flex-charge.com/v1/transmit \
     --header 'Authorization: abc123def456' \ //replace with bearer returned by oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
{
  "transaction": {
    "id": "3478613",
    "timestampUtc": "0001-01-01T00:00:00Z",
    "timezoneUtcOffset": 0,
    "amount": 19975,
    "currency": "USD",
    "responseCode": "203",
    "avsResultCode": "M",
    "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": 2028,
    "expirationYear": 12,
    "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.flex-charge.com/v1/evaluate \
     --header 'Authorization: abc123def456' \ //replace with bearer returned by oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
{

	"isMIT": true,
	"isRecurring": true,
	"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,
    "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": 2028,
    "expirationYear": 12,
    "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": "123456789-987654321", //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": 2028,
        "expirationYear": 12,
        "cardBinNumber": "123456",
        "cardLast4Digits": "7890"
      },
      "billingInformation": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1 555-987-6543",
        "country": "United States",
        "countryCode": "US",
        "addressLine1": "456 Oak St.",
        "city": "NY",
        "zipcode": "10001"
      },
      "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."
      },
      "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


{ 
    "result" : "success",
    "error":{},
    "transmitId":"{{$guid}}"
}

What’s Next