Checkout with 3DS
To leverage 3DS Execution, you must upgrade to v3 of the Order API endpoint and use a pre-authorization integration, calling Forter prior to calling your payment gateway to authorize customer funds.
Send Order API Request
The Order API is used to provide Forter with all relevant data points that will help Forter determine whether the entity conducting the transaction/engagement is legitimate or fraudulent. The full request and response data can be found in our Order API reference.
Include all Checkout Integration as well as additional details necessary for 3DS execution, including full card data, gateway, processor, acquirer details, etc.
Force Modes
You can opt to receive only a 3DS recommendation at the time of the transaction by specifying payment[0].creditCard.threeDSecure.threeDsExecutor = MERCHANT. In this case, if Forter decides to execute 3DS, it will only return the recommendation and will not initiate 3DS itself.
You can force Forter to execute or not-execute 3DS (i.e override Forter’s decision) by specifying payment[0].creditCard.threeDSecure.execute3ds: FORCE_3DS or payment[0].creditCard.threeDSecure.execute3ds: NOT_SUPPORTED_BY_MERCHANT. In any case, the decision to step up to a challenge is made by the issuer during 3DS execution, after data collection.
You can instruct Forter to indicate to the issuer that a challenge is preferable by specifying payment[0].creditCard.threeDSecure.requestChallenge: true. This will only take effect if 3DS is executed (either due to a Forter recommendation or because the you forced 3DS).
Handle Order API Response
Outcome Option 1: Continue the flow in the client side
The response will include managedOrderToken, which you should pass back to the client side. Follow the instructions for Checkout with 3DS After the process is completed on the client side you should call the 3DS result from your server.
Outcome Option 2: Process completed, handle response
In this path, you received the final results from Forter and there is no need to continue the process on the client side. The response will include a forterDecision that determines your next action.
Outcome | Call to Action | Order Response Fields |
|---|---|---|
Forter Approved Transaction is approved by Forter, 3DS was not executed | Standard Authorization | "forterDecision": "APPROVE" "verificationMethod": {} To simulate this response, use [email protected] in the accountOwner object in the Order API request. |
Forter Declined Transaction is declined by Forter, 3DS was not executed | Do not Authorize | "forterDecision": "DECLINE" "verificationMethod": {} To simulate this response, use [email protected] in the accountOwner object in the Order API request. |
Forter Did Not Review Transaction was not reviewed for a fraud decision. | Act according to policy prior to Forter integration | "forterDecision": "NOT REVIEWED" "recommendation": "" "verificationMethod": {} To simulate this response, use [email protected] in the accountOwner object in the Order API request. |
If you are using Forter's PSD2 recommendation service, the response may include a recommendation to request an exemption from PSD2 SCA when requesting payment authorization.
Outcome | Call to Action | Order Response Fields |
|---|---|---|
Forter Approved & Recommended to request an exemption from PSD2 Transaction is approved by Forter, 3DS was not executed, and Forter recommends asking for an exemption from 3DS (TRA or Low Value) when requesting payment authorization | Authorize with exemption request Please note that not all processors support all types of exemptions. 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" To simulate, use card number 5222220000000006 and [email protected] in the Order API request "forterDecision": "APPROVE" "recommendation": "REQUEST_SCA_EXEMPTION_LOW_VALUE" To simulate, use card number 5222220000000006 and [email protected] in the Order API request "forterDecision": "APPROVE" "recommendation": "REQUEST_SCA_EXEMPTION_CORP" To simulate, use card number 5222220000000006 and [email protected] in the Order API request. |
Forter Approved & Transaction is excluded from PSD2 Transaction is approved by Forter, 3DS was not executed, and the transaction is excluded from PSD2 requirements, even if it involves an EU merchant and an EU consumer. The exclusion recommendation serves as an informative indicator explaining the reason why the transaction is not considered for PSD2. | Standard Authorization The exclusion message is informative only, and you do not need to include any specific value in the payment authorization request. | "forterDecision": "APPROVE" "recommendation": "REQUEST_SCA_EXCLUSION_ANONYMOUS" To simulate, use card number 5222220000000006 and [email protected] in the Order API request. "forterDecision": "APPROVE" "recommendation": "REQUEST_SCA_EXCLUSION_MOTO" To simulate, use card number 5222220000000006 and [email protected] in the Order API Request. "forterDecision": "APPROVE" "recommendation": "REQUEST_SCA_EXCLUSION_ONE_LEG_OUT" To simulate, use card number 5222220000000006 and [email protected] in the Order API request. |
Client Side Handling of managedOrderToken
Incorporate Forter's client components into your website and application as explained in Front-end Integration for 3DS.
The managedOrderToken from the Order API response should be passed back to the client side for additional processing. The merchant client-side response handler should trigger Forter's checkoutTools.managedOrders.manageOrder(managedOrderToken, {challengeContainer: optionalChallengeContainer }, callback) JS function with the following inputs:
- managedOrderToken which was received from the server response
- callback merchant's JS function which will be called upon completion, and should be used to trigger 3DS result API request to receive the final fraud decision and 3ds results.
- {challengeContainer: optionalChallengeContainer }, where 3DS challenge will be rendered in case required.
IMPORTANT NOTE: In case 3DS execution is not possible, you will not receive managedOrderToken in the Order API response and can skip this step.
Callback Style
window.checkoutTools.managedOrders.manageOrder(
managedOrderToken,
{
challengeContainer: () => {
// render custom container for challenge modal if needed
return htmlElement; // can be null to render Forter's default modal
}
},
(error) => {
if (!error) {
// process is complete, call server to get results
}
},
);A promise based interface is also available
await window.checkoutTools.managedOrders.manageOrder(
managedOrderToken,
{
challengeContainer: () => {
// render custom container for challenge modal if needed
return htmlElement; // can be null to render Forter's default modal
}
},
);
// process is complete, call server to get results