3D Secure

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

On this page

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.
  • PayPal handles 3D Secure authentication for Standard Payments integrations. No changes are required for your integration.

How it works

This demo shows a checkout flow that triggers authentication with 3D Secure.

3D Secure demo

Enable 3D Secure in the advanced credit and debit cards integration

Step 1: Include a contingency for 3D Secure

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

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

Step 2: Update the advanced card fields 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",
                * "liabilityShift":  Possible,
                * }
                */

                // Needed only when 3D Secure contingency applied

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

                if (payload.liabilityShift) {
                     // Handle buyer confirmed 3D Secure successfully
                }
            });
        });
    });
}
else {
    /*
     * Handle experience when advanced credit and debit card payments
     * card fields are not eligible
     */
}

3D Secure response parameters

You can see the response of the 3D Secure flow by viewing the LiabilityShift, EnrollmentStatus, and AuthenticationResult fields in the payload returned to your client by your server.

  • LiabilityShift signals whether the issuing bank may accept liability for the transaction. If you've integrated with the JavaScript SDK, you receive the LiabilityShift parameter only. This is a client- and server-side parameter.
  • EnrollmentStatus shows whether the card type and issuing bank are ready to complete a 3D Secure authentication. This is a server-side parameter.
  • AuthenticationResult indicates the result of the authentication challenge. This is a server-side parameter.

LiabilityShift

Response Description
Possible Liability might shift to the card issuer.
No Liability is with the merchant.
Unknown The authentication system is not available.

EnrollmentStatus

Response Description
Y Card type and issuing bank are ready to complete a 3D Secure authentication.
N Card type and issuing bank are not ready to complete a 3D Secure authentication.
U System is unavailable at the time of the request.
B System has bypassed authentication.

AuthenticationResult

Response Description
Y Successful authentication.
N Failed authentication.
R Rejected authentication.
A Attempted authentication.
U Unable to complete authentication.
C Challenge required for authentication.
I Information only.
D Decoupled authentication.

Based on the results of EnrollmentStatus and AuthenticationResult, a LiabilityShift response is returned. The LiabilityShift response determines how you might proceed with authentication.

EnrollmentStatus AuthenticationResult LiabilityShift Recommended action
Y Y Possible Continue with authorization.
Y N No Do not continue with authorization.
Y R No Do not continue with authorization.
Y A Possible Continue with authorization.
Y U Unknown Do not continue with authorization. Request cardholder to retry.
Y U No Do not continue with authorization. Request cardholder to retry.
Y C Unknown Do not continue with authorization. Request cardholder to retry.
Y No Do not continue with authorization. Request cardholder to retry.
N No Continue with authorization.
U No Continue with authorization.
U Unknown Do not continue with authorization. Request cardholder to retry.
B No Continue with authorization.
Unknown Do not continue with authorization. Request cardholder to retry.

Note: Check with your acquirer for guidance with liability shift actions.

Deprecated 3D Secure parameters

Note: If you integrated 3D Secure prior to June 2020, the liabilityShifted, authenticationStatus, and AuthenticationReason parameters continue to work on the server, but are no longer supported.

liabilityShifted authenticationStatus AuthenticationReason Reason 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 3D Secure 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