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

3D Secure: Orders API

APICurrentLast updated: September 30th 2021, @ 5:56:39 pm


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.

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": {
             "verification": {
                "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.

Next steps

Test and go live

See also