# 3D Secure: Orders API (/platforms/checkout/advanced/customize/3d-secure/api)



## Know before you code [#know-before-you-code]

* You may be subject to [PSD2 regulations](https://www.paypal.com/uk/webapps/mpp/PSD2) 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 [#run-in-postman]

> **Info:** ### Explore PayPal APIs with Postman [#explore-paypal-apis-with-postman]
>
> Use Postman to explore and test PayPal APIs. Learn more in our [Postman guide](/api/rest/postman/).

## 1. Include a contingency for 3D Secure [#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.

```text lineNumbers
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 [#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 [#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 [#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 [#3-buyer-completes-the-authentication-experience]

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

### 3DS Request [#3ds-request]

```text lineNumbers
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 [#3ds-response]

```text lineNumbers
"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 [#4-proceed-with-the-transaction]

### Single-step API request [#single-step-api-request]

After a buyer resolves the 3D Secure contingency thrown by the [create order](/api/orders/v2/orders-create) endpoint, the merchant or partner must call the [authorize order](/api/orders/v2/orders-authorize) and [capture order](/api/orders/v2/orders-capture) endpoints with an empty payload to complete the transaction.

### Multi-step API request [#multi-step-api-request]

After a buyer resolves the 3D Secure contingency thrown by the [authorize order](/api/orders/v2/orders-authorize) and [capture order](/api/orders/v2/orders-capture) endpoints, the merchant or partner must call the [authorize order](/api/orders/v2/orders-authorize) and [capture order](/api/orders/v2/orders-capture) endpoints again with an empty payload to complete the transaction.

## Next steps [#next-steps]

> **Info:** Go live
>
> Move from PayPal's production environment to go live.

## See also [#see-also]

> **Info:** Response parameters
>
> Learn more about 3D Secure response parameters

> **Info:** Test scenarios
>
> Generate 3D Secure responses for various card testing scenarios in the PayPal sandbox