;

3D Secure

Advanced credit and debit card payments processing includes support for providing customer authentication with 3D Secure.

Use 3D Secure to authenticate card holders through card issuers. It reduces the likelihood of fraud when you use supported cards and improves transaction performance. A successful 3D Secure authentication can shift liability for fraudulent chargebacks from the merchant to the card issuer.

3D Secure authentication is performed only if the card is enrolled for the service. When your customer submits their card details on your website for processing, you have the option of triggering 3D Secure. When triggered, customers are prompted by their card issuing bank to complete an additional verification step to enter a one-time or static password, depending on the implementation.

Know before you code

If you are based in Europe, you are subjected to PSD2. PayPal recommends that you include 3D Secure as part of your integration and also pass the cardholder's billing address as part of the transaction processing.

1. Include contingency

Include a div element with payments-sdk__contingency-lightbox that follows your card payments card form.

<div id="payments-sdk__contingency-lightbox"></div>

2. Update code

To trigger the authentication, pass a contingencies parameter with 3D_SECURE as the value where you submit the advanced credit and debit card payments instance.

 // Check eligibility for advanced credit and debit card payments
if (paypal.HostedFields.isEligible()) {
    // render the card fields
    paypal.HostedFields.render({

         // sample function to return the order ID
        createOrder: () => {
            // add logic to return an order ID from your server
        },
        fields: {
            number: {
                selector: '#card-number',
                placeholder: 'card number'
            },
            cvv: {
                selector: '#cvv',
                placeholder: 'CVV',
            },
            expirationDate: {
                selector: '#expiration-date',
                placeholder: 'mm/yyyy'
            }
        }
    }).then(function (hf) {

        document.querySelector('#my-sample-form').addEventListener('submit', (event) => {
            event.preventDefault();

            hf.submit({

                 // Trigger 3D Secure authentication
                contingencies: ['3D_SECURE']

            }).then(function (payload) {

                /** sample payload
                * {
                * "orderId": "0BS14434UR665304G",
                * "liabilityShifted":       true,
                * "authenticationStatus":   "YES",
                * "authenticationReason":   "SUCCESSFUL"
                * }
                * possible value:
                * liabilityShifted - true, false, undefined
                * authenticationStatus - "YES", "NO", "ERROR", undefined
                * authenticationReason - "SUCCESSFUL", "ATTEMPTED", "BYPASSED", "UNAVAILABLE", "ERROR", "CARD_INELIGIBLE", "SKIPPED_BY_BUYER", "FAILURE", undefined
                */

                // Needed only when 3D Secure contingency applied

                if (payload.liabilityShifted === undefined) {
                     // Handle no 3D Secure contingency passed scenario
                }

                if (payload.liabilityShifted) {
                     // Handle Buyer confirmed 3D Secure successfully
                }

                if (payload.authenticationReason === 'SKIPPED_BY_BUYER') {
                     // Handle buyer skipped 3D Secure use-case
                }
            });
        });
    });
}
else {
    /*
     * Handle experience when advanced credit and debit card payments
     * card fields are not eligible
     */
}

You can see the outcome of the 3D Secure flow by looking at the liabilityShifted, authenticationStatus, and authenticationReason fields in the payload returned to your client. Here are the possible outcome values:

Liability shifted Authentication status Authentication reason Description Next steps
undefined undefined undefined You have not required 3D Secure for the buyer or the card network did not require a 3D Secure You can continue with authorization and assume liability. If you prefer not to assume liability, ask the buyer for another card
true YES SUCCESSFUL Buyer successfully authenticated using 3D secure Buyer authenticated with 3DS and you can continue with the authorization
false ERROR ERROR An error occurred with the 3D Secure authentication system Prompt the buyer to re-authenticate or request for another form of payment
false NO SKIPPED_BY_BUYER Buyer was presented the 3D Secure challenge but chose to skip the authentication Do not continue with current authorization. Prompt the buyer to re-authenticate or request buyer for another form of payment
false NO FAILURE Buyer may have failed the challenge or the device was not verified Do not continue with current authorization. Prompt the buyer to re-authenticate or request buyer for another form of payment
false NO BYPASSED 3D Secure was skipped as authentication system did not require a challenge You can continue with the authorization and assume liability. If you prefer not to assume liability, ask the buyer for another card
false NO ATTEMPTED Card is not enrolled in 3D Secure. Card issuing bank is not participating in 3D Secure Continue with authorization as authentication is not required
false NO UNAVAILABLE Issuing bank is not able to complete authentication You can continue with the authorization and assume liability. If you prefer not to assume liability, ask the buyer for another card
false NO CARD_INELIGIBLE Card is not eligible for 3D Secure authentication Continue with authorization as authentication is not required

In scenarios where liabilityShifted was either false or undefined, you have the option to complete the payment at your own risk, meaning that the liability of any chargeback has not shifted from the merchant to the card issuer.

Next steps

Test and go live