About 3D Secure
3D Secure (3DS) is a security protocol used to authenticate a cardholder during online card transactions. When a cardholder spends above a certain threshold, they'll be prompted to verify their identity. If they fail to authenticate or abandon the process, then the transaction will not proceed.
Why it matters
3DS helps you reduce the risk of fraud and comply with local regulations. It's part of Strong Customer Authentication (SCA), a requirement under the Revised Payment Services Directive (PSD2) that applies to transactions in the European Economic Area (EEA), Monaco, and the UK. It typically applies to transactions above €30.00 or £30.00.
How it works
When a cardholder initiates a transaction above the threshold, you'll be notified via the 3DSAuthRequest
webhook.
You’ll need to present the cardholder with their issuing bank's Access Control Server (ACS) screen to complete authentication (e.g., OTP or biometric verification).
Once the cardholder completes or fails authentication, you'll send the result to the v2/cards/3ds
endpoint with one of the following outcomes:
Outcome | Description |
---|---|
SUCCESS |
The cardholder successfully completed the authentication process. |
FAILED |
The cardholder failed the authentication process and their identity wasn't verified. For example, if they entered the wrong code. |
CANCELLED |
The cardholder cancelled the authentication process. |
NOT_AUTHENTICATED |
The cardholder failed to complete the authentication process. For example, due to a timeout. |
If your request is successful, we'll return a 200
response and the transaction will continue. The final outcome will be sent via the CardTransaction
webhook containing a transaction.response.code
. View a list of possible response codes.
Testing 3DS in sandbox
We provide a 3DS simulation in our sandbox environment which allows you to test your 3DS integration before going live.
Sandbox Testing Steps
-
Simulate Transaction Initiation
Trigger a test transaction that requires 3DS using
v2/cards/simulations/3DSAuthRequest
endpoint. -
Receive 3DSAuthRequest Webhook
You will receive the
3DSAuthRequest
webhook. -
Send Authentication Outcome
Post the result to
v2/cards/3ds
usingSUCCESS
,FAILED
,CANCELLED
, orNOT_AUTHENTICATED
.
info
Interaction with a real ACS (OTP or biometric entry) is not available in sandbox. This step is mocked by submitting the authentication outcome directly.