3D Secure: Orders API
Standard payments and advanced credit and debit card payments processing includes support for providing customer authentication with 3D Secure.
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.
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": {
"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.
2: Launch authentication flow with HATEOS link
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
- The issuing bank verifies authentication.
- 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.
Response parameters
You can see the response of the 3D Secure flow by viewing the LiabilityShift
, EnrollmentStatus
, and Authentication_Status
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.Authentication_Status
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. |
Authentication_Status
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 Authentication_Status
, a LiabilityShift
response is returned. The LiabilityShift
response determines how you might proceed with authentication.
EnrollmentStatus |
Authentication_Status |
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. |