Marketplaces and Platforms / Accept Payments / Checkout / 3D Secure / Orders API

3D Secure: Orders API


Standard payments and 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 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 demo

1: Include a contingency for 3D Secure

Use the following code to request either SCA_ALWAYS or SCA_WHEN_REQUIRED as a verification attribute for the card object.

  • SCA_ALWAYS trigger 3D Secure for every transaction, regardless of SCA requirements.
  • SCA_WHEN_REQUIRED returns a 3D Secure contingency when it is a mandate in the region where you operate. This is the default when neither parameter is explicitly passed.
"request": {
    "method": "POST",
    "path": "v2/checkout/orders/5O190127TN364715T/authorize",
    "headers": {
      "PayPal-Request-Id": "7b92603e-77ed-4896-8e78-5dea2050476a",
      "Authorization": "Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g"
    },
    "body": {
      "payment_source": {
        "card": {
          "number": "4111111111111111",
          "expiry": "2010-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": {
            "method": "SCA_WHEN_REQUIRED"
          }
        }
      }
    }
  },

Step result

  • A single-step payment request returns an HTTP 201 Created status.
  • A multi-step payment request returns an HTTP 422 Unprocessable Entity status.
  • A confirm order request returns an HTTP 200 OK status.

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

3: Buyer completes the authentication experience

  1. The issuing bank verifies authentication.
  2. Device data is collected and JavaScript is posted directly to issuing bank.

3DS request

"request": {

  "method": "GET",

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

  "headers": {

    "Authorization": "Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g"

  }

},

3DS response

"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"
          }
        }
      }
    }
  }
}
}

4: Proceed with the transaction

Single-step API request

After the 3D Secure contingency is thrown during create order response and contingency is resolved by the buyer, the merchant or partner must invoke the authorize order and capture order endpoints with an empty payload to complete the transaction.

Multi-step API request

After the 3D Secure contingency is thrown during authorize order and capture order response and contingency is resolved by the buyer, the merchant or partner must invoke the authorize order and capture order endpoints again with an empty payload to complete the transaction.

Response parameters

You can see the response of the 3D Secure flow by viewing the LiabilityShift, EnrollmentStatus, and Authentication_Status 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.
  • Authentication_Status 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.

Authentication_Status

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 Authentication_Status, a LiabilityShift response is returned. The LiabilityShift response determines how you might proceed with authentication.

EnrollmentStatus Authentication_Status 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