Configure 3D Secure for your Primer account
Follow the below process to start using 3DS on sandbox immediately. Do note that for 3DS to work in production, you will need to complete the process described in step 4.
To get 3DS configured and running, you need to:
- 1Set up your workflow
- 2Configure your Client Session
- 3Handle 3DS in Universal Checkout
- 4Onboard your 3DS profile to go live
1. Set up your workflow
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
3DS 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
3DS authentication will be handled by Primer's agnostic 3DS 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.
2. Configure your Client Session
You need to pass the following field in POST/client-session:
| Field | Description | Required |
|---|---|---|
| The customer's email address | Yes |
To improve 3DS success rates, it is recommended to pass the following field in POST/client-session:
| Field | Description | Required |
|---|---|---|
| The customer's billing address | Recommended |
In Sandbox, both the email address and billing address must be provided to trigger 3DS.
3. Handle 3DS in Universal Checkout
Install 3DS SDK
There are no additional requirements to enable 3D Secure on Web. You are all set to create a payment with 3D Secure!
Execute 3D Secure
Universal Checkout drop-in and headless automatically renders the 3DS challenge when required by your workflow.
4. Onboard your 3DS profile to go live
Before going live with 3DS on Primer, your account has to be configured with your 3DS profile(s). This 3DS profile consists of the following fields for each card network:
- Acquirer Merchant ID (MID)
- Acquirer BIN
- Merchant Category Code (MCC)
Please reach out to us directly via our Service Desk to configure this. If you don’t have access, please contact your account administrator for assistance.
Test 3D Secure
Monitor 3DS
You can monitor 3DS on Primer in three main ways:
- Payment status update webhook
- Payments API
- Payment timeline
1. Payment status update webhook
Subscribe to the payment status update webhook to receive notification updates each time your payment changes status.
As part of the webhook body, the threeDSecureAuthentication object is included detailing the outcome. Below is an example of this object for a successful 3DS authentication:
12345
{ "responseCode": "AUTH_SUCCESS", "protocolVersion": "2.2.0", "challengeIssued": true}
2. Payments API
Using Primer's Payments API, you can retrieve the payment object, where the threeDSecureAuthentication object is included detailing the outcome. This is available in the GET/payments/{paymentId} request, alongside POST/payments.
Below is an example for an unsuccessful 3DS authentication:
1234567
{ "responseCode": "AUTH_FAILED", "reasonCode": "CARD_AUTHENTICATION_FAILED", "reasonText": "Card Authentication Failed", "protocolVersion": "2.1.0", "challengeIssued": true}
3. Payment timeline
You can see all your Primer payments from the Payments timeline in the Primer Dashboard.
Navigate to the specific payment detailed timeline page. You will see the 3DS authentication event. Select this event to open the side drawer that contains the data tied to this 3DS event.
