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

  1. Simulate Transaction Initiation

    Trigger a test transaction that requires 3DS using v2/cards/simulations/3DSAuthRequest endpoint.

  2. Receive 3DSAuthRequest Webhook

    You will receive the 3DSAuthRequest webhook.

  3. Send Authentication Outcome

    Post the result to v2/cards/3ds using SUCCESS, FAILED, CANCELLED, or NOT_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.