3D Secure: Orders API

DOCSCURRENTADVANCED

Last updated: Feb 27th, 7:37am

Enable 3D Secure for advanced credit and debit cards. This integration uses Orders API.

Info: PayPal handles 3D Secure authentication for standard payment integrations. No changes are required for standard integrations.

Know before you code

Required
If you are based in Europe, you may be subject to PSD2:

Include 3D Secure as part of your integration.
Pass the cardholder's billing address as part of the transaction processing.

Optional
Explore PayPal APIs with Postman

You can use Postman to explore and test PayPal APIs. Learn more in our Postman guide.

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.

1"request": {
2      "method": "POST",
3      "path": "v2/checkout/orders/5O190127TN364715T/authorize",
4      "headers": {
5        "PayPal-Request-Id": "7b92603e-77ed-4896-8e78-5dea2050476a",
6        "Authorization: Bearer <Access-Token>"
7      },
8      "body": {
9        "payment_source": {
10          "card": {
11            "number": "4111111111111111",
12            "expiry": "2010-02",
13            "name": "John Doe",
14            "billing_address": {
15              "address_line_1": "2211 N First Street",
16              "address_line_2": "17.3.160",
17              "admin_area_1": "CA",
18              "admin_area_2": "San Jose",
19              "postal_code": "95131",
20              "country_code": "US"
21            },
22            "attributes": {
23              "verification": {
24                  "method": "SCA_WHEN_REQUIRED"
25            }
26            }
27          }
28        }
29      }
30    },

Step result

            Request
            Result
        
            Single-step payment request
            HTTP 201 Created
        
            Multi-step payment request
            HTTP 422 Unprocessable Entity
        
            Confirm order request
            HTTP 200 OK

Request	Result
Single-step payment request	HTTP `201 Created`
Multi-step payment request	HTTP `422 Unprocessable Entity`
Confirm order request	HTTP `200 OK`

Launch authentication flow with HATEOAS link

The merchant needs to redirect the payer back to PayPal to complete 3D Secure authentication.

To trigger the authentication:

Redirect the buyer to the "rel": "payer-action" HATEOAS link returned as part of the response before authorizing or capturing the order.

Append "redirect_uri" to the payer-action URL so that PayPal returns the payer to the merchant's checkout page after they complete 3D Secure authentication.

Sample URL

https://example.com/webapp/myshop?action=verify&flow=3ds&cart_id=ORDER-ID&redirect_uri=MERCHANT-LANDING-PAGE

Buyer completes authentication

The issuing bank verifies authentication.

Device data is collected, and JavaScript is posted directly to the issuing bank.

3DS request
3DS response

1"request": {
2  "method": "GET",
3  "path": "v2/checkout/orders/5O190127TN364715T?fields=payment_source",
4  "headers": {
5    "Authorization: Bearer <Access-Token>"
6  }
7},

Proceed with the transaction

Single-step API request

After the 3D Secure contingency is thrown during the 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 the 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.