3D Secure: Orders API

Know before you code

You may be subject to PSD2 regulations if you are in Europe. We recommend incorporating 3D Secure into your integration and providing the cardholder's billing address during transaction processing.
For standard payments integrations, PayPal manages 3D Secure authentication automatically, so you do not need to make any changes.
Use Postman to explore and test PayPal APIs.

Run in Postman

Explore PayPal APIs with Postman

Use Postman to explore and test PayPal APIs. Learn more in our Postman guide.

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 triggers 3D Secure for each 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 attribute is the default when you don't pass any parameter.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H "PayPal-Partner-Attribution-ID: BN-CODE" \
 -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
 -H "PayPal-Request-Id: PAYPAL-REQUEST-ID" \
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
            "amount": {
                "currency_code": "USD",
                "value": "100.00"
            }
        }
    ],
    "payment_source": {
        "card": {
            "number": "4868719460707704",
            "expiry": "2025-02",
            "security_code": "123",
            "name": "Firstname Lastname",
            "billing_address": {
                "address_line_1": "123 Main St.",
                "address_line_2": "Unit B",
                "admin_area_2": "Anytown",
                "admin_area_1": "CA",
                "postal_code": "12345",
                "country_code": "US"
            },
            "attributes": {
                "verification": {
                    "method": "SCA_ALWAYS"
                }
            }
        }
    }
}'

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.

2. Launch authentication flow with HATEOAS link

The merchant must redirect the payer 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

3. Buyer completes the authentication experience

The issuing bank verifies authentication.
The device data is collected, and JavaScript is posted directly to the issuing bank.

3DS Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/3TE883926L0940023?fields=payment_source \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H "PayPal-Partner-Attribution-ID: BN-CODE" \
 -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \

3DS Response

"response": {
  "status": "200 OK",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "payment_source": {
        "card": {
            "last_digits": "7704",
            "brand": "VISA",
            "type": "CREDIT",
            "authentication_result": {
                "liability_shift": "POSSIBLE",
                "three_d_secure": {
                    "enrollment_status": "Y",
                    "authentication_status": "Y"
                }
            }
        }
    }
}

4. Proceed with the transaction

After a buyer resolves the 3D Secure contingency thrown by the create order endpoint, the merchant or partner must call the authorize order and capture order endpoints with an empty payload to complete the transaction.

Multi-step API request

After a buyer resolves the 3D Secure contingency thrown by the authorize order and capture order endpoints, the merchant or partner must call the authorize order and capture order endpoints again with an empty payload to complete the transaction.

Next steps

Go live

Move from PayPal's production environment to go live.

Know before you code

You may be subject to PSD2 regulations if you are in Europe. We recommend incorporating 3D Secure into your integration and providing the cardholder's billing address during transaction processing.
For standard payments integrations, PayPal manages 3D Secure authentication automatically, so you do not need to make any changes.
Use Postman to explore and test PayPal APIs.

Run in Postman

Explore PayPal APIs with Postman

Use Postman to explore and test PayPal APIs. Learn more in our Postman guide.

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 triggers 3D Secure for each 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 attribute is the default when you don't pass any parameter.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H "PayPal-Partner-Attribution-ID: BN-CODE" \
 -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
 -H "PayPal-Request-Id: PAYPAL-REQUEST-ID" \
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
            "amount": {
                "currency_code": "USD",
                "value": "100.00"
            }
        }
    ],
    "payment_source": {
        "card": {
            "number": "4868719460707704",
            "expiry": "2025-02",
            "security_code": "123",
            "name": "Firstname Lastname",
            "billing_address": {
                "address_line_1": "123 Main St.",
                "address_line_2": "Unit B",
                "admin_area_2": "Anytown",
                "admin_area_1": "CA",
                "postal_code": "12345",
                "country_code": "US"
            },
            "attributes": {
                "verification": {
                    "method": "SCA_ALWAYS"
                }
            }
        }
    }
}'

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.

2. Launch authentication flow with HATEOAS link

The merchant must redirect the payer 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

3. Buyer completes the authentication experience

The issuing bank verifies authentication.
The device data is collected, and JavaScript is posted directly to the issuing bank.

3DS Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/3TE883926L0940023?fields=payment_source \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H "PayPal-Partner-Attribution-ID: BN-CODE" \
 -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \

3DS Response

"response": {
  "status": "200 OK",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "payment_source": {
        "card": {
            "last_digits": "7704",
            "brand": "VISA",
            "type": "CREDIT",
            "authentication_result": {
                "liability_shift": "POSSIBLE",
                "three_d_secure": {
                    "enrollment_status": "Y",
                    "authentication_status": "Y"
                }
            }
        }
    }
}

Go live

Move from PayPal's production environment to go live.

3D Secure: Orders API

Go live

Response parameters

Test scenarios

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

3D Secure: Orders API

Go live

Response parameters

Test scenarios

On this page

On this page