/evaluate
On a declined transaction, POST /evaluate for FlexCharge to analyze and rescue/decline it.
Retrieve the tokenized credit card information and pass it along with the /evaluate request. FlexCharge 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.
Request
FlexCharge 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: 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 >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": 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": "abcd1234", //Replace with your mid
"siteId" : "UUID/GUID", //need 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:
- Authenticate and send the bearer token for this call.
- Retrieve Payment Method token for this call.
Body parameters
Try it right now: check out the /evaluate Reference. or the Postman Collection
isDeclined | bool | required | |
mid | string | optional | Your FlexCharge Merchant Identification Number. Get your Mid |
orderId | string | required | Your internal order ID. |
siteUrl | string | optional | Website linked to the descriptor of the subscription. |
siteId | string | optional | |
orderSource | string | optional | Source of the order E.g.: ecommerce, installment, etc. |
idempotencyKey | guid/uuid | required | You need to generate a unique GUID/UUID, so that we can identify repeated requests. |
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. |
billingInformation | object | required | See billingInformation fields below. |
paymentMethod | object | required | See paymentMethod fields below. |
shippingInformation | object | optional | See shippingInformation fields below. |
merchant | object | required for partners | See merchant fields below |
orderItems | object array | optional | See orderItems fields below. |
additionalFields | object array | optional | See additionalFields fields below. |
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. |
expiryDateUtc | datetime | required for MIT | Indicates period during which FlexCharge will retry the transaction. |
siteUrl | string | Optional 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. |
Send only 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
id | string | required | External transaction identifier in the format of a GUID |
dynamicDescriptor | string | conditional | Required only if enabled |
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. Must be >$0.00 and <$200.00 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 | If value cannot be provided, send 'NA' and provide phone instead. |
phone | string | optional | |
id | string | optional | External ID |
birthdate | datetime | optional |
affiliate
optional object
id | string | This is an internal identifier for the affiliate. It's typically used for backend or database purposes to uniquely identify affiliates within a system. |
name | string | This is a friendly name or label associated with the affiliate. |
billingInformation
Required object.
firstName | string | required | |
lastName | string | required | |
phone | string | optional | |
country | string | required | |
countryCode | string | required | ISO 3166-1 alpha-2 country code (2-letter) |
addressLine1 | string | required | |
addressLine2 | string | optional | |
state | string | required for US cards | 2-letter and 2-digit codes from the ANSI standard INCITS 38:2009 (supersedes FIPS 5-2) |
city | string | required | |
zipCode | string | required | 5 or 9 digits |
paymentMethod
Required object.
holderName | string | required | |
cardType | string | required | E.g.: Credit, Debit, Prepaid Card |
cardBrand | stirng | 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. |
cardNumber | string | required | PCI compliance: do not send cardNumber in clear, send token that was returned with /tokenize |
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 |
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). E.g.: 'txn_789012' |
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 | string | optional | |
totalPayments | string | 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
{
"Result":"Success/Failed",
"Status": "APPROVED | DECLINED | CHALLENGE | SUBMITTED",
"OrderSessionKey": "{{$guid}}", //FlexCharge's unique transaction identifier
"SenseKey": "same value that was present in request", //optional
}
result | string | Success/Failed |
status | string | For 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. |
orderSessionKey | guid/uuid | FlexCharge's unique transaction identifier |
senseKey | string | Optional. |
Order status
Order status next steps according to your integration.
APPROVED | DECLINED | CHALLENGE | SUBMITTED | |
|---|---|---|---|---|
| Standard CIT integration | Client side: redirect on success page | Client side: redirect on decline page | Client side: redirect on decline page | N/A |
| Advanced CIT integration | Client 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 integration | N/A | N/A | N/A | Server side: update order status |
Updated about 1 month ago
What’s Next