/evaluate

On declined/failed transactions, you will have to invoke FlexCharge's Evaluate API. This ACTIVATES the FlexCharge service.

FlexCharge can rescue transactions in different ways:


Request

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 '
{
  "transaction": {
    "id": "3478613",
    "timestampUtc": "0001-01-01T00:00:00Z",
    "timezoneUtcOffset": 0,
    "amount": 15000,    //In cents. must be >0 and <20000
    "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": "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": "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"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511",
  "idempotencyKey": "abcd1234",
  "senseKey": "1234567890"
}
'
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-24T00:00:00Z",
    "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",
    "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"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511",
  "idempotencyKey": "abcd1234",
  "senseKey": "1234567890"
}
'
{
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "authorizationToken": "Bearer abc123def456" //replace with bearer returned by oauth2
  "expiryDateUtc": "2023-04-05T01:23:45.678Z", //default expiry date for the whole batch
  "requests": [
    {

    "isMIT": true,
    "isRecurring": true,
    "expiryDateUtc": "2023-05-24T00:00:00Z",
    "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",
    "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"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511",
  "idempotencyKey": "abcd1234",
  "senseKey": "1234567890"
}

{
"isMIT": true,
"isRecurring": true,
"isDecline": true,
"expiryDateUtc": "2023-06-24T00:00:00Z",
"subscription": {
    "subscriptionId": "sub_654321",
    "schemeTransactionId": "txn_210987",
    "schemeBrand": "Mastercard",
    "interval": "Weekly",
    "price": 15.99,
    "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."
},
    "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"
  },
  "mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
  "orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511",
  "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
idempotencyKeyguid/uuidrequiredYou need to generate a unique GUID/UUID, so that we can identify repeated requests.
orderIdstringrequiredYour internal order ID.
orderSourcestringoptionalSource of the order
E.g.: ecommerce, installment, etc.
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
midstringrequired
for partners
Your FlexCharge Merchant Identification Number. Get your Mid
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 FlexCharge will retry the transaction.
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.

❗️

Exclusive retry mechanism with MIT that have just failed

The FlexCharge service is optimized to work with failed Merchant Initiated Transactions (MIT) that have just failed. These need to be passed to FlexCharge 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
timestampUtcdatetimerequiredDate and time of the transaction.
timezoneUtcOffsetintegerrequiredUTC offset of the timezone.
transactionTypestringoptionalE.g.: 'Auth', 'Capture', 'Void'
amountintegerrequiredAmount 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

billingInformation

Required object.

firstNamestringrequired
lastNamestringrequired
phonestringoptional
countrystringrequired
countryCodestringrequiredISO 3166-1 alpha-2 country code (2-letter)
addressLine1stringrequired
addressLine2stringoptional
statestringoptional2-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
cardBrandstirngrequiredE.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.
cardNumberstringrequiredPCI compliance: do not send cardNumber in clear,
send token that was returned with /tokenize

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

{
  "Result":"Success/Failed",
  "Status": "APPROVED | DECLINED | EXPIRED | CANCELLED | SUBMITTED",
  "OrderSessionKey": "{{$guid}}", //FlexCharge's unique transaction identifier
  "SenseKey": "same value that was present in request", //optional
}
resultstringSuccess/Failed
statusstringFor CIT sync calls: APPROVED ; DECLINED
For MIT calls: SUBMITTED
Use /outcome or webhook to retrieve status on async calls.
orderSessionKeyguid/uuidFlexCharge's unique transaction identifier
senseKeystringOptional.