/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:
- Customer Initiated Transactions (CIT): one-time transactions where a customer enters their credit card information on a checkout page
- Merchant Initiated Transactions (MIT): merchant initiates the payment on behalf of the customer, in the case of a recurring subscription for example.
- MIT batch request via SFTP: a file containing multiple payment transactions initiated by a merchant is sent to FlexCharge secured and private server.
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:
- Authenticate and send the bearer token for this call.
- Tokenize the paymentMethod, and use the returned token for this call.
Body parameters
Try it right now: check out the /evaluate Reference. or the Postman Collection
isDeclined | bool | required | |
idempotencyKey | guid/uuid | required | You need to generate a unique GUID/UUID, so that we can identify repeated requests. |
orderId | string | required | Your internal order ID. |
orderSource | string | optional | Source of the order E.g.: ecommerce, installment, etc. |
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 |
mid | string | required for partners | Your FlexCharge Merchant Identification Number. Get your Mid |
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 | 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. |
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
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. 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 |
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 | optional | 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). |
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
{
"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
}
Updated 1 day ago