The Fraud & 3DS Recommendation Integration offers access to Forter's Fraud Management and Payment Optimization for merchants who have already integrated with a 3DS provider.

Integration Flow

Setup

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

PSP supports 3DS requests

Verify with your PSP that you can request in the Authorization call to trigger 3DS for the transaction pre authorization.
Get the relevant reference from your PSP, for calling the Authorization API with the 3DS request.

PSP supports PSD2 exemption requests

Relevant only for PSD2 solution

Verify with your PSP that you can request in the Authorization call an exemption from executing 3DS for Low Value and Low Risk transactions.
Get the relevant reference from your PSP, for calling the Authorization API with the Exemption request.

BIN & Last 4

Verify that you can pass the card's BIN number & Last 4 digits in the Order request.

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.

curl -X POST "https://api.forter-secure.com/{service}"
      -u "${secretKey}:"
      -H "api-version: 2.0"
      -H "x-forter-siteid:${siteId}"
      -H "Content-Type: application/json"
      -d @filepost.data

JS and Mobile SDK

Incorporate Forter's client components into your website and application.

Javascript for your website

In every web page, before the closing tag, add the Forter Fraud JS. The script can be found within the Integration Center in Forter Portal, under Docs.

Make sure to include in the script your ${siteId}which is available in the Settings are in Forter Portal. Note there is a different siteId for Sandbox and Live environments.

CSP

In case the website enforces a CSP, please make sure the Forter rules are whitelisted and set the csp field inside the merchantConfig object to true.

Webview and Mobile SDKs for your App

See here Forter's client components for iOS, Android, React Native and Hybrid Apps with Webview.

Pre Auth Order API

The V2 Order API provides real-time fraud decisions along with payment optimization recommendation for the authorization call.

The request should be sent before calling the payment gateway to authorize funds (Pre-Auth).

The response will include Forter's fraud decision, along with a recommendation regarding whether to execute 3DS during the authorization call. In situations where a PSD2 solution is applicable, the response may include a recommendation to request an exemption from 3DS during the authorization call.

Order Request

Call Forter v2 Order API with all the relevant data points that will help Forter determine whether the entity conducting the transaction/engagement is legitimate or fraudulent (e.g Account, Cart Items, Billing, Delivery etc) as well as data points which are required for providing 3DS recommendation (e.g Bin - in case of PSD2 solution).

Please make sure you map all fields marked as "Required".

Note in the documentation that some fields are required only in specific use cases. For example, the fields related to a specific payment method are only required if the customer has paid using such method, the fields related to Hotel reservation are only required for the hospitality vertical etc. You should contact you account manager in order to get the list of relevant fields.

Example of Order Request


{
  "orderId": "2356fdse0rr489",
  "orderType": "WEB",
  "authorizationStep": "PRE_AUTHORIZATION",
  "additionalIdentifiers": {
    "additionalOrderId": "4306795",
    "isSplitOrder": false,
    "splitOrderIds": [
      "6543545",
      "6545635"
    ],
    "orderSegment": "Regular Checkout",
    "paymentGatewayId": "5TG23432562",
    "merchant": {
      "merchantId": "eh629dK9",
      "merchantDomain": "HandbagsExpressDiscounts.com",
      "merchantName": "Handbags Express Discounts"
    },
    "siteLocalization": {
      "country": "FR",
      "language": "EN",
      "currency": "USD"
    }
  },
  "timeSentToForter": 1415287568000,
  "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"
  },
  "totalAmount": {
    "amountUSD": "99.95",
    "amountLocalCurrency": "105.55",
    "currency": "CAD"
  },
  "totalDiscount": {
    "couponCodeUsed": "FATHERSDAY2015"
  },
  "accountOwner": {
    "fullName": "Smith",
    "email": "[email protected]",
    "accountId": "e520-ba9a-367-60b",
    "created": 1415273168,
    "pastOrdersCount": 51,
    "pastOrdersSum": 1702.5,
    "lastLoginIP": "203.12.55.12",
    "registrationIP": "203.12.55.12"
  },
  "customerAccountData": {
    "personalDetails": {
      "fullName": "John Smith",
      "middleInitials": "R. H.",
      "prefix": "Mr.",
      "suffix": "Jr.",
      "email": "[email protected]",
      "accountId": "e520-ba9a-367-60b",
      "username": "johnsm98"
    },
    "created": 1415273168,
    "type": "BUSINESS",
    "status": "ACTIVE",
    "merchantAccountStatus": "open",
    "statusChangeBy": "MERCHANT_ADMIN",
    "statusChangeReason": "user violation of coupon abuse policy",
    "passwordData": {
      "hashedPassword": "dFjKl2390fjl9!djk",
      "latestPasswordResetEmailDate": 1420294711
    },
    "isManagedAccount": false,
    "assetsInAccount": {
      "storeCreditsInAccount": {
        "amountUSD": "99.95",
        "amountLocalCurrency": "105.55",
        "currency": "CAD"
      }
    },
    "customerEngagement": {
      "likedItems": {
        "inUse": true,
        "itemInListCount": 4
      },
      "sharedItems": {
        "inUse": true,
        "itemInListCount": 4
      },
      "wishlist": {
        "inUse": true,
        "itemInListCount": 4
      },
      "reviewsWritten": {
        "inUse": true,
        "itemInListCount": 4
      },
      "communityPostsWritten": {
        "inUse": true,
        "itemInListCount": 4
      },
      "messagesSent": {
        "inUse": true,
        "itemInListCount": 4
      },
      "messagesReceived": {
        "inUse": true,
        "itemInListCount": 4
      },
      "followersCount": 105,
      "followingCount": 230,
      "profilePicture": true,
      "aboutMe": false,
      "extendedBioOrDescription": false,
      "profileLogo": false
    },
    "customerService": {
      "contactTime": 1430997968,
      "orderId": "4306795",
      "ticketId": "4306795",
      "initiatedBy": "CUSTOMER",
      "contactMethodType": "PHONE",
      "contactNameUsed": {
        "customerContactNameType": "OTHER",
        "customerFirstName": "John",
        "customerLastName": "Smith"
      },
      "contactPhoneUsed": {
        "merchantContactedPhoneRole": "BILLING_PHONE",
        "merchantContactedPhoneNumber": "212-555-5555"
      },
      "contactEmailUsed": {
        "merchantContactedEmailRole": "BILLING_EMAIL",
        "merchantContactedEmail": "[email protected]"
      },
      "contactCustomerIP": "10.0.0.127",
      "customerSupportFurtherVerification": {
        "customerSupportAdditionalVerificationDocuments": {
          "documentFirstName": "John",
          "documentLastName": "Smith",
          "documentType": "Passport",
          "nationality": "US",
          "documentVerified": true
        },
        "customerSupportSMSverification": "+1-212-555-5555",
        "customerAnsweredSecurityQuestions": true
      },
      "customerSupportChangeOrderDetails": {
        "customerSupportRequestPickupStoreZip": "94104",
        "customerSupportRequestPickupFromShippingCarrier": false,
        "customerSupportRequestSwitchBillingAndShipping": false
      }
    },
    "sellingBehaviourData": {
      "sellerDetails": {
        "sellerPersonalDetails": {
          "fullName": "John Smith",
          "middleInitials": "R. H.",
          "prefix": "Mr.",
          "suffix": "Jr.",
          "email": "[email protected]",
          "accountId": "e520-ba9a-367-60b",
          "username": "johnsm98"
        },
        "type": "BUSINESS",
        "status": "ACTIVE",
        "ratingAsBuyer": {
          "score": "4.5",
          "type": "INTERNAL_PEERS",
          "source": "yelp"
        },
        "taxExempt": false,
        "verifiedSeller": true,
        "dateVerified": 1430997968,
        "dateOfFirstSale": 1430997968,
        "sellerAccountCreationDate": 1415273168,
        "sellerPastSalesCount": 8,
        "sellerPastSalesSum": {
          "amountUSD": "99.95",
          "amountLocalCurrency": "105.55",
          "currency": "CAD"
        },
        "availableFundsForWithdrawal": {
          "amountUSD": "99.95",
          "amountLocalCurrency": "105.55",
          "currency": "CAD"
        },
        "sellerReturnsCount": 2,
        "sellerInitiatedDisputesCount": 1,
        "buyerInitiatedDisputesCount": 6,
        "sellerLostDisputesCount": 0,
        "paidForPromotion": false,
        "sellerRegistrationIP": {
          "ip": "10.0.0.128",
          "updateTimes": {
            "creationTime": 1448549922,
            "removalTime": 1448895522
          }
        },
        "sellerLastLoginIP": {
          "ip": "10.0.0.128",
          "updateTimes": {
            "creationTime": 1448549922,
            "removalTime": 1448895522
          }
        }
      },
      "itemsCurrentlyListedForSale": 5,
      "sellerVerificationCreditCard": {
        "nameOnCard": "John R. H. Smith",
        "fullCreditCard": "2424242424242424",
        "threeDSecure": {
          "acquirerData": {
            "acquirerName": "Barclays",
            "acquirerBIN": "457173",
            "acquirerMerchantId": 5245020244654,
            "acquirerMerchantName": "Simple T-shirt",
            "merchantCategoryCode": 5655,
            "merchantCountryCode": 840,
            "acquirerCountry": "US"
          },
          "threeDSServerTransID": "26d648a9-da8a-4f8b-a76d-094801d2fd45",
          "scaOutOfScope": "ANONYMOUS_PREPAID_CARD",
          "scaExemption": "TRUSTED_BENEFICIARY",
          "execute3ds": "DYNAMIC_FORTER_DECISION"
        },
        "cardBrand": "VISA",
        "bin": "42424242",
        "lastFourDigits": "4242",
        "expirationMonth": "03",
        "expirationYear": "2018",
        "cardType": "CREDIT",
        "countryOfIssuance": "US",
        "cardBank": "Chase"
      }
    }
  },
}

Order Response

Outcome	Call to Action	Order Response Fields
Forter Approved Transaction APPROVED by Forter, 3DS was not recommended	Standard Authorization	`"action":"approve", "recommendations": []` In order to test such response, use the email address [email protected] in the accountOwner object within the API request.
Forter Declined Hard DECLINE by Forter, 3DS was not recommended	Do not Authorize	`"action":"decline"` `"recommendations": []` In order to test such response, use the the email address [email protected] in the accountOwner object within the API request.
Forter Declined & 3DS is recommended Borderline transaction which was DECLINED by Forter, and 3DS is recommended in order to APPROVE it	Authorize only following a successful 3DS	`"action":"decline"` `"recommendations": [VERIFICATION_REQUIRED_3DS_CHALLENGE]` 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.	According to the policies in place prior to the integration with Forter.	`"action":"not reviewed"` `"recommendations": []` In order to test such response, use the the email address [email protected] in the accountOwner object within the API request.

Additional Outcomes Applicable Only to PSD2 Solution

Outcome	Call to Action	Order Response Fields
Forter Approved & Recommended to ask PSD2 Exemption PSD2 transaction which was APPROVED by Forter, and Forter recommended to ask an exemption from 3DS (TRA or Low Value) in the Authorization request	Authorize with Exemption Request Please note that not all processors support all types of exemptions. Check with your PSP to determine which exemptions are supported. Forter will recommend specific exemptions only if they are supported by the processor specified in the Order Request.	`"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXEMPTION_TRA"` In order to simulate such Order Response, use the email [email protected] when calling the Order API and card number 5222220000000006 when calling the Init API OR `"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXEMPTION_LOW_VALUE"` In order to simulate such Order Response, use the email [email protected] when calling the Order API and card number 5222220000000006 when calling the Init API `"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXEMPTION_CORP"` In order to simulate such Order Response, use the email [email protected] when calling the Order API and card number 5222220000000006 when calling the Init API
Forter Approved & Recommended to ask PSD2 Exemption over the 3DS Rails PSD2 transaction which was APPROVED by Forter, and Forter recommended to ask an exemption from 3DS over the 3ds rails (TRA, Low Value, Corp), in the Authorization request	Authorize with Exemption-over-rails request Please note that not all processors support all types of exemptions. Check with your PSP to determine which exemptions	`"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXEMPTION_LOW_VALUE_EMVCO"` In order to simulate such Order Response, use the email [email protected] when calling the Order API and card number 5222220000000006 when calling the Init API `"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXEMPTION_TRA_EMVCO"` In order to simulate such Order Response, use the email [email protected])when calling the Order API and card number 5222220000000006 when calling the Init API `"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXEMPTION_CORP_EMVCO"` In order to simulate such Order Response, use the email [email protected] when calling the Order API and card number 5222220000000006 when calling the Init API
Forter Approved & 3DS is recommended PSD2 transaction which was APPROVED by Forter, and 3DS is recommended in order to comply PSD2	Authorize with 3DS request	`"action":"approve",` `"recommendations": [VERIFICATION_REQUIRED_3DS_CHALLENGE]` In order to test such response, use the email address [email protected] in the accountOwner object within the API request.
Forter Approved, transaction is excluded from PSD2 Exclusions do not require any call to action like exemptions, and the merchant is not required to include any specific value in the authorization request. They serve as informative indicators explaining the reason why the transaction is not considered for PSD2 solution, even if it involves an EU merchant and an EU consumer.	Standard Authorization The exclusion messages are informative only, no need to adjust your integration with the PSP	`"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXCLUSION_ANONYMOUS"` To simulate an Order Response with the "recommendation": "REQUEST_SCA_EXCLUSION_ANONYMOUS", use the card number 5222220000000006 when calling the Init APIand the email address: [email protected] when calling the Order API `"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXCLUSION_MOTO"` To simulate an Order Response with the "recommendation": "REQUEST_SCA_EXCLUSION_MOTO", use the card number 5222220000000006 when calling the Init API and the email address [email protected] when calling the Order API `"forterDecision": "APPROVE"` `"recommendation": "REQUEST_SCA_EXCLUSION_ONE_LEG_OUT"` To simulate an Order Response with the "recommendation": "REQUEST_SCA_EXCLUSION_ONE_LEG_OUT", use the card number 5222220000000006 when calling the Init API and the email address [email protected] when calling the Order API

Authorization

Authorization with 3DS Request

In order to pass the bank a request to trigger 3DS following Forter's recommendation in the Order Response, you should adjust your integration with the PSP and include 3DS request flag in the PSP Authorization request.

Contact your PSP to enable such a request (it is not always activated by default), and get their relevant Authorization API reference which explains how to trigger 3DS for transaction.

Adyen

Trigger 3DS by flagging the request in the Payment Request as explained in Adyen docs here.

Authorization with PSD2 Exemption

The following part is relevant only for PSD2 solution

Same as in 3DS Execution Integration. See here

Status API

Same as in 3DS Execution Integration. See here.

Claims API

Same as in 3DS Execution Integration. See here.