Spreedly 3DS2 Global Implementation Guide

This guide walks you through implementing 3DS2 authentication using Spreedly's global solution. Before starting, review the Introduction to Spreedly 3DS2 Global for background information.

Introduction

3D Secure (3DS) is an authentication protocol developed by EMVco that adds an extra layer of security to online credit card transactions through two-factor authentication. While this additional security step can create friction in the checkout process, it's often required for regulatory compliance and fraud prevention.

How 3D Secure Works with Spreedly

Spreedly's implementation of 3D Secure is designed to be flexible and optional. Here are the key concepts you need to understand:

3D Secure is Opt-In

• 3D Secure authentication is completely optional, even when using gateways that support it
• You must explicitly flag transactions to enable 3D Secure processing
• If a transaction is flagged but processed through a gateway that doesn't support 3D Secure, it will still be processed normally (without 3DS)

Asynchronous Processing Required

• 3D Secure transactions use an asynchronous flow that differs from standard payment processing
• You cannot simply enable a setting to make 3D Secure work—your application must be specifically designed to handle the asynchronous workflow
• The flow is similar to standard transactions but requires additional integration steps

Compliance and Requirements

This guide will help you implement and test the necessary flows to prepare your payment application for:

• Payment Services Directive 2 (PSD2) requirements
• 3D Secure 2.0 (3DS2) authentication flows

If you have questions not covered in this integration guide, please contact Spreedly support for assistance.

Supported Card Brands

Spreedly 3DS2 Global currently supports:

• Visa
• MasterCard
• Amex
• Discover
• Diners
• JCB
• Dankort
• Union Pay
• Cartes Bancaires

Prerequisites

Before implementing 3DS2, ensure you have:

1. Updated iFrame version: Use iframe-v1, iframe-candidate, iframe-stable, or version above v1.177. Follow the iFrame Payment Form guide for setup.

2. Payment Method Token: Create one using either:

   • iFrame Payments Form
   • Payment Methods API

3. Frontend 3DS2 Support: Your frontend must handle asynchronous 3DS2 flows.

Implementation Steps

Step 1: Create a Merchant Profile

A Merchant Profile contains your merchant information for each card brand you want to support. See Merchant Profile API reference for more details.

How-to Guide

In order to process transactions using Spreedly’s 3DS2 solution and help identify which merchant is requesting authentication, Spreedly has created an entity called a Merchant Profile that allows customers to save merchant information. This also generates an SCA Provider Key, another entity from Spreedly that allows customers to make 3DS2 Authentication transactions and holds the credentials required for Spreedly to interact with a 3DS2 server.

Required Fields to Configure a Merchant Profile

There is a required set of data fields that are needed per card network to generate 3DS credentials per merchant. You will need to gather this information before proceeding with creating the Merchant Profile:

• Merchant ID (“MID”) - The Merchant ID is assigned by each payment gateway. Be aware that the field name may vary per gateway. Contact your payment gateway provider if needed.
• Merchant Name - The Merchant Name is the legal name of your organization.
• Merchant Country - The Merchant Country must be listed in ISO 3166-1 Numeric format. Some examples include United Kingdom of Great Britain and Northern Ireland (826), Switzerland (756), Netherlands (528), and Germany (276).
• Merchant MCC - The Merchant Category Code (MCC) is configured and provided by your payment gateway provider. The time to set up an MCC varies according to your payment gateway process. Refer to this Spreedly article for additional details.
• Merchant URL - The Merchant URL is your organization’s website. If you have multiple URLs, choose the one that best represents your organization.
• Merchant Password - Optional: The Merchant Password is not required when configuring your Merchant Profile.
• Acquirer BIN per Card Brand - The Bank Identification Number is assigned by your acquirer, i.e. merchant bank.

Please contact your banking institution if needed. Currently, Spreedly supports Visa, MasterCard, Amex, Discover, Diners, JCB, Dankort, Union_Pay, and Cartes_Bancaires for 3DS2 transactions.

📘

Note: For help obtaining Merchant Profile fields, see our Merchant Profile Onboarding Support Guide

API Request

curl https://core.spreedly.com/v1/merchant_profiles.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "merchant_profile": {
          "description": "Spreedly",
          "visa": {
            "acquirer_merchant_id": "spreedlys_mid",
            "merchant_name": "Spreedly",
            "country_code": "840",
            "mcc": "5978"
          },
          "mastercard": {
            "acquirer_merchant_id": "spreedlys_mid",
            "merchant_name": "Spreedly",
            "country_code": "840",
            "mcc": "5978"
          },
          "amex": {
            "acquirer_merchant_id": "spreedlys_mid",
            "merchant_name": "Spreedly",
            "country_code": "840",
            "mcc": "5978"
          },
          "discover": {
            "acquirer_merchant_id": "spreedlys_mid",
            "merchant_name": "Spreedly",
            "country_code": "840",
            "mcc": "5978"
          },
          "diners":{
            "acquirer_merchant_id": "spreedlys_mid",
            "merchant_name": "Spreedly",
            "country_code": "840",
            "mcc": "5978"
          }
        }
      }'

Response

The response includes a token field - save this as your merchant_profile_key:

{
  "merchant_profile": {
    "token": "LXeWiT9QNMPbLeZC7Z86ep4xh6s",
    "description": "Spreedly",
    "created_at": "2023-05-31T19:28:04Z",
    "updated_at": "2023-05-31T19:28:04Z",
    "sub_merchant_key": null,
    "card_networks": {
      "visa": {
        "acquirer_merchant_id": "spreedlys_mid",
        "mcc": "5978",
        "merchant_name": "Spreedly",
        "country_code": "840"
      },
      "mastercard": {
        "acquirer_merchant_id": "spreedlys_mid",
        "mcc": "5978",
        "merchant_name": "Spreedly",
        "country_code": "840"
      }
      // ... other card networks
    }
  }
}

Step 2: Create an SCA Provider

Using your merchant_profile_key, create an SCA Provider to handle 3DS2 authentication.

Key Parameters

• type: Use test for integration testing or spreedly for production
• merchant_password and merchant_brand_id: Optional fields
• sandbox: Set to true for testing environments

💡

Tip: Start with a Test SCA Provider to validate your integration. See Testing your 3DS2 Global Integration for test scenarios.

API Request

curl https://core.spreedly.com/v1/sca/providers.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "sca_provider": {
          "merchant_profile_key": "LXeWiT9QNMPbLeZC7Z86ep4xh6s",
          "type": "test",
          "sandbox": true,
          "mastercard": {
            "acquirer_bin": "4444444444",
            "merchant_url": "https://spreedly.com",
            "merchant_password": "optional"
          },
          "visa": {
            "acquirer_bin": "4444444444",
            "merchant_url": "https://spreedly.com",
            "merchant_password": "optional",
            "merchant_brand_id": "optional"
          },
          "amex": {
            "acquirer_bin": "4444444444",
            "merchant_url": "https://spreedly.com",
            "merchant_password": "optional"
          },
          "discover": {
            "acquirer_bin": "4444444444",
            "merchant_url": "https://spreedly.com",
            "merchant_password": "optional"
          },
          "diners":{
            "acquirer_bin": "4444444444",
            "merchant_url": "https://spreedly.com",
            "merchant_password": "optional"
          }
        }   
      }'

Response

Save the token field as your sca_provider_key:

{
  "sca_provider": {
    "token": "6EskuBYV5DVyN7Mmy1pV41FqgbN",
    "sandbox": true,
    "type": "test",
    "created_at": "2023-06-06T18:02:26Z",
    "updated_at": "2023-06-06T18:02:26Z",
    "mastercard": {
      "acquirer_bin": "4444444444",
      "merchant_url": "https://spreedly.com",
      "merchant_password": "optional"
    }
    // ... other card networks
  }
}

📘

IMPORTANT: When creating a Merchant Profile, there may be up to a one hour delay for the 3DS server to register merchant credentials with all of the card brands. While the SCA Provider key returned here will work immediately in our API, it may result in failures with our 3DS Server. We advise merchants to wait an hour after creating a production Spreedly SCA Provider before using it on gateway transactions.

Using Your SCA Provider

Option 1: Standalone Authentication

Perform 3DS2 authentication separately from payment processing:

curl https://core.spreedly.com/v1/sca/providers/6EskuBYV5DVyN7Mmy1pV41FqgbN/authenticate.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
      "currency_code": "EUR", 
      "amount": 100,
      "test_scenario": {
        "scenario": "authenticated"
      },
      "browser_info": "eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ=="
    }
  }'

Important Notes:

• browser_info is required for PSD2 compliance
• Use Spreedly.ThreeDS.serialize from our Lifecycle.js library to generate browser info on your frontend
• See Sca Provider Api Reference for more details

Option 2: Authentication During Payment

Include 3DS2 authentication directly in your purchase, authorize, or verify requests:

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "sca_provider_key": "6EskuBYV5DVyN7Mmy1pV41FqgbN",
          "amount": 100,
          "currency_code": "USD",
          "ip": "127.0.0.1",
          "browser_info": "eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ=="
        }
      }'

Using Previous Authentication Tokens

If you've already performed a standalone authentication, use the authentication token in subsequent transactions:

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "sca_authentication_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "ip": "127.0.0.1"
        }
      }'

Frontend Integration

Your frontend must handle asynchronous 3DS2 flows. See our platform-specific guides:

Advanced Features

Non-Payment Authentication

Spreedly's 3DS2 Global functionality supports merchants who need to perform 3DS on a specific payment method for cardholder verification only. This process is known as a Non-Payment Authentication.

How it Works

When you initiate this flow, Spreedly automatically informs the Access Control Server (ACS) that the request is strictly for cardholder verification and is not a payment.

• Potential Challenges: Even though no payment is involved, the card issuer may still request a challenge (e.g., a one-time passcode or biometric scan) from the cardholder to complete the verification process.

Two Ways to Initiate the Flow

Merchants currently have two primary methods to perform this Non-Payment Authentication:

1. Standalone Authentication:
   1. Perform a standalone SCA authentication transaction but omit the financial fields: amount and currency_code.
2. During a verify Transaction:
   1. Pass the necessary data (sca_provider_key, and browser_info) when performing a standard card verify transaction. This signals that the purpose is verification, which triggers the Non-Payment Authentication flow.

curl https://core.spreedly.com/v1/sca/providers/6EskuBYV5DVyN7Mmy1pV41FqgbN/authenticate.json \
	-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
	-H 'Content-Type: application/json' \
	-d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          // No amount or currency_code
          "browser_info": "eyJ3aWR0aCI6MjEzMy..."
        }
  	  }'

Requesting Exemptions

Low Value Exemption

For transactions under 30 EUR, request a low value exemption to reduce friction:

{
  "transaction": {
    "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
    "exemption_type": "low_value_exemption",
    "amount": 100,
    "currency_code": "EUR",
    "browser_info": "eyJ3aWR0aCI6MjEzMy..."
  }
}

Transaction Risk Analysis (TRA) Exemption

Request TRA exemption based on your merchant fraud rate:

{
  "transaction": {
    "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
    "sca_provider_key": "ZI0HsrLtnvzvNry7f3HARhnOXbA",
    "sca_authentication_parameters": {
      "exemption_type": "transaction_risk_analysis_exemption",
      "acquiring_bank_fraud_rate": "level_one"
    },
    "amount": 100,
    "currency_code": "EUR",
    "ip": "127.0.0.1",
    "browser_info": "eyJ3aWR0aCI6MjEzMy..."
  }
}

Fraud Rate Levels:

• level_one: Less than 0.01%
• level_two: 0.01% to 0.06%
• level_three: 0.06% to 0.13%

🚧

Warning: You are responsible for providing accurate fraud rate information. Consult your acquirer if unsure.

Authentication Flow Outcomes

When a transaction includes the sca_provider_key, 3D Secure (3DS) authentication is initiated before the payment gateway is contacted. Understanding these outcomes is critical for a robust integration.

Scenario 1: Immediate Authentication Failure

In rare cases, the 3DS authentication fails instantly, before any device fingerprinting or challenge is required.

Scenario 2: Pending Authentication Flow

The transaction is initially placed in a pending state, requiring the collection of the device_fingerprint. Once this data is submitted to the 3DS server, the transaction proceeds to one of three final outcomes.

2A. Frictionless Success

The 3DS server successfully authenticates the user without requiring any further input (e.g., the user is whitelisted or meets risk criteria).

2B. Frictionless Failure

The 3DS server rejects the transaction without requiring a challenge.

2C. Challenge Required

The 3DS server determines a higher level of risk and requires the end-user to complete a challenge (e.g., via a one-time passcode or banking app).

Note: Your frontend must handle all pending scenarios by using the callbacks and the lifecycle events to determine the transaction's final success or failure.

Important Notes

Supported Gateways

Additional Resources

💡

Getting Started Tip: We recommend starting with a Test SCA Provider to validate your integration before moving to production.

🚧

Update on force_daf Behavior

The force_daf flag will no longer be processed by Spreedly.

No integration changes required: You do not need to modify your current integration in order to accommodate this change.

For more information on this change please refer to our changelog here.