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 Name | Type | API validation | Notes |
|---|---|---|---|
isDeclined | bool | optional | true when the transaction was declined, false when it was approved. |
orderId | string | optional | Your internal order ID. |
orderSource | string | optional | Source of the order. Allowed values: ecommerce, terminal, vterminal. Defaults to ecommerce. |
sequenceNumber | string | optional | FlexFactor needs it for SFTP batch. Numerical position of that transaction within the batch. Starting from 1. |
customerIp | string | optional | The customer's IP as captured on the checkout page. Must be the end-user / cardholder browser IP, not the merchant server IP. |
isMIT | bool | optional | true for merchant-initiated transactions. When true, FlexFactor needs the MIT fields. |
transaction | object | optional | See transaction fields below. |
payer | object | optional | See payer fields below. |
paymentMethod | object | optional | See paymentMethod fields below. |
billingInformation | object | optional | See billingInformation fields below. |
shippingInformation | object | optional | See shippingInformation fields below. |
merchant | object | optional | Recommended for partner/gateway calls. See merchant fields below |
deviceDetails | object | optional | See deviceDetails fields below |
mid | string | optional | FlexFactor needs it for partner integrations. Your FlexFactor Merchant Identification Number. Get your Mid |
orderItems | object array | optional | See orderItems fields below. |
additionalFields | object array | optional | See additionalFields fields below. |
userDefinedFields | object array | optional | Array of key/value objects with the same shape as additionalFields. |
extraData | string | optional | Open-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 Name | Type | API validation | Notes |
|---|---|---|---|
isMIT | bool | optional | true for merchant-initiated transactions. When true, FlexFactor needs the MIT fields below. |
isRecurring | bool | optional | FlexFactor needs it for MIT. true for subscriptions. |
siteUrl | string | optional | FlexFactor needs it for MIT. Website linked to the descriptor of the subscription. |
subscription | object | optional | FlexFactor needs it for MIT. See subscription fields below. |
Detailed object parameters:
transaction
Object FlexFactor needs for every transmit.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
id | string | optional | External transaction identifier in the format of a GUID |
timestampUtc | datetime | optional | Date and time of the transaction. |
timezoneUtcOffset | integer | optional | UTC offset of the timezone. Optional; you can omit it. |
transactionType | string | optional | E.g.: 'Auth', 'Capture', 'Void' |
amount | integer | optional | Amount of the transaction in cents. E.g. $19.99 -> '1999' |
currency | string | optional | ISO 4217 currency code. |
responseCode | string | optional | 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 | optional | This is the source of the code from the original transaction E.g.: "nmi", "Paypal". If this value cannot be provided, send null. |
processorName | string | optional | Name of the processor. |
avsResultCode | string | optional | Address Verification Service result code. |
cvvResultCode | string | optional | Card Verification Value result code. |
cavvResultCode | string | optional | Cardholder Authentication Verification Value result code. |
cardNotPresent | bool | optional | Indicates if the card was present during the transaction. |
payer
Object FlexFactor needs for every transmit.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
email | string | optional | |
phone | string | optional | |
id | string | optional | External ID |
birthdate | datetime | optional |
billingInformation
Optional object.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
firstName | string | optional | FlexFactor needs it when you send this object. |
lastName | string | optional | FlexFactor needs it when you send this object. |
fullName | string | optional | Full name of the cardholder. |
phone | string | optional | |
country | string | optional | FlexFactor needs it when you send this object. |
countryCode | string | optional | FlexFactor needs it when you send this object. ISO 3166-1 alpha-2 country code (2-letter) |
addressLine1 | string | optional | FlexFactor needs it when you send this object. |
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 | optional | FlexFactor needs it when you send this object. |
zipcode | string | optional | FlexFactor needs it when you send this object. 5 or 9 digits |
paymentMethod
Object FlexFactor needs for every transmit.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
holderName | string | optional | |
cardType | string | optional | E.g.: Credit, Debit, Prepaid Card |
cardBrand | string | optional | E.g.: VISA, Mastercard |
cardCountry | string | optional | ISO 3166-1 alpha-2 country code (2-letter) |
cardIssuer | string | optional | |
cardLevel | string | optional | |
cardFingerprint | string | optional | |
expirationMonth | integer | optional | |
expirationYear | integer | optional | |
cardBinNumber | string | optional | 6 character string. |
cardLast4Digits | string | optional | 4 character string. |
token | boolean | optional | Indicates whether the payment method is a FlexFactor token. |
merchant
Optional object. Recommended for partner/gateway calls.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
id | string | optional | FlexFactor needs it when you send this object. External ID |
name | string | optional | |
mcc | integer | optional | FlexFactor needs it when you send this object. Merchant Category Codes used to identify the type of business in which a merchant is engaged. |
country | string | optional | FlexFactor needs it when you send this object. |
deviceDetails
Optional object.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
deviceType | string | optional | FlexFactor needs it when you send this object. Type of device used for that transaction (e.g., 'mobile', 'laptop', 'tablet') |
deviceName | string | optional | FlexFactor needs it when you send this object. Name of the device (e.g., 'iPhone 12', 'Samsung Galaxy S21') |
deviceOS | string | optional | FlexFactor needs it when you send this object. Operating system of the device (e.g., 'iOS 14', 'Android 11') |
browser | string | optional | FlexFactor needs it when you send this object. Name of the browser (e.g., 'Chrome', 'Safari') |
userAgent | string | optional | FlexFactor 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 Name | Type | API validation | Notes |
|---|---|---|---|
subscriptionId | string | optional | FlexFactor needs it when you send this object. |
schemeTransactionId | string | optional | FlexFactor 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). |
schemeBrand | string | optional | FlexFactor 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 |
interval | string | optional | FlexFactor needs it when you send this object. E.g.: 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'. |
price | int | optional | FlexFactor needs it when you send this object. Amount in cents |
currency | string | optional | FlexFactor needs it when you send this object. |
paymentNumber | string | optional | |
totalPayments | string | optional |
orderItems
Optional object.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
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 | integer | optional | The quantity of this item. |
shippingInformation
Optional object.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
firstName | string | optional | FlexFactor needs it when you send this object. |
lastName | string | optional | FlexFactor needs it when you send this object. |
fullName | string | optional | Full name of the recipient. |
phone | string | optional | |
country | string | optional | FlexFactor needs it when you send this object. |
countryCode | string | optional | FlexFactor needs it when you send this object. ISO 3166-1 alpha-2 country code (2-letter) |
addressLine1 | string | optional | FlexFactor needs it when you send this object. |
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 | optional | FlexFactor needs it when you send this object. |
zipcode | string | optional | FlexFactor needs it when you send this object. 5 or 9 digits |
additionalFields
Optional array of object.
| Property Name | Type | API validation | Notes |
|---|---|---|---|
key | string | optional | Description of the additional information. |
value | string | optional | Content 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.
success | boolean | true when errors is empty. |
result | string | Not populated on this endpoint; null. |
status | string | Not populated on this endpoint; null. |
statusCode | string | Not populated on this endpoint; null. It is not the HTTP status code. |
errors | array of objects | Error details; empty on success. Each item is serialized positionally: item1 message, item2 key, item3 error code, item4 friendly flag (boolean). |
customProperties | object | Optional. Additional properties. |
transmitId | guid/uuid | Response transaction key. |
HTTP status codes
| Situation | HTTP | Body |
|---|---|---|
| The copy was recorded | 200 | Envelope with success: true and transmitId |
| Invalid or expired bearer token | 401 | — |
| Not found | 404 | Problem details |
| An internal error occurred | 500 | — |
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}}"
}Updated 15 days ago

