Overview

The purpose of this document is to provide guidelines for moving the integration with Forter from post authorization to pre authorization. Moving to Pre-Auth is a prerequisite for accessing 3DS services (see below), but getting 3DS services is optional.
The process consists of the two following phases:

1. Moving the Order Call to an earlier stage, and using the Forter V3 API instead of V2 API
   1. Order Request
   2. Getting Fraud Decision
   3. Optional Capabilities:
      1. Getting 3DS Recommendation
      2. Getting PSD2 Exemption Recommendation
      3. Getting 3DS Execution
2. Calling Status API after authorization

Moving the Order Call to an earlier stage

This stage includes moving the Order API Call to an earlier stage of the payment flow, from post to pre authorization. Calling Forter Order API should be done right before calling the PSP for authorization and before executing 3DS, ideally at a point where the routing is already known (unless the merchant wish Forter to decide with Forter Smart Routing), so the relevant MID can be provided in the call to Forter in case that 3DS Execution is implemented (see below).

Use Forter V3 API instead of V2 API

The following changes should be made in order to upgrade from V2 to v3

Order Request

1. Changing the called endpoint from api.forter-secure.com/v2/orders/{id} to api.forter-secure.com/v3/managed/orders/{id}. The request payload should remain the same.
2. Updating the API version to 2.X (as discussed with your support team)
3. Add authorizationStep field.
4. Send the same data as in the post auth order call, with the exception of:
   1. creditCard.verificationResults
   2. tokenizedCard.verificationResults
   3. paypal.paymentStatus
   4. applePay.verificationResults
   5. androidPay.verificationResults
   6. digitalWallet.paymentSuccessStatus
   7. installmentService.serviceResponseCode
   8. venmo.verificationResults
   9. bankTransfer.paymentSuccessStatus
   10. any paymentGatewayData or paymentProcessorData

Getting Fraud Decision

Order Request

Include in the request also the card BIN number & Last 4 digits. No need to include the card full number.

Handling Order Response

Forter fraud decision (APPROVE \ DECLINE \ NOT REVIEWED) is received in the decision field instead of an action field.

{
  "action": "approve"
}

{  
  "forterDecision": "APPROVE",  
}

If you are are guided to retain your Post-Authorization integration while adding Pre-Authorization integration (i.e., receiving fraud decisions both before and after authorization), you should take into account the Post-Authorization fraud decision only in the event of successful authorization, and in such case if Forter declined the transaction then you should void the authorization (otherwise no further action is required).

Getting 3DS Recommendation (Optional)

Handling Order Response

Forter recommendation (VERIFICATION_REQUIRED_3DS_CHALLENGE) is received in the recommendation string field, instead of the recommendations array field.

{  
  "action": "approve",  
  "recommendations": ["VERIFICATION_REQUIRED_3DS_CHALLENGE"]  
}

{  
  "forterDecision": "APPROVE",  
  "recommendation": "VERIFICATION_REQUIRED_3DS_CHALLENGE"  
}

Getting PSD2 Exemption Recommendation (Optional)

Handling Order Response

{  
  "action": "approve",  
  "recommendations": ["REQUEST_SCA_EXEMPTION_TRA"]  
}

{  
  "forterDecision": "APPROVE",  
  "recommendation": "REQUEST_SCA_EXEMPTION_TRA"  
}

Getting 3DS Execution (Optional)

This capability is available starting from V3 and requires the following.

Preliminary Prerequisites - are described here

Add Forter 3DS JS SDK to the checkout page, in addition to the Forter JS SDK. as described here

Add Acquirer Data to the Order Request the PSP, Acquirer and MID which will be used in authorization.

Add Forter 3DS Mobile SDK (optional) as described in the 3ds mobile sdk guides for IOS & Androind here.

Handling Order Response Consider the following possible outcomes:

1. No 3DS Act as explained above in Getting Fraud Decision.
2. PSD2 exemption recommendation (optional): Act as explained above in Getting PSD2 Exemption.
3. 3DS is being executed. The response will include mangedOrderToken field. Act as follow:
   1. Pass from your server to your frontend the mangedOrderToken.
   2. On your frontend
      1. Call window.checkoutTools.managedOrders.manageOrder(mangedOrderToken, container, callback) as described here .
      2. Once your JS callback is called in the frontend, call your server.
   3. On your server
      1. Call /v3/managed/orders/{id}/results API to get the final APPROVE \ DECLINE fraud decision alongside the 3DS Results (CAVV, ECI, dsTransID etc). See more here in full documentation.
      2. Include the 3DS results in the authorization request to your payment provider. See examples here.

Calling Status API after authorization (no decision)

Call Forter Status API after authorization for keeping Forter updated about the authorization results and order status (e.g cancellation). See more here in full documentation. Note this call will not return any decision and it's simply for the Forter feedback loop.

If you are already integrated with the Forter Status API, make sure to add the verificationResults object to the status request, which should include the 3DS and authorization results as received in the PSP Authorization Response.