Integration Guides

Pre Auth Order API

The Pre Auth Order API is called after the 3DS Initialization

Suggest Edits

Order API Overview

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

The request should be sent after the 3DS Initialization and before calling the payment gateway to authorize funds (Pre-Auth).

The response includes Forter's fraud decision, along with 3DS results (if executed), to be included in 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 instead of providing 3DS execution results.

Step 1 - Server Side: Implement an endpoint for calling Forter Order API

Order Request

To call the Forter Order API in this endpoint, please provide all relevant data points that will aid Forter in determining whether the transaction or engagement is legitimate or fraudulent. This may include details such as account information, cart items, billing, delivery, and more. Additionally, some data points are necessary for 3DS execution, such as gateway, processor, acquirer, and so on.

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.

The request should contain the following values from the 3DS Init response:

initResponse.correlationId -> orderRequest.payment[0].creditCard.creditCardCorrelationId
initResponse.threeDSServerTransID -> orderRequest.payment[0].creditCard.threeDSecure.threeDSServerTransID

// Native Challenge
initResponse.threeDSEncodedMobileAppSDKData -> orderRequest.payment[0].creditCard.threeDSecure.threeDSEncodedMobileAppSDKData

Required parameters for Native Challenge

The threeDSEncodedMobileAppSDKData field is found under payment[0].creditCard.threeDSecure, next to threeDSServerTransID. It is needed to show native challenges as part of the 3DS protocol. We send this data directly to the issuer during 3DS. Without it, we can only show challenges through a web or WebView interface.

Example of threeDSecure attribute

"threeDSecure": {
  "threeDSServerTransID": "e9097990-d994-4579-b5e2-bdcf23cd98d8",
  "threeDSEncodedMobileAppSDKData": "eyJzZGtSZWZlcmVuY2VOdW1iZXIiOiIzRFNfTE9BX1NES1=="
}

Example of full 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

OutcomeCall to ActionOrder Response Fields
Forter Approved

Transaction APPROVED by Forter, 3DS was not executed		Standard Authorization"forterDecision": "APPROVE"
"verificationMethod": {}
In order to simulate such Order Response, use the email address [email protected] in the accountOwner object within the API request.
Forter Approved & 3DS was executed successfully

Borderline transaction which was APPROVED by Forter only following successful 3DS

OR

Transaction which was APPROVED by Forter, and Frictionless 3DS was executed successfully in order to shift liability

OR

PSD2 transaction which was APPROVED by Forter, 3DS was executed in order to comply PSD2 and succeeded		Authorize with 3DS results"forterDecision": "APPROVE"
"verificationMethod": { "status": "FRICTIONLESS"}

In order to simulate such Order Response, use card number 5222220000000005 when calling the Init API

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "ATTEMPTED"}

In order to simulate such Order Response, use card number 4111110000001142 when calling the Init API
Forter Approved & 3DS was executed unsuccessfully

PSD2 transaction which was APPROVED by Forter, 3DS was executed in order to comply PSD2 regulation and failed		Do not Authorize"forterDecision": "APPROVE"
"verificationMethod": { "status": "FRICTIONLESS_NOT_AUTHENTICATED"}

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "FRICTIONLESS_BANK_REJECT"}

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "FRICTIONLESS_TECHNICAL_ISSUE"}

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "NETWORK_ERROR"}

In order to simulate such Order Response, use card number 5248481111200179 when calling the Init API
Forter Approved & 3DS was executed & SCA (challenge) is required

PSD2 transaction which was APPROVED by Forter, 3DS was executed in order to comply PSD2 regulation and resulted in a requirement to display 3DS challenge		Continue to 3DS Challenge Phase"forterDecision": "APPROVE" "verificationMethod": { "status": "CHALLENGE_REQUESTED"}
Forter Declined & 3DS was executed & SCA (challenge) is required

Borderline transaction, 3DS was executed in order to APPROVE it by Forter, and resulted in a requirement to display 3DS challenge		Continue to 3DS Challenge Phase"forterDecision": "DECLINE" "verificationMethod": { "status": "CHALLENGE_REQUESTED"}

In order to simulate such Order Response, use card number 5111220000000009 when calling the Init API
Forter Declined

Hard DECLINE by Forter, 3DS was not executed		Do not Authorize"forterDecision": "DECLINE" "verificationMethod": {}

In order to simulate such Order Response, use the email address [email protected] in the accountOwner object within the API request.
Forter Declined & 3DS was executed unsuccessfully

Borderline transaction which was DECLINED by Forter following unsuccessful 3DS		Do not Authorize"forterDecision": "DECLINE"
"verificationMethod": { "status": "FRICTIONLESS_NOT_AUTHENTICATED"}

In order to simulate such Order Response, use card number 4000000000001992 when calling the Init API

OR

"forterDecision": "DECLINE" "verificationMethod": { "status": "FRICTIONLESS_BANK_REJECT"}

In order to simulate such Order Response, use card number 5200000000000031 when calling the Init API

OR

"forterDecision": "DECLINE" "verificationMethod": { "status": "FRICTIONLESS_TECHNICAL_ISSUE"}

In order to simulate such Order Response, use card number 5200000000001336 when calling the Init API

OR

"forterDecision": "DECLINE" "verificationMethod": { "status": "NETWORK_ERROR"}
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 ForterIn order to simulate such Order Response, use the email address [email protected] in the accountOwner object within the API request.
Forter Approved, Frictionless 3DS was attempted unsuccessfully

Transaction APPROVED by Forter, Frictionless 3DS attempted to shift liability, but wasn't completed successfully.		Standard Authorization

The messages are informative only, no need to adjust your integration with the PSP		"forterDecision": "APPROVE" "verificationMethod": { "status": "CHALLENGE_REQUESTED_BYPASSED"}

To simulate such Order Response, use the card number 4138490000000000 when calling the Init API and the email address [email protected] when calling the Order API

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "ATTEMPTED_BYPASSED"}

To simulate such Order Response, use the card number 5248480000200068 when calling the Init API and the email address [email protected] when calling the Order API

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "FRICTIONLESS_NOT_AUTHENTICATED_BYPASSED"}

To simulate such Order Response, use the card number 4407900000000002 when calling the Init API and the email address [email protected] when calling the Order API
Forter Approved, Mastercard IDCI was executed

Transaction APPROVED by Forter, and IDCI was executed to share Forter's risk score with Mastercard		Authorize with IDCI Results"forterDecision": "APPROVE" "verificationMethod": { "status": "DATA_ONLY"}

Additional Outcomes Applicable Only to PSD2 Solution

OutcomeCall to ActionOrder Response Fields
Forter Approved & Recommended to ask PSD2 Exemption

PSD2 transaction which was APPROVED by Forter, 3DS was not executed, 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 & and successfully executed PSD2 Exemption over 3DS rails

PSD2 transaction which was APPROVED by Forter, Forter decided to ask an exemption from 3DS Authentication (TRA or Low Value) via the 3DS protocol without any friction, and the request was approved by the ACS. 		Authorize with 3DS Results{ "forterDecision": "APPROVE", "recommendation": "", "verificationMethod": { "status": "EXEMPTED", "verificationSpecificData": { "ThreeDS": { "threeDSServerTransID": "eaf1dc38-a24f-442b-861b-a46bf91353ce", "version": "2.2.0", "ECIValue": "07", "authenticationValue": "ApkBBDFxKAAAAJvml4J3dWgDEHY=", "cardEnrolled": "Y", "transStatus": "I", "challengeStatus": "I", "dsTransID": "fae1ff8f-b895-4887-bc2e-df182bad0052" }
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

Step 2 - Client Side: Call your Server Side

After implementing the endpoint on your server side in Step 1, it should be called from your client side after the 3DS initialization and before authorizing funds on the payment gateway ; e.g when the consumer presses 'Pay' after filling the card details.

Example of calling your server side with the card number in payment event:

const onCheckoutClick = async (fullCreditCard, threeDSServerTransID) => {
    const 3DSResults = await axios.post("/api/order_3ds", {fullCreditCard, threeDSServerTransID});
    console.log(
        `Forter decision: ${3DSResults.data.forterDecision}.`,
        `Status: ${3DSResults.data.verificationMethod.status}`
    )

Updated 3 months ago