3DS Integration Guide

Integrating the 3DSecure in the Forter Cartridge

In order to integrate with 3DS recommendations, merchants will need to modify their ForterOrder.ds file to handle a new "recommendation" field in the response body as well as to pass additional 3DS authorization response data in the post-authorization request body.

1. Updates to API Schema

Once you've confirmed a 3DS integration with your dedicated Forter Implementations team, they will modify the schema to include additional fields in the request body payment[0].creditCard object and enable the exposure of a "recommendations" key in the response object returned by Forter in the pre-authorization call.

Your Implementation team will direct you to the relevant API version and you can specify which version you should point to in the cartridge in the cartridges > int_forter > cartridge > scripts > init > forterServiceInit.js file of your cartridge by modifying the default Option .86 in svc.addHeader("api-version", "Option .86");

2. Enable Pre-Auth

Go to the CheckoutServices.js file in your Forter Cartridge. The exact path to this file is: Cartridges > int_forter_sfra > cartridge > controllers > CheckoutService.js.

Open this file and uncomment the following code AFTER the var order = COHelpers.createOrder(currentBasket); function and BEFORE the var handlePaymentResult = COHelpers.handlePayments(order, order.orderNo); function in the file.

'use strict';

var server = require('server');
server.extend(module.superModule);

var COHelpers      = require('*/cartridge/scripts/checkout/checkoutHelpers');
var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
var ForterConfig   = require('int_forter_mfra/cartridge/scripts/lib/forter/ForterConfig.ds').ForterConfig;

server.replace('PlaceOrder', server.middleware.https, function (req, res, next) {
    var BasketMgr = require('dw/order/BasketMgr');
    var HookMgr = require('dw/system/HookMgr');
    var OrderMgr = require('dw/order/OrderMgr');
    var Resource = require('dw/web/Resource');
    var Transaction = require('dw/system/Transaction');
    var URLUtils = require('dw/web/URLUtils');
    var basketCalculationHelpers = require('*/cartridge/scripts/helpers/basketCalculationHelpers');

    var currentBasket = BasketMgr.getCurrentBasket();

    if (!currentBasket) {
        res.json({
            error: true,
            cartError: true,
            fieldErrors: [],
            serverErrors: [],
            redirectUrl: URLUtils.url('Cart-Show').toString()
        });
        return next();
    }

    if (req.session.privacyCache.get('fraudDetectionStatus')) {
        res.json({
            error: true,
            cartError: true,
            redirectUrl: URLUtils.url('Error-ErrorCode', 'err', '01').toString(),
            errorMessage: Resource.msg('error.technical', 'checkout', null)
        });

        return next();
    }

    var validationBasketStatus = HookMgr.callHook(
        'app.validate.basket',
        'validateBasket',
        currentBasket,
        false
    );

    if (validationBasketStatus.error) {
        res.json({
            error: true,
            errorMessage: validationBasketStatus.message
        });
        return next();
    }

    // Check to make sure there is a shipping address
    if (currentBasket.defaultShipment.shippingAddress === null) {
        res.json({
            error: true,
            errorStage: {
                stage: 'shipping',
                step: 'address'
            },
            errorMessage: Resource.msg('error.no.shipping.address', 'checkout', null)
        });
        return next();
    }

    // Check to make sure billing address exists
    if (!currentBasket.billingAddress) {
        res.json({
            error: true,
            errorStage: {
                stage: 'payment',
                step: 'billingAddress'
            },
            errorMessage: Resource.msg('error.no.billing.address', 'checkout', null)
        });
        return next();
    }

    // Calculate the basket
    Transaction.wrap(function () {
        basketCalculationHelpers.calculateTotals(currentBasket);
    });

    // Re-validates existing payment instruments
    var validPayment = COHelpers.validatePayment(req, currentBasket);
    if (validPayment.error) {
        res.json({
            error: true,
            errorStage: {
                stage: 'payment',
                step: 'paymentInstrument'
            },
            errorMessage: Resource.msg('error.payment.not.valid', 'checkout', null)
        });
        return next();
    }

    // Re-calculate the payments.
    var calculatedPaymentTransactionTotal = COHelpers.calculatePaymentTransaction(currentBasket);
    if (calculatedPaymentTransactionTotal.error) {
        res.json({
            error: true,
            errorMessage: Resource.msg('error.technical', 'checkout', null)
        });
        return next();
    }

    // Creates a new order.
    var order = COHelpers.createOrder(currentBasket);
    if (!order) {
        res.json({
            error: true,
            errorMessage: Resource.msg('error.technical', 'checkout', null)
        });
        return next();
    }
    // add or uncomment the new pre-auth code here:
    var argOrderValidate = {
                Order: order,
                orderValidateAttemptInput: 1
            },
            forterController = require('int_forter/cartridge/controllers/ForterValidate'),
            forterDecision   = forterController.ValidateOrder(argOrderValidate);
        // in case if no response from Forter, try to call one more time
        if (forterDecision.result === false && forterDecision.orderValidateAttemptInput == 2) {
            var argOrderValidate = {
                    Order: order,
                    orderValidateAttemptInput: 2
                },
                forterController = require('int_forter/cartridge/controllers/ForterValidate'),
                forterDecision   = forterController.ValidateOrder(argOrderValidate);
        }
        
        if (forterDecision.JsonResponseOutput.processorAction == 'void') {
            if (!empty(forterDecision.PlaceOrderError)) {
                return {error : true, forterErrorCode : forterDecision.PlaceOrderError};
            } else {
                return {error : true};
            }
        }  
        // end of pre-auth code

    var handlePaymentResult = COHelpers.handlePayments(order, order.orderNo);     // Handles payment authorization
    if (handlePaymentResult.error) {
        if (ForterConfig.forterShowDeclinedPage == true && !empty(ForterConfig.forterCustomDeclineMessage)) {
            res.json({
                error: true,
                errorMessage: ForterConfig.forterCustomDeclineMessage
            });
        } else {
            res.json({
                error: true,
                errorMessage: Resource.msg('error.technical', 'checkout', null)
            });
        }
        return next();
    }
    
    var fraudDetectionStatus = HookMgr.callHook('app.fraud.detection', 'fraudDetection', currentBasket);
    if (fraudDetectionStatus.status === 'fail') {
        Transaction.wrap(function () { OrderMgr.failOrder(order); });

        // fraud detection failed
        req.session.privacyCache.set('fraudDetectionStatus', true);

        res.json({
            error: true,
            cartError: true,
            redirectUrl: URLUtils.url('Error-ErrorCode', 'err', fraudDetectionStatus.errorCode).toString(),
            errorMessage: Resource.msg('error.technical', 'checkout', null)
        });

        return next();
    }

    // Places the order
    var placeOrderResult = COHelpers.placeOrder(order, fraudDetectionStatus);
    if (placeOrderResult.error) {
        res.json({
            error: true,
            errorMessage: Resource.msg('error.technical', 'checkout', null)
        });
        return next();
    }

    COHelpers.sendConfirmationEmail(order, req.locale.id);

    // Reset usingMultiShip after successful Order placement
    req.session.privacyCache.set('usingMultiShipping', false);

    // TODO: Exposing a direct route to an Order, without at least encoding the orderID
    //  is a serious PII violation.  It enables looking up every customers orders, one at a
    //  time.
    res.json({
        error: false,
        orderID: order.orderNo,
        orderToken: order.orderToken,
        continueUrl: URLUtils.url('Order-Confirm').toString()
    });

    return next();
});


module.exports = server.exports();

3. Update your Business Manager

The additional code that you have added above to your CheckoutServices.js file allows your storefront to send order information to the Forter endpoint BEFORE an authorization call is made to your payment gateway.

You will also need to update your Forter Business Manager extension to show a customized error message (in cases of decline) for this updated Pre-Authorization Flow.

4. Handle Recommendations

You will need to add logic in your Forter SFCC cartridge to handle the new, "recommendation" field that will be included in the Forter response for orders that require 3DS.

Merchants should make sure to include logic to handle all possible iterations of both the decisions and recommendations within their Forter cartridge (ForterValidate.js) and within their gateway cartridge to ensure that orders are correctly routed after receiving a pre-authorization decision and recommendation from Forter.

In the case of 3DS for regulation, the Forter pre-Authorization decision ("action") will be an "approve" along with a populated "recommendations" field.

In the case of 3DS for risk assessment, the Forter pre-Authorization decision ("action") will be a "decline" along with a populated "recommendations" field

In your SFCC cartridge, go to the forterValidate file, cartridges/int_forter_sfra/cartridge/scripts/pipelets/forter/forterValidate.js and add logic to handle both the decision and recommendation in cases where the recommendation field is populated with a value other than an empty string ("").

Possible Recommendation values are:

"VERIFICATION_REQUIRED_3DS_CHALLENGE"

"" (when Forter does NOT recommend any 3DS or Exemption due to clear Approve)

"REQUEST_SCA_EXCLUSION_MOTO"

"REQUEST_SCA_EXCLUSION_PREPAID"

"RECOMMENDATION_REQUEST_SCA_EXCLUSION_ONE_LEG_OUT"

"REQUEST_SCA_EXCLUSION_ONE_LEG_OUT"

"REQUEST_SCA_EXCLUSION_MIT"

"REQUEST_SCA_EXEMPTION_TRA"

"RECOMMENDATION_REQUEST_SCA_EXEMPTION_LOW_VALUE"

"REQUEST_SCA_EXEMPTION_LOW_VALUE"

"REQUEST_SCA_EXEMPTION_CORP"

"RECOMMENDATION_REQUEST_SCA_EXEMPTION_TRUSTED_BENEFICIARY"

"REQUEST_SCA_EXEMPTION_TRUSTED_BENEFICIARY"

The logic should be modified within the validateOrder(args) function around line 137 where the current options and logic for handling decisions and response body fields is located:

    if (fResponse.actionEnum === 'DECLINED' && fResponse.recommendation[0] === undefined) { // modify accordingly
        if (sitePrefs.forterCancelOrderOnDecline === true) {
            fResponse.processorAction = 'void';
            if (sitePrefs.forterShowDeclinedPage === true && sitePrefs.forterCustomDeclineMessage) {
                resp.PlaceOrderError = {
                    code: sitePrefs.forterCustomDeclineMessage
                };
            }
        } else {
            fResponse.processorAction = 'skipCapture';
        }
    } else if (fResponse.actionEnum === 'NOT_REVIEWED') {
        fResponse.processorAction = 'notReviewed';
    } else if (fResponse.actionEnum === 'APPROVED' && fResponse.recommendation[0] == "") { // add logic to handle recommendation field when no rec is given
        fResponse.processorAction = sitePrefs.forterAutoInvoiceOnApprove ? 'capture' : 'skipCapture';
    } else if (fResponse.actionEnum === 'APPROVED' && fResponse.recommendation[0] != "REQUEST_SCA_EXEMPTION_LOW_VALUE") { //logic to handle/store 3DS rec for exemption
    fResponse.processorAction = sitePrefs.initiate3DSChallenge //were initiate3DSChallenge is a custom setting added to your dw site 'dw/system/Site'
    } else if (fResponse.actionEnum === 'DECLINED' && fResponse.recommendation[0] != "VERIFICATION_REQUIRED_3DS_CHALLENGE") { //logic to handle/store 3DS recommendation 
    fResponse.processorAction = sitePrefs.initiate3DSChallenge //were initiate3DSChallenge is a custom setting added to your dw site 'dw/system/Site'
    }

5. Code Modifications to payment Gateway Cartridge

As seen in the above example, you'll need to modify your SFCC site preferences dw > system > Site to handle the new "recommendations" field in the response body. In the example above, the fucntionality is called initiate3DSChallenge. This functionality should allow your SFCC platform to accept a recommendation and trigger a 3DS challenge from your payment gateway.

Each gateway has different 3DS challenge requirements and configurations. It will be incumbant on each merchant to handle the integration of the recommendation into their gateway and configure the relevant 3DS challenge to a customer based on the recommendation provided by Forter.

6. Post-Auth Options

For a second, synchronous post-auth decision, you will need to update the mapping in your ForterOrder.ds file to include the authorization and 3DS response data from your gateway and make sure your ForterValidate.js file also handles the second post-auth Forter decision.

For an post-auth order status call without a new Forter decision ("action"), you'll modify the ForterUpdate.js job and authorization response mapping in the corresponding ForterPayment() function.

Option 1: Post-Auth Validation Call

After the gateway has successfully initiated 3DS and authorized payment (or rejected payment), the results should be included in the post-authorization call to the Forter cartridge. These fields should be added to the ForterCreditCard(auth, cc) function mapping of your ForterOrder.ds file. This flow is applicable for merchants who may not be receiving a Forter payment recommendation (3DS or PSD2) but want to provide Forter's models with the payments outcome from their processor.

function ForterCreditCard(auth, cc) {
    var processorResponseCode = '';
    var processorResponseText = '';
    var creditCardExpMonth;

    // format the expiration month. from 1 to 01, etc.
    if (cc.creditCardExpirationMonth.toString().length === 1) {
        creditCardExpMonth = '0' + cc.creditCardExpirationMonth.toString();
    } else {
        creditCardExpMonth = cc.creditCardExpirationMonth.toString();
    }

    this.nameOnCard = cc.creditCardHolder;
    this.cardBrand = cc.creditCardType;

    if (cc.creditCardNumber.substring(0, 6).indexOf('*') > -1) {
        this.bin = session.forms.billing.creditCardFields.cardNumber.value.substring(0, 6); // session.forms.billing.paymentMethods.creditCard.number.value.substring(0, 6);
    } else {
        this.bin = cc.creditCardNumber.substring(0, 6);
    }

    this.lastFourDigits = cc.creditCardNumberLastDigits;
    this.expirationMonth = creditCardExpMonth;
    this.expirationYear = cc.creditCardExpirationYear.toString();

    this.verificationResults = {};
    this.verificationResults.avsFullResult = auth ? auth.avsResultCode.toString() : '';  
    this.verificationResults.cvvResult = auth ? auth.cvvResultCode.toString() : ''; 
    this.verificationResults.authorizationCode = auth ? auth.authCode.toString() : '';

    // ******************************** new 3DS response data ********************************    
    this.verificationResultsauthorizationPolicy =  "3DSecure", //can be hardcoded
    this.verificationResults.cavvResult = auth.body ? replyMessage.decisionEarlyReply.rcode,
    this.verificationResults.eciValue auth.body ? auth.payerAuthValidationReply.eciRaw,
    this.verificationResults.threeDsStatus = auth.payerAuthValidationReply.authenticationMessage || '',
    this.verificationResults.threeDsStatusCode = auth.payerAuthValidationReply.authenticationStatusCodeRaw || '',
    this.verificationResults.threeDsStatusReasonCode = auth.body.status,
    this.liabilityShift = auth.payerAuthValidationReply ? true : false, //should be a boolean value
    threeDsVersion = auth.payerAuthValidationRepl.auth.version
    this.verificationResults.threeDsInteractionMode = "FRICTIONLESS", // modify according to 3ds used
    this.verificationResults.threeDsChallengeCancelCode = replyMessage.decisionEarlyReply.challengeCodeNumeric || '',
    this.verificationResults.authenticationChallengeStartTime = new Number((order.header.Timestamp/1000).toFixed()); , // should be timestamp as int in unix format
    this.verificationResults.authenticationTriggered =  auth.payerAuthValidationReply ? true : false, //should be a boolean value
    this.verificationResults.external3dsVendorPayload =  {}, // optional
    this.verificationResults.external3dsVendorPayloadBeforeChallenge =  {}, // optional 
    this.verificationResults.authenticationMethodType = "THREE_DS", // can be hardcoded if this is the only auth method
    this.verificationResults.authorizationProcessedWith3DS =  auth.payerAuthValidationReply ? true : false, //should be a boolean value
    this.verificationResults.partyExecuted3DS =  "PSP" // add relevant vendor(s)
    // **************************** end of new 3DS response data ***************************
    },
    this.paymentGatewayData = {};
    this.paymentGatewayData.gatewayName = 'AUTHORIZE.NET';                   
    this.paymentGatewayData.gatewayTransactionId = auth ? auth.transId.toString() : '';  

    if (auth && auth.errors.errorCode.length > 0) {                            
        processorResponseCode = auth.errors.errorCode.toString();      
        processorResponseText = auth.errors.errorText.toString();      
    } else if (auth && auth.messages.code.length > 0) {                        
        processorResponseCode = auth.messages.code.toString();         
        processorResponseText = auth.messages.description.toString();  
    }

    this.verificationResults.processorResponseCode = processorResponseCode;
    this.verificationResults.processorResponseText = processorResponseText;
}

Option 2: Post-Auth Order Status Call

Step 1: Include Post-Auth Status Update script The example Authorize.net script below outlines how to update the script that handles credit card processing so that it includes the relevant post-authorization and 3DS order status call to Forter. Note that the two default order statuses are:

"PROCESSING" (when the gateway has authorized the payment)

"CANCELED_BY_MERCHANT" (when the gateway/processor has NOT authorized payment)

The code example below applies to all SFRA and SG pre-auth/status implementations and the full postAuthOrderStatusUpdate() function can be found in forterValidate.js file (cartridges > int_forter_sfra > cartridge > scripts > pipelets > forter > forterValidate.js)


    var argOrderUpdate = { 
        orderNumber: orderNumber,
        updateAttempt: 1 
    },
    forterCall = require('*/cartridge/scripts/pipelets/forter/forterValidate'),
    forterDecision = forterCall.postAuthOrderStatusUpdate(argOrderUpdate, "PROCESSING");

    if (forterDecision.result === false && forterDecision.updateAttempt == Option ) { 
        forterDecision.updateAttempt = Option ; 
        forterCall.postAuthOrderStatusUpdate(argOrderUpdate, "PROCESSING");
    }

Step 2: Customize ForterUpdate.js file After uncommenting the pre-auth code CheckoutServices.js file, customize the forterUpdate.js file to include your gateway's authorization AND 3DS response in the status call to Forter. The exact path to the forterUpdate.js file is cartridges > int_forter_sfra > cartridge > scripts > lib > forter > dto > forterUpdate.js). Customize the ForterPayment(payment, order) function to map your specific gateway authorization response.

```javascript

function ForterCreditCard(auth, cc) {
    var processorResponseCode = '';
    var processorResponseText = '';
    var creditCardExpMonth;

    // format the expiration month. from 1 to 01, etc.
    if (cc.creditCardExpirationMonth.toString().length === 1) {
        creditCardExpMonth = '0' + cc.creditCardExpirationMonth.toString();
    } else {
        creditCardExpMonth = cc.creditCardExpirationMonth.toString();
    }

    this.nameOnCard = cc.creditCardHolder;
    this.cardBrand = cc.creditCardType;

    if (cc.creditCardNumber.substring(0, 6).indexOf('*') > -1) {
        this.bin = session.forms.billing.creditCardFields.cardNumber.value.substring(0, 6); // session.forms.billing.paymentMethods.creditCard.number.value.substring(0, 6);
    } else {
        this.bin = cc.creditCardNumber.substring(0, 6);
    }

    this.lastFourDigits = cc.creditCardNumberLastDigits;
    this.expirationMonth = creditCardExpMonth;
    this.expirationYear = cc.creditCardExpirationYear.toString();

    this.verificationResults = {};
// ******************************** new 3DS response data ********************************    
    this.verificationResultsauthorizationPolicy =  "3DSecure", //can be hardcoded
    this.verificationResults.cavvResult = auth.body ? replyMessage.decisionEarlyReply.rcode,
    this.verificationResults.eciValue auth.body ? auth.payerAuthValidationReply.eciRaw,
    this.threeDsStatus = auth.payerAuthValidationReply.authenticationMessage || '',
    this.threeDsStatusCode = auth.payerAuthValidationReply.authenticationStatusCodeRaw || '',
    this.threeDsStatusReasonCode = auth.body.status,
    this.liabilityShift = auth.payerAuthValidationReply ? true : false, //should be a boolean value
    this.threeDsVersion = auth.payerAuthValidationRepl.auth.version
    this.threeDsInteractionMode = "FRICTIONLESS", // modify according to 3ds used
    this.threeDsChallengeCancelCode = replyMessage.decisionEarlyReply.challengeCodeNumeric || '',
    this.authenticationChallengeStartTime = new Number((order.header.Timestamp/1000).toFixed()); , // should be timestamp as int in unix format
    this.authenticationTriggered =  auth.payerAuthValidationReply ? true : false, //should be a boolean value
    this.external3dsVendorPayload =  {}, // optional
    this.external3dsVendorPayloadBeforeChallenge =  {}, // optional 
    this.authenticationMethodType = "THREE_DS", // can be hardcoded if this is the only auth method
    this.authorizationProcessedWith3DS =  auth.payerAuthValidationReply ? true : false, //should be a boolean value
    this.partyExecuted3DS =  "PSP"

    this.verificationResults.avsFullResult = auth ? auth.avsResultCode.toString() : '';    
    this.verificationResults.cvvResult = auth ? auth.cvvResultCode.toString() : ''; 
    this.verificationResults.authorizationCode = auth ? auth.authCode.toString() : '';    
    this.paymentGatewayData = {};
    this.paymentGatewayData.gatewayName = 'AUTHORIZE.NET';                
    this.paymentGatewayData.gatewayTransactionId = auth ? auth.transId.toString() : '';  

    if (auth && auth.errors.errorCode.length > 0) {                            
        processorResponseCode = auth.errors.errorCode.toString();      
        processorResponseText = auth.errors.errorText.toString();      
    } else if (auth && auth.messages.code.length > 0) {                        
        processorResponseCode = auth.messages.code.toString();         
        processorResponseText = auth.messages.description.toString();  
    }

    this.verificationResults.processorResponseCode = processorResponseCode;
    this.verificationResults.processorResponseText = processorResponseText;
    }   
};