The integration grants access to Forter's Fraud Management and Issuer Optimization with Mastercard.

Integration Flow

Integration Phases

Setup

Prior to commencing development, verify that the integration prerequisites are met between the merchant and Forter.

Full PAN

Verify that you can pass the full card number in the Order API. This information is required for Issuer Optimization with Mastercard IDCI.

If you have vaulted cards and the full card number is not exposed on the checkout page, please check with your Tokenization vendor regarding the availability of a Detokenization Proxy service. This service enables you to make a request to a 3rd party (such as Forter Order API) with a Token included in the request. The request is then routed through the proxy, where the token is replaced with the corresponding card data.

Gateway , Processor and Acquirer Data

Verify that you can pass all the details about the expected Authorization process in the Order API:

Gateway Data
Name (e.g Braintree)

Processor Data
Name (e.g Chase Paymentech)

Acquirer Data
Acquirer Name (e.g Barclays)
Acquirer BIN
Acquirer Merchant Id
Acquirer Merchant Name
Merchant Category Code
Merchant Country Code
AcquirerCountry

Note that it in some cases the GW, Acquirer and Processor services are provided by the same company.

Get your API Keys

Forter uses Basic authentication. Provide your API key as the basic auth username value.

All Forter APIs require a unique site-id in the https request header in order to validate the request source. This mechanism must be used in all backend API requests that are sent from the merchant's server to Forter.

In Forter Portal, toggle between Live and Sandbox (TEST) environments to find your secret key on the Settings page.

Forter JS & Mobile SDK

See here how to incorporate Forter's client components into your website and application.

Pre Auth Order API

The Order API provides real-time fraud decisions along with Issuer Optimization for Mastercard.

Order Request

The request should be sent before calling the payment gateway to authorize funds (Pre-Auth) ; e.g when the consumer presses 'Pay' after filling the card details. Please provide all relevant data points that will aid Forter in determining whether the transaction or engagement is legitimate or fraudulent. Note that full card data is required for Issuer Optimization with Mastercard.

Please note that some fields are only required for specific use cases. For instance, fields related to a specific payment method are only necessary if the customer has utilized that particular method, fields pertaining to hotel reservations are only mandatory for the hospitality vertical etc. Please reach out to your account manager for a list of applicable fields.

Example of Order Request

  "orderId": "171abcde",
  "authorizationStep": "PRE_AUTHORIZATION",
  "orderType": "WEB",
  "primaryDeliveryDetails": {
    "deliveryType": "PHYSICAL",
    "deliveryMethod": "USPS - Ground Mail",
    "delayedDeliveryDate": "2022-12-15",
    "expectedDeliveryDate": "2022-12-22",
    "smsUpdates": true,
    "deliveryPrice": {
      "amountUSD": "99.95"
    },
    "waitToShipTogether": true,
    "trackingExtraCharge": {
      "amountUSD": "99.95"
    },
    "leaveOutside": true,
    "carrier": "USPS",
    "deliveryComments": "Please call before arriving, Thanks!"
  },
  "cartItems": [
    {
      "basicItemData": {
        "name": "White GenericBrand handbag",
        "price": {
          "amountUSD": "99.95"
        },
        "type": "TANGIBLE",
        "quantity": 1,
        "category": "Apparel and accessories",
        "productIdType": "SKU",
        "discount": {
          "couponCodeUsed": "FATHERSDAY2015",
          "discountType": "COUPON"
        },
        "productId": "Ag54352R7768kkO",
        "id": "342S5453Gy"
      },
      "itemSpecificData": {
        "physicalGoods": {
          "customDesign": true,
          "wrapAsGift": true,
          "size": "7.5"
        },
        "personalCustomization": true
      },
      "created": 1415273168
    }
  ],
  "primaryRecipient": {
    "personalDetails": {
      "firstName": "John",
      "lastName": "Smith",
      "fullName": "John Smith",
      "suffix": "Jr.",
      "prefix": "Mr.",
      "middleInitials": "R. H."
    },
    "phone": [
      {
        "updateTimes": {
          "creationTime": 1448549922,
          "removalTime": 1448895522
        },
        "phone": "15557654321",
        "phoneType": "HOME"
      }
    ],
    "address": {
      "country": "US",
      "updateTimes": {
        "creationTime": 1448549922,
        "removalTime": 1448895522
      },
      "addressType": "HOME",
      "zip": "94104",
      "address1": "235 Montgomery st.",
      "address2": "Ste. 1110",
      "region": "CA",
      "city": "San Francisco"
    }
  },
  "checkoutTime": 1415273168,
  "connectionInformation": {
    "customerIP": "10.0.0.127",
    "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",
    "forterTokenCookie": "2315688945984",
    "merchantDeviceIdentifier": "HGJ7512345H3",
    "fullHeaders": "{\\\"method\\\":\\\"GET \\/ HTTP\\/1.1\\\", \\\"Host\\\": \\\"forter.com\\\", \\\"Connection\\\": \\\"keep-alive\\\", \\\"Accept\\\": ...}"
  },
  "timeSentToForter": 1415287568000,
  "totalAmount": {
    "amountUSD": "99.95"
  },
  "payment": [
    {
      "amount": {
        "amountUSD": "99.95"
      },
      "billingDetails": {
        "personalDetails": {
          "firstName": "John",
          "lastName": "Smith",
          "fullName": "John Smith"
        },
        "phone": [
          {
            "updateTimes": {
              "creationTime": 1448549922,
              "removalTime": 1448895522
            },
            "phone": "15557654321",
            "phoneType": "HOME",
            "phoneExt": "1001"
          }
        ],
        "address": {
          "country": "US",
          "updateTimes": {
            "creationTime": 1448549922,
            "removalTime": 1448895522
          },
          "addressType": "HOME",
          "zip": "94104",
          "address1": "235 Montgomery st.",
          "address2": "Ste. 1110",
          "region": "CA",
          "city": "San Francisco"
        }
      },
      "creditCard": {
        "creditCardCorrelationId": "2022-09-16T200920526-eb7f9e9d-v3",
        "bin": "42424242",
        "expirationMonth": "03",
        "lastFourDigits": "4242",
        "expirationYear": "2018",
        "nameOnCard": "John R. H. Smith",
        "countryOfIssuance": "US",
        "cardType": "CREDIT",
        "cardBank": "Chase",
        "paymentProcessorData": {
          "processorName": "Braintree",
          "processorMerchantId": "ncxwe5490asjdf",
          "processorTransactionId": "fjdsS46sdklFd20"
        },
        "cardBrand": "VISA",
        "paymentGatewayData": {
          "authorizationStep": "pre-authorization",
          "gatewayTransactionId": "fjdsS46sdklFd20",
          "gatewayName": "Braintree",
          "gatewayMerchantId": "ncxwe5490asjdf",
        },
        "threeDSecure": {
          "execute3ds": "DYNAMIC_FORTER_DECISION",
          "threeDSServerTransID": "4bg93513-f9b4-43bf-8b76-2dd523a1e858",
          "threeDSEncodedMobileAppSDKData": null
        },
        "fullResponsePayload": {}
      }
    }
  ],
  "customerAccountData": {
    "customerEngagement": {},
    "statusChangeBy": "MERCHANT_ADMIN",
    "merchantAccountStatus": "open",
    "statusChangeReason": "user violation of coupon abuse policy",
    "historicalIPData": [
      {
        "ip": "10.0.0.128",
        "updateTimes": {
          "creationTime": 1448549922,
          "removalTime": 1448895522
        }
      }
    ],
    "type": "BUSINESS",
    "status": "ACTIVE",
    "orderHistory": [
      {
        "status": "SENT",
        "basicItemData": {
          "name": "White GenericBrand handbag",
          "price": {
            "amountUSD": "99.95"
          },
          "type": "TANGIBLE",
          "quantity": 1,
          "category": "Apparel and accessories",
          "productIdType": "SKU",
          "discount": {
            "couponCodeUsed": "FATHERSDAY2015",
            "discountType": "COUPON"
          },
          "productId": "Ag54352R7768kkO",
          "id": "342S5453Gy"
        },
        "orderTime": 1415273168
      }
    ],
    "registrationIP": "203.12.55.12"
  },
  "accountOwner": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "pastOrdersCount": 51,
    "created": 1415273168,
    "accountId": "e520-ba9a-367-60b",
    "pastOrdersSum": 1702.5,
    "lastLoginIP": "203.12.55.12",
    "registrationIP": "203.12.55.12"
  },
  "additionalIdentifiers": {
    "merchant": {
      "merchantDomain": "HandbagsExpressDiscounts.com",
      "merchantId": "eh629dK9",
      "merchantName": "Handbags Express Discounts"
    },
    "paymentGatewayId": "5TG23432562",
    "splitOrderIds": [
      [
        "6543545",
        "6545635"
      ]
    ],
    "isSplitOrder": true,
    "additionalOrderId": "4306795"
  },
  "additionalInformation": {},
  "totalDiscount": {
    "couponCodeUsed": "FATHERSDAY2015",
    "discountType": "COUPON"
  }
}

Order Response

Outcome	Call to Action	Order Response Fields
Forter Approved Transaction APPROVED by Forter	Authorize	`"forterDecision": "APPROVE"` In order to test such response, use the the email address [email protected] in the accountOwner object within the API request.
Forter Approved & Data Only was executed Transaction APPROVED by Forter and has data only recommendation	Authorize with IDCI results	`"forterDecision": "APPROVE", "verificationMethod": {"status": "DATA_ONLY", ...}` In order to test such response, use the the email address [email protected] in the accountOwner object within the API request.
Forter Declined Hard DECLINE by Forter	Do not Authorize	`"forterDecision": "DECLINE"` In order to test such response, use the the email address [email protected] in the accountOwner object within the API request.
Forter didn't Review Transaction wasn't reviewed for providing fraud decision. Usually in Listening Mode during onboarding.	Act according to the policies in place prior to the integration with Forter.	`"forterDecision": "NOT REVIEWED"` In order to test such response, use the the email address [email protected] in the accountOwner object within the API request.

Authorization

To provide the bank with the IDCI results on APPLY_DATA_ONLY_PROTOCOL recommendation, it is necessary to modify your integration with the Payment Service Provider (PSP). This adjustment involves including the following values from Forter Order Response in the PSP Authorization request.

verificationMethod.verificationSpecificData.ThreeDS.dsTransID
verificationMethod.verificationSpecificData.ThreeDS.authenticationValue

Please refer to the mapping examples provided below.

Adyen

Map the previously mentioned Forter fields to thedsTransID and cavv fields within the Adyen authorize request.

Braintree

Map the previously mentioned Forter fields to the dsTransactionId and cavv fields within the Braintree Transaction: Sale request.

Status API

Same as in the 3DS Execution Integration. Refer to the details provided here.

Claims API

Same as in the 3DS Execution Integration. Refer to the details provided here.