/evaluate

On a declined transaction, POST /evaluate for Flex to analyze and rescue/decline it.


Retrieve the tokenized credit card information and pass it along with the /evaluate request. Flex will then determine if this transaction can be rescued or not.

Overview

To rescue a declined transaction, send an /evaluate request with the corresponding payment method token.

To rescue a declined transaction, send an /evaluate request with the corresponding payment method token.


Request

Flex can rescue transactions in different ways:

Customer Initiated Transactions (CIT)Merchant Initiated Transactions (MIT)MIT batch request via SFTP
Straight transactions on a checkout page.Rebills on subscriptions.File containing multiple payment subscription rebills, sent in a secured and private server.
Real-time response.Async response.Async response.
curl --request POST \
     --url https://api-sandbox.flex-charge.com/v1/evaluate \
     --header 'Authorization: Bearer {bearer_token_returned_by_oauth2}' \ //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": 15000,	//In cents. must be >10 and <20000 for test calls
    "currency": "USD",
    "responseCode": "203",
    "avsResultCode": "M",
    "cvvResultCode": "NA",
    "processorName": "Acme Payments",
    "cavvResultCode": "2",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "transactionType": "CAPTURE",
    "dynamicDescriptor": "MyShoesStore"
  },
  "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": 2500,
      "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": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "city": "CA",
    "zipcode": "94111"
  },
  "merchant": {
    "country": "US",
    "mcc": 5999,
    "id": "merchant123",
    "name": "Acme Inc."
  },
  "affiliate": {
    "id": "123123123",
    "name": "Affiliate 1"
  },
  "paymentMethod": {
    "holderName": "John Doenowitz",
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "United States",
    "cardIssuer": "Acme Bank",
    "cardFingerprint": "abcd1234",
    "expirationMonth": 12,
    "expirationYear": 2028,
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111",
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" // If you are not PCI compliant, do not send credit card number in clear, send token returned by /tokenize
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "mid": "abcd1234", //Replace with your mid
  "siteId" : "UUID/GUID", //needs to be taken from the merchant portal developers section
  "siteUrl" : "https://www.someSite.com",
  "orderSource" : "ecommerce",
  "isDeclined": true,
  "isMIT": false,
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511", //must be unique even for test calls
  "idempotencyKey": "abcd1234"
}
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,
	"expiryDateUtc": "2023-05-24T12:30:20Z",
	"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, //In cents. must be >10 and <20000 for test calls
    "currency": "USD",
    "responseCode": "203",
    "avsResultCode": "M",
    "cvvResultCode": "NA",
    "processorName": "Acme Payments",
    "cavvResultCode": "2",
    "responseCodeSource": "NMI",
    "responseDescription": "Activity limit exceeded",
    "responseStatus": "DECLINED",
    "transactionType": "CAPTURE",
    "dynamicDescriptor": "MyShoesStore"
  },
  "payer": {
    "id": "customer123",
    "email": "[email protected]", //must be this exact address mail if using the 4111111111111111 test card
    "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": "Doenowitz",
    "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."
  },
  "affiliate": {
    "id": "123123123",
    "name": "Affiliate 1"
  },
  "paymentMethod": {
    "holderName": "John Doe",
    "cardType": "CREDIT",
    "cardBrand": "VISA",
    "cardCountry": "United States",
    "cardIssuer": "Acme Bank",
    "cardFingerprint": "abcd1234",
    "expirationMonth": 2028,
    "expirationYear": 12,
    "cardBinNumber": "411111",
    "cardLast4Digits": "1111",
    "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
  },
  "billingInformation": {
    "firstName": "John",
    "lastName": "Doenowitz",
    "phone": "+1 555-123-4567",
    "country": "United States",
    "countryCode": "US",
    "addressLine1": "123 Main St.",
    "state": "CA",
    "city": "San Francisco",
    "zipcode": "94111"
  },
  "mid": "123-456", //replace with your mid
  "isDeclined": true,
  "orderId": "987-654-321", //must be unique even for test calls
  "idempotencyKey": "abcd1234",
}
'
{
  "mid": "123456789-987654321", //replace with your mid
  "authorizationToken": "Bearer abc123def456" //replace with bearer returned by oauth2
  "expiryDateUtc": "2023-04-05T01:23:45.678Z", //default expiry date and time for the whole batch, you can specify individual expiryDate within each transaction
  "requests": [
    {
    
    "sequenceNumber": 1, // The numerical position of the transaction within the batch.
    "IsDeclined": true
    "isMIT": true,
    "isRecurring": true,
    "SiteUrl": "https://example.com", //Website linked to the descriptor of the subscription.
    "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, //in cents, >$10 and <$200 for tests
      "currency": "USD",
      "responseCode": "203",
      "avsResultCode": "M",
      "cvvResultCode": "NA",
      "processorName": "Acme Payments",
      "cavvResultCode": "2",
      "responseCodeSource": "NMI",
      "responseDescription": "Activity limit exceeded",
      "responseStatus": "DECLINED",
      "transactionType": "CAPTURE",
      "dynamicDescriptor": "MyShoesStore"
    },
    "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",
      "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
    },
    "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"
    },

    "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511", //must be unique even for test calls
    "idempotencyKey": "abcd1234",
    "senseKey": "1234567890"
},
{ 
    "sequenceNumber": 2, // The numerical position of the transaction within the batch.
    "isMIT": true,
    "isRecurring": true,
    "isDecline": true,
    "SiteUrl": "https://example.com", //Website linked to the descriptor of the subscription
    "subscription": {
        "subscriptionId": "sub_654321",
        "schemeTransactionId": "txn_210987",
        "schemeBrand": "Mastercard",
        "interval": "Weekly",
        "price": 1599,
        "currency": "USD",
        "paymentNumber": 3,
        "totalPayments": 52
    },
      "threeDSecure": {
        "threeDsVersion": "2.2.0",
        "ecommerceIndicator": "01",
        "authenticationValue": "hijklm67890",
        "directoryServerTransactionId": "ds_456789",
        "xid": "xid_135790",
        "authenticationValueAlgorithm": "SHA-512",
        "directoryResponseStatus": "A",
        "authenticationResponseStatus": "C",
        "enrolled": "Y"
    },
      "transaction": {
        "id": "1234567",
        "timestampUtc": "0001-01-01T00:00:00Z",
        "timezoneUtcOffset": 0,
        "amount": 14999,
        "currency": "USD",
        "responseCode": "204",
        "avsResultCode": "N",
        "cvvResultCode": "M",
        "processorName": "XYZ Payments",
        "cavvResultCode": "1",
        "responseCodeSource": "Braintree",
        "responseDescription": "Insufficient funds",
        "responseStatus": "DECLINED",
        "transactionType": "AUTHORIZE"
    },
      "payer": {
        "id": "customer456",
        "email": "[email protected]",
        "phone": "+1 555-987-6543",
        "birthdate": "1985-05-05"
    },
      "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
    }
    ],
      "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."
    },
    "affiliate": {
   		 "id": "123123123",
   		 "name": "Affiliate 1"
 		 },
      "paymentMethod": {
        "holderName": "Jane Doe",
        "cardType": "CREDIT",
        "cardBrand": "MASTERCARD",
        "cardCountry": "United States",
        "cardIssuer": "XYZ Bank",
        "cardFingerprint": "efgh5678",
        "expirationMonth": 2028,
        "expirationYear": 12,
        "cardBinNumber": "123456",
        "cardLast4Digits": "7890",
        "cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
    },

      "billingInformation": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1 555-987-6543",
        "country": "United States",
        "countryCode": "US",
        "addressLine1": "456 Oak St.",
        "city": "NY",
        "zipcode": "10001"
      },
      
      "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09512", /must be unique even for test calls
      "idempotencyKey": "abcd1234",
      "senseKey": "1234567890"
}
  ]
}

❗️

Prerequisites to invoke this API:

Body parameters

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

isDeclinedboolrequired
midstringoptionalYour Flex Merchant Identification Number. Get your Mid
orderIdstringrequiredYour internal order ID.
siteIdstringrequiredUnique Flex ID of the website/campaign generating this transaction.
Retrieve your siteId
siteUrlstringoptionalUrl can be specified if multiple domains share the same siteId.
orderSourcestringoptionalSource of the order. if not sent the default is ecommerce
ecommerce, terminal, vterminal
idempotencyKeyguid/uuidrequiredYou need to generate a unique GUID/UUID, so that we can identify repeated requests.
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.
billingInformationobjectrequiredSee billingInformation fields below.
paymentMethodobjectrequiredSee paymentMethod fields below.
shippingInformationobjectoptionalSee shippingInformation fields below.
merchantobjectrequired
for partners
See merchant fields below
orderItemsobject arrayoptionalSee orderItems fields below.
additionalFieldsobject arrayoptionalSee additionalFields fields below.

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.
expiryDateUtcdatetimerequired
for MIT
Indicates period during which Flex will retry the transaction.
siteUrlstringOptional
for MIT
Website linked to the descriptor of the subscription.
subscriptionobjectrequired
for MIT
See subscription fields below.
threeDSecureobjectrequired
for MIT
See 3DSecure fields below.

❗️

Send only MIT that have just failed

The Flex service is optimized to work with failed Merchant Initiated Transactions (MIT) that have just failed. These need to be passed to Flex on that day (and not after a few days or weeks) and should not be retried by the Merchant up to the set expiry date.


Detailed object parameters:

transaction

Required object

idstringrequiredExternal transaction identifier in the format of a GUID
dynamicDescriptorstringconditionalRequired only if enabled
timestampUtcdatetimerequiredDate and time of the transaction.
timezoneUtcOffsetintegerrequiredUTC offset of the timezone.
transactionTypestringoptionalE.g.: 'Auth', 'Capture', 'Void'
riamountintegerrequiredAmount of the transaction in cents.
Must be >$0.00 and <$200.00
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

emailstringrequiredIf value cannot be provided, send 'NA' and provide phone instead.
phonestringoptional
idstringoptionalExternal ID
birthdatedatetimeoptional

affiliate

optional object

idstringThis is an internal identifier for the affiliate. It's typically used for backend or database purposes to uniquely identify affiliates within a system.
namestringThis is a friendly name or label associated with the affiliate.

billingInformation

Required object.

firstNamestringrequired
lastNamestringrequired
phonestringoptional
countrystringrequired
countryCodestringrequiredISO 3166-1 alpha-2 country code (2-letter)
addressLine1stringrequired
addressLine2stringoptional
statestringrequired
for US cards
2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2)
citystringrequired
zipCodestringrequired5 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.
cardNumberstringrequired- Send the token that was returned with /tokenize
- Send the full PAN if you are PCI compliant
tokenbooleanoptional- If you send a Flex token in cardNumber: provide true
- If you send the full PAN in cardNumber: provide false

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

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).
E.g.: 'txn_789012'
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
paymentNumberstringoptional
totalPaymentsstringoptional

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

{
  "Result":"Success/Failed",
  "Status": "APPROVED | DECLINED | CHALLENGE | SUBMITTED",
  "OrderSessionKey": "{{$guid}}", //Flex unique transaction identifier
  "SenseKey": "same value that was present in request", //optional
}
resultstringSuccess/Failed
statusstringFor CIT sync calls: APPROVED ; DECLINED ; CHALLENGE
---
For MIT calls: SUBMITTED
---
If status is CHALLENGE or SUBMITTED, use /outcome or webhook to retrieve order status on that async calls.
orderSessionKeyguid/uuidFlex unique transaction identifier
senseKeystringOptional.

Order status

Order status next steps according to your integration.

APPROVEDDECLINEDCHALLENGESUBMITTED
Standard CIT integrationClient side:
redirect on success page
Client side:
redirect on decline page
Client side:
redirect on decline page
N/A
Advanced CIT integrationClient side:
redirect on success page
Client side:
redirect on decline page
Client side:
invoke UI Widget
Server side:
update order status
Client side:
invoke UI Widget
Server side:
update order status
MIT integrationN/AN/AN/AServer side:
update order status