3D Secure: Orders API
Standard payments and advanced credit and debit card payments processing includes support for providing customer authentication with 3D Secure.
On this page
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 with Orders API
Step 1: Include a contingency for 3D Secure
Use the following code to request either SCA_ALWAYS
or SCA_WHENEVER_REQUIRED
as a verification attribute for the Card object. SCA_WHENEVER_REQUIRED
returns a 3D Secure contingency when it is a mandate in the region where you operate.
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2020-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": "SCA_WHEN_REQUIRED"
}
}
}
Step result
A successful request returns a 201 Created status and a PAYER_ACTION_REQUIRED
status that includes a HATEOS link.
Step 2: Launch authentication flow with HATEOS link
To trigger the authentication, redirect the payer to the "rel": "payer-action"
HATEOAS link returned as part of the response prior to authorizing or capturing the order.
Step 3: Buyer completes the authentication experience
Step 4: Get the 3D Secure authentication results
Use the authentication results to proceed with the transaction. PayPal recommends you verify the 3D Secure responses on the server side instead of the client side.
Sample request
"request": {
"method": "GET",
"path": "v2/checkout/orders/5O190127TN364715T?fields=payment_source",
"headers": {
"Authorization": "Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g"
}
},
"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"
}
}
}
}
}
}
Response parameters
You can see the response of the 3D Secure flow by viewing the LiabilityShift
, EnrollmentStatus
, and AuthenticationResult
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 theLiabilityShift
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.AuthenticationResult
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. |
AuthenticationResult
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 AuthenticationResult
, a LiabilityShift
response is returned. The LiabilityShift
response determines how you might proceed with authentication.
EnrollmentStatus |
AuthenticationResult |
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. |