What is 3DS?
Strong Customer Authentication (SCA) regulation in Europe requires the use of 3D Secure (3DS) for card payments.
3DS requires customers to complete an additional verification step with the card issuer when paying. If challenged, we direct the customer to an authentication page served by their bank, and they enter a password associated with the card or a code sent to their phone.
Configure 3D Secure for your Primer account
At Primer, we've decoupled 3D Secure from any underlying processor. Configure 3D Secure in your workflow, and Universal Checkout will handle the rest, presenting a fully in-context and optimized 3D Secure flow to your customer on web and mobile. Now you're SCA-ready with a unified checkout across all your payments services including 3D Secure 2.0.
Primer supports Dynamic 3DS to improve conversion, enabling you to present 3D Secure to customers only when it's absolutely required.
If your card processor does not support third-party 3D Secure, Primer seamlessly redirects the user to the processor's 3DS challenge page instead.
Set up the workflow for 3D Secure
Configuring 3DS settings for your payments takes place within the "Authorize payment" Action. Learn more here about how to set up a workflow to process payments.
In the configuration panel, you need to choose which 3DS option you want for all payments processed by this Action block:
No 3DS
3D Secure will not be used for any payments processed by this block. Payments will be declined when the Issuer requires authentication.
Adaptive 3DS
Use Primer’s proprietary Adaptive 3DS which will only carry out 3DS authentication if the payment would be declined without it.
Primer 3DS
3D Secure authentication will be handled by Primer's agnostic 3D Secure solution for payments processed by this block. This could either be a challenge or frictionless.
Processor 3DS
Your processor will present a 3DS challenge according to their configuration. This isn't compatible with Fallbacks as Primer is not involved in the flow.
Configure your Client Session
To improve 3DS success rates, it is recommended to pass the following elements in the Client Session:
Field | Description |
---|---|
The customer's email address | |
The customer's billing address |
In Sandbox, the email address and billing address must be provided to trigger 3DS.
Handle 3D Secure in Universal Checkout
Install Primer3DS SDK
3D Secure on iOS requires the addition of the Primer3DS
library to your project.
With CocoaPods
First, modify your Podfile
like so:
12345678910
source 'https://github.com/CocoaPods/Specs.git'source 'https://github.com/primer-io/primer-podspecs.git' use_frameworks! target 'PrimerSDK_Example' do pod 'PrimerSDK' pod 'Primer3DS' // ...end
Then run pod install
to install Primer3DS
on your workspace.
In case you encounter an error that the bundle needs signing on Xcode 14, add the following post-install script in your podfile.
123456789
post_install do |installer| installer.pods_project.targets.each do |target| if target.respond_to?(:product_type) and target.product_type == "com.apple.product-type.bundle" target.build_configurations.each do |config| config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO' end end endend
In case you notice the warning "WARNING! Failed to import Primer3DS" when you initialize the PrimerSDK
, add the following post-install script in the end of your pod file.
1234567891011121314151617
target 'MyApp' do pod 'PrimerSDK' pod 'Primer3DS' # ... # This is what needs to be added post_install do |installer| installer.pods_project.targets.each do |target| if target.name == "PrimerSDK" target.build_configurations.each do |config| config.build_settings['OTHER_LDFLAGS'] = '$(inherited) -framework "Primer3DS"' end end end endend
With Swift Package Manager
To add PrimerSDK with Swift Package Manager;
- 1Select your project, and then navigate to
Package Dependencies
- 2Click on the + button at the bottom-left of the
Packages
section - 3Paste https://github.com/primer-io/primer-sdk-3ds-ios into the Search Bar
- 4Press Add Package
- 5Let Xcode download the package and set everything up
If Primer3DS
is not installed, 3DS will fail. In the case of a 3DS triggered by the workflow, the primerDidFailWithError
functions will be called.
Handle Out-of-Band (OOB) redirects (Optional)
Starting from 3D Secure protocol version 2.2.0, you can enhance the user experience by implementing an automatic redirect from another (authentication) application during an OOB challenge to your application once the challenge is successfully completed. This feature allows for a seamless transition and improved user flow.
If this feature is not implemented, the user will have to come back to your application manually to complete their payment, which adds significant friction.
To enable this feature, ensure that you include the threeDsAppRequestorUrl
parameter when configuring the PrimerThreeDsOptions
object.
Please note that the threeDsAppRequestorUrl
value must be an iOS Universal Link.
Additionally, it is essential that your application is configured to handle the Universal Link properly in order to facilitate the redirection.
To configure the Universal Link correctly using Universal Checkout, follow these steps:
- 1
Pass your Universal Link (e.g.
https://{UNIVERSAL_LINK}
) asthreeDsAppRequestorUrl
in thePrimerThreeDsOptions
object of your settings.123456789
let settings = PrimerSettings( // ... paymentMethodOptions: PrimerPaymentMethodOptions( threeDsOptions: PrimerThreeDsOptions( threeDsAppRequestorUrl: "https://{UNIVERSAL_LINK}" ), ), // ...)
swiftcopy - 2
Implement the
application(_:continue:restorationHandler:) -> Bool
in yourAppDelegate
and callPrimer.shared.application(_:continue:restorationHandler:)
function.123456789101112
import PrimerSDKimport UIKit @UIApplicationMainclass AppDelegate: UIResponder, UIApplicationDelegate { // ... func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool { return Primer.shared.application(application, continue: userActivity, restorationHandler: restorationHandler) }}
swiftcopy - 3
Implement the
application(_:open:options:) -> Bool
in yourAppDelegate
and callPrimer.shared.application(_:continue:restorationHandler:)
function.123456789101112
import PrimerSDKimport UIKit @UIApplicationMainclass AppDelegate: UIResponder, UIApplicationDelegate { // ... func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { return Primer.shared.application(app, open: url, options: options) }}
swiftcopy
Execute 3D Secure
Universal Checkout drop-in and headless automatically render the 3DS challenge when required by your workflow.
If your application is not installed from a trusted source (e.g. a debug version, not installed from the store, or used on an simulator), try to set
PrimerDebugOptions.is3DSSanityCheckEnabled
to false
.
Otherwise 3D Secure library initialization will fail due to security checks being performed.
is3DSSanityCheckEnabled
flag should only be used in development mode, and not in production release of your app.
1234567
let settings = PrimerSettings( // ... debugOptions: PrimerDebugOptions( is3DSSanityCheckEnabled: false ) // ...)
Troubleshooting
- If you notice a console warning "Failed to import Primer3DS" on the SDK initialization, go to Scheme settings and select
Manual order
.
Test 3D Secure
Go Live
Before going live with 3D Secure, your account has to be configured for each of your processor.
To do so, please get in touch with your contact at Primer with the following information:
- Acquirer Merchant ID
- ARN (Acquirer reference number) - per card scheme
For Amex - this is referred to as the Amex SE number (Service entity) - Merchant Category Code