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


`isDeclined`	bool	required
`orderId`	string	required	Your internal order ID.
`orderSource`	string	optional	Source of the order E.g.: ecommerce, installment, etc.
`sequenceNumber`	string	required for batch via SFTP	Numerical position of that transaction within the batch. Starting from 1.
`isMIT`	bool	required	`true` for merchant-initiated transactions. When `true`, requires specific MIT fields.
`transaction`	object	required	See transaction fields below.
`payer`	object	required	See payer fields below.
`paymentMethod`	object	required	See paymentMethod fields below.
`billingInformation`	object	optional	See billingInformation fields below.
`shippingInformation`	object	optional	See shippingInformation fields below.
`merchant`	object	required for partners	See merchant fields below
`deviceDetails`	object	optional	See deviceDetails fields below
`mid`	string	required for partners	Your FlexFactor Merchant Identification Number. Get your Mid
`orderItems`	object array	optional	See orderItems fields below.
`additionalFields`	object array	optional	See 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:


`isMIT`	bool	required	`true` for merchant-initiated transactions. When `true`, requires specific MIT fields below.
`isRecurring`	bool	required for MIT	`true` for subscriptions.
`siteUrl`	string	required for MIT	Website linked to the descriptor of the subscription.
`subscription`	object	required for MIT	See subscription fields below.
`threeDSecure`	object	required for MIT	See 3DSecure fields below.

Detailed object parameters:

transaction

Required object


`id`	string	required	External transaction identifier in the format of a GUID
`timestampUtc`	datetime	required	Date and time of the transaction.
`timezoneUtcOffset`	integer	required	UTC offset of the timezone.
`transactionType`	string	optional	E.g.: 'Auth', 'Capture', 'Void'
`amount`	integer	required	Amount of the transaction in cents. E.g. $19.99 -> '1999'
`currency`	string	required	ISO 4217 currency code.
`responseCode`	string	required	Response code received from the gateway.
`responseDescription`	string	optional	Description of the response.
`responseStatus`	string	optional	E.g.: Approved, Declined, Voided, Refunded, Chargeback, etc.
`responseSubStatus`	string	optional	Sub-status of the response.
`responseCodeSource`	string	required (*)	This is the source of the code from the original transaction E.g.: "nmi", "Paypal"
`processorName`	string	optional	Name of the processor.
`avsResultCode`	string	required	Address Verification Service result code.
`cvvResultCode`	string	required	Card Verification Value result code.
`cavvResultCode`	string	required (*)	Cardholder Authentication Verification Value result code.
`cardNotPresent`	bool	required	Indicates if the card was present during the transaction.

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

payer

Required object


`email`	string	required
`phone`	string	optional
`id`	string	optional	External ID
`birthdate`	datetime	optional

billingInformation

Optional object.


`firstName`	string	required if this object is provided
`lastName`	string	required if this object is provided
`phone`	string	optional
`country`	string	required if this object is provided
`countryCode`	string	required if this object is provided	ISO 3166-1 alpha-2 country code (2-letter)
`addressLine1`	string	required if this object is provided
`addressLine2`	string	optional
`state`	string	optional	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
`zipCode`	string	required if this object is provided	5 or 9 digits

paymentMethod

Required object.


`holderName`	string	required
`cardType`	string	required	E.g.: Credit, Debit, Prepaid Card
`cardBrand`	string	required	E.g.: VISA, Mastercard, AMEX, etc.
`cardCountry`	string	required	ISO 3166-1 alpha-2 country code (2-letter)
`cardIssuer`	string	optional
`cardLevel`	string	optional
`cardFingerprint`	string	optional
`expirationMonth`	integer	required
`expirationYear`	integer	required
`cardBinNumber`	string	required	6 character string.
`cardLast4Digits`	string	required	4 character string.

merchant

Required object for partners only.


`id`	string	required if this object is provided	External ID
`name`	string	optional
`mcc`	integer	required if this object is provided	Merchant Category Codes used to identify the type of business in which a merchant is engaged.
`country`	string	required if this object is provided

deviceDetails

Optional object.


`deviceType`	string	required if this object is provided	Type of device used for that transaction (e.g., 'mobile', 'laptop', 'tablet')
`deviceName`	string	required if this object is provided	Name of the device (e.g., 'iPhone 12', 'Samsung Galaxy S21')
`deviceOS`	string	required if this object is provided	Operating system of the device (e.g., 'iOS 14', 'Android 11')
`browser`	string	required if this object is provided	Name of the browser (e.g., 'Chrome', 'Safari')
`userAgent`	string	required 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.


`subscriptionId`	string	required if this object is provided
`schemeTransactionId`	string	required 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).
`schemeBrand`	string	required 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
`interval`	string	required if this object is provided	E.g.: 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
`price`	int	required if this object is provided	Amount in cents
`currency`	string	required if this object is provided
`paymentNumber`	integer	optional
`totalPayments`	integer	optional

threeDSecure

Required object when isMIT and isRecurring are true.


`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	The indication of an online commerce transaction.
`authenticationValue`	string	required if this object is provided	The encrypted code from the cardholder's bank.
`directoryServerTransactionId`	string	required if this object is provided	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.


`sku`	string	optional	The SKU of the item.
`name`	string	optional	The name of the item.
`description`	string	optional	The description of the item.
`amount`	integer	optional	The amount of the item.
`discountAmount`	integer	optional	The discount amount on the item.
`tax`	integer	optional	The tax on the item.
`discountType`	string	optional	The discount type on the item.
`quantity`	string	optional	The quantity of this item.

shippingInformation

Optional object.


`firstName`	string	required if this object is provided
`lastName`	string	required if this object is provided
`phone`	string	optional
`country`	string	required if this object is provided
`countryCode`	string	required if this object is provided	ISO 3166-1 alpha-2 country code (2-letter)
`addressLine1`	string	required if this object is provided
`addressLine2`	string	optional
`state`	string	optional	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
`zipCode`	string	required if this object is provided	5 or 9 digits

additionalFields

Optional array of object.


`key`	string	optional	Description of the additional information.
`value`	string	optional	Content 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.


`transmitId`	Response 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}}"
}

/transmit

❗️
Prerequisites to invoke this API:

❕
When using SFTP batches:

Request parameters

Additional parameters for MIT

transaction

payer

billingInformation

paymentMethod

merchant

deviceDetails

subscription

threeDSecure

orderItems

shippingInformation

additionalFields

Response

Payload examples

Request example

Response example

❗️Prerequisites to invoke this API:

❕When using SFTP batches:

Request parameters

Additional parameters for MIT

transaction

payer

billingInformation

paymentMethod

merchant

deviceDetails

subscription

threeDSecure

orderItems

shippingInformation

additionalFields

Response

Payload examples

Request example

Response example

❗️
Prerequisites to invoke this API:

❕
When using SFTP batches: