3D Secure: Orders API

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

On this page

• Know before you code
• How it works
• 3D Secure with Orders API
• Response parameters
• Next steps

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 may be 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 with Orders API

Step 1: Include a contingency for 3D Secure

Use the following code to request either SCA_ALWAYS or SCA_WHENEVER_REQUIRED as a verification attribute for the Card object. SCA_WHENEVER_REQUIREDreturns a 3D Secure contingency when it is a mandate in the region where you operate.

  "payment_source": {
    "card": {
      "number": "4111111111111111",
      "expiry": "2020-02",
      "name": "John Doe",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      },
      "attributes": {
        "verification": "SCA_WHEN_REQUIRED"
      }
    }
  }

Step result

A successful request returns a 201 Created status and a PAYER_ACTION_REQUIRED status that includes a HATEOS link.

Step 2: Launch authentication flow with HATEOS link

To trigger the authentication, redirect the payer to the "rel": "payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order.

Step 3: Buyer completes the authentication experience

Step 4: Get the 3D Secure authentication results

Use the authentication results to proceed with the transaction. PayPal recommends you verify the 3D Secure responses on the server side instead of the client side.

Sample request

"request": {

    "method": "GET",

    "path": "v2/checkout/orders/5O190127TN364715T?fields=payment_source",

    "headers": {

      "Authorization": "Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g"

    }

  },

  "response": {

    "status": "200 OK",

    "headers": {

      "Content-Type": "application/json"

    },

    "body": {

      "payment_source": {

        "card": {

          "type": "CREDIT",

          "brand": "VISA",

          "last_digits": "1111",

          "authentication_result": {

            "liability_shift": "POSSIBLE",

            "three_d_secure": {

              "enrollment_status": "Y",

              "authentication_status": "Y"

            }

          }

        }

      }

    }

  }

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.

Next steps

3D Secure test scenarios