3D Secure (3DS) adds a cardholder authentication step, such as a one-time passcode or banking-app approval, to online card payments. Under the Payment Services Directive 2 (PSD2), Strong Customer Authentication (SCA) is often required for online transactions in the European Union and European Economic Area (EU/EEA), and similar rules apply in the UK. Outside these regions, 3DS is optional but can reduce fraud.
This module builds on what you’ve already done. You’ll add 3DS to the transactions you sent in Module 4, then include it in the go-live steps from Module 5.
By the end of this module, you will be able to:
- Choose the 3DS option that fits your gateways and payment flow
- Explain how 3DS changes the transaction flow you built in Module 4
- Test 3DS in sandbox and add it to your go-live checklist from Module 5
How 3DS Changes Your Transactions
In Module 4, you sent transactions and got a final result back right away. 3DS works differently in three ways:
- It’s opt-in. 3DS only runs when you flag a transaction for it, even on gateways that support it. If you flag a transaction but the gateway doesn’t support 3DS, it’s processed normally without 3DS.
-
It’s asynchronous. A 3DS transaction can return a
pendingstate while Spreedly collects device information and, if the issuer requires it, the cardholder completes a challenge. Your integration must wait for the final result, using thecallback_urlyou send on the transaction and the events from your frontend (Checkout SDK or iFrame). This is a new state to handle alongside the ones covered in Module 4. - Your frontend has a role. The Checkout SDK or iFrame shows the issuer’s challenge on your page and sends browser information, which PSD2 requires.
Everything else from Module 4 still applies: save the transaction token, use the transcript to troubleshoot, and ignore response fields you don’t recognize. 3DS responses include extra authentication fields.
Choosing a 3DS Option
Spreedly offers three 3DS options:
| 3DS2 Global (recommended) | 3DS2 Gateway Specific | Third Party 3DS2 | |
|---|---|---|---|
| Who authenticates | Spreedly’s connected 3DS server | Your gateway’s 3DS server | Your own external 3DS provider |
| Works across gateways | Yes, with any supported gateway that accepts external 3DS results | No, only with the gateway that authenticated | Yes, with supported gateways |
| How you flag a transaction | sca_provider_key |
attempt_3dsecure |
Pass your provider’s authentication values on the transaction |
| Best for | Multi-gateway setups and orchestration | A single gateway with its own 3DS service | Organizations that already use a 3DS provider |
1. 3DS2 Global: Spreedly’s Recommended Option
3DS2 Global gives you one 3DS integration across many gateways. Spreedly runs the authentication through its connected 3DS server, and you can use the result at any supported gateway. If you route between gateways, as in a Composer workflow, this keeps 3DS working no matter which gateway processes the payment.
Setup has two parts:
- Create a Merchant Profile with your merchant details for each card brand: Merchant ID (MID), merchant name, country, Merchant Category Code (MCC), and URL.
- Create an SCA Provider using the Merchant Profile and your acquirer BIN for each card brand. The SCA Provider key is what you send on transactions.
Start gathering these details early. The MID, MCC, and acquirer BINs come from your gateway or acquiring bank, and getting them can take time. See How to get the ABIN and MID from your gateway.
Guides for your frontend:
- Checkout SDK (Hosted Fields or Express Checkout): 3DS with the Checkout SDK. Requires Checkout SDK 1.0.0 or later.
- Native mobile apps: 3DS2 Global Mobile
- Full setup: 3DS2 Global guide
2. 3DS2 Gateway Specific
You authenticate through your gateway’s own 3DS server. This suits you if you process with one gateway and want to use its 3DS service. The limitation is that the authentication result only works with that gateway, so it’s less flexible if you use several.
If you use the Checkout SDK, Gateway Specific 3DS2 requires version 1.1.0 or later. See the Gateway Specific 3DS2 guide.
3. Third Party 3DS2
If you already use an external 3DS provider, you can pass the authentication values it returns on a normal transaction to a supported gateway. Spreedly doesn’t run the authentication. See the Third Party 3DS2 guide.
Testing 3DS in Sandbox
As in Module 4, test everything in sandbox first. For 3DS2 Global:
- Create a test SCA Provider (
"type": "test","sandbox": true) and run the test scenarios in Testing your 3DS2 Global integration. - Test every outcome, not just success: frictionless approval, frictionless failure, a completed challenge, and a failed or abandoned challenge. Your integration must handle each one.
- Confirm your callback URL receives the final result, and that your frontend shows the challenge correctly.
Going Live with 3DS
Add these to your go-live checklist from Module 5:
- For 3DS2 Global, create a production SCA Provider (
"type": "spreedly") and wait one hour before using it on live transactions. The 3DS server needs that time to register your details with the card brands - Your production transactions use the production SCA Provider key, and your callback URL points to production
- Your Content Security Policy (CSP) allows the 3DS provider script (
script-src https://plugins.spreedly.com) and the issuer’s challenge frame, withframe-src https:and matchingform-actionandconnect-src. If you allow only Spreedly’s domains, tokenization works but 3DS silently fails in production. See Securing iFrame or Checkout SDK - After launch, check Success Rates and Failures in Reports (Module 5) for drops caused by failed authentications
Getting Help
Review the guide for your chosen option closely before you start. The 3DS2 Global FAQs answer common questions. For anything else, contact your Account Manager or Customer Support, and include the details listed in Module 5’s “Getting help” section.
Module Checklist
You’ve completed Module 6 when you have:
- Chosen a 3DS option for your organization
- Gathered your MID, MCC, and acquirer BINs (3DS2 Global)
- Tested every 3DS outcome in sandbox, including challenges and failures
- Confirmed your integration handles the
pendingstate and receives the final result - Added the 3DS items to your go-live checklist