Spreedly 3DS2 Global SCA Provider Guide

Spreedly 3DS2 Global is currently in beta. Documentation and API usage are subject to change before final release. Please contact Spreedly support if you encounter any problems with your Spreedly 3DS2 Global integration.

Prerequisites

In order to process transactions using Spreedly’s 3DS2 solution, you must register your merchants via the Spreedly platform. There is a required set of data fields per card network that are necessary to generate 3DS credentials per merchant:

  • Acquirer BIN
  • Merchant ID (“MID”)
  • Merchant MCC
  • Merchant Name
  • Merchant Country
  • Merchant URL

The top six fields can be located by contacting your acquirer or, in some cases, can be located by using your payment processor (see more on this below).

After you have collected the data above, you will be able to register with Spreedly 3DS2 Global using our Merchant Management Endpoint.

Important Note At this time, Stripe is not able to provide ABIN/MID details to 3rd parties. In order to be SCA-ready, we recommend that Stripe merchants use Spreedly’s Gateway Specific 3DS2 solution for Stripe Payment Intents.

What is an Acquirer BIN?

The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution.

There are various places the BIN could be located:

  • Contact your acquirer to obtain your acquirer BIN.
  • If you aren’t familiar with where to find your acquirer BIN, your payment processor could be of value. Due to the sensitive nature of the information, some payment processors may not provide the BIN via email but are able to assist over the phone.

What is a Merchant ID (MID)?

The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have.

There are various places the MID could be located:

  • Contact your acquirer to obtain your acquirer MID.
  • MID can also be found by contacting your payment processor’s support team.

What is a MCC?

The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication.

There are various places the MCC could be located:

  • Contact your acquirer to obtain your MCC.
  • Tax Document: Form 1099-K has a merchant category code box which includes the 4-digit MCC. This document can be found under your gateway’s documentation/reporting section.
  • Some Payment Processors automatically assign a MCC at account creation, or you can set the MCC on your own. If you don’t know what your MCC is, you can contact your gateway’s support and they should be able to help. Due to the sensitive nature of the information, some payment processors may not be able to provide that information via email.

What is the Merchant Name?

Assigned by the acquiring bank; please contact them.

What is the Merchant Country?

Country Code in ISO 3166-1 numeric format.

What is the Merchant URL?

Fully qualified URL of the merchant’s main website or customer care site that contains a method of contact. This provides additional information to the receiving 3DS system if a problem arises. It is sent to the ACS (issuer), which will decide if it is relevant to be displayed—however, it isn’t commonly used.

If you have multiple URLs, the one that best represents your organization should be used.

Using the Merchant Management Endpoint

All fields shown below are required to create a Spreedly SCA Provider, with the exception of each card brand’s merchant_password field.

The values given for a sandbox Spreedly API provider must have the correct formatting (i.e., a valid country code and merchant category code) but are not used in the authentication, so fake values are acceptable. Please see the values given in our Integration Guide to use as examples of working values.

curl https://core.spreedly.com/v1/sca/providers.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "sca_provider": {
          "merchant_profile_key": "Ke4Ybltto744p0mdSnXmaOxBeeK",
          "type": "spreedly",
          "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"
          },
          "amex": {
              "acquirer_bin": "4444444444",
              "merchant_url": "https://spreedly.com",
              "merchant_password": "optional"
          }
        }
      }'
curl https://core.spreedly.com/v1/sca/providers.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<sca_provider>
        <merchant_profile_key>Ke4Ybltto744p0mdSnXmaOxBeeK</merchant_profile_key>
        <type>spreedly</type>
        <sandbox>true</sandbox>
        <mastercard>
            <acquirer_bin>4444444444</acquirer_bin>
            <merchant_url>https://spreedly.com</merchant_url>
            <merchant_password>optional</merchant_password>
        </mastercard>
        <visa>
            <acquirer_bin>4444444444</acquirer_bin>
            <merchant_url>https://spreedly.com</merchant_url>
            <merchant_password>optional</merchant_password>
        </visa>
        <amex>
            <acquirer_bin>4444444444</acquirer_bin>
            <merchant_url>https://spreedly.com</merchant_url>
            <merchant_password>optional</merchant_password>
        </amex>
    </sca_provider>'

Note: this creates a sandbox (i.e., test-only) SCA provider, which is useful for integration tests. For Production, create a new SCA Provider without using this flag.

When creating a production Spreedly SCA Provider, 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. Spreedly advises merchants to wait an hour after creating a production Spreedly SCA Provider before using it on gateway transactions.

Sandbox Test Scenarios

Credit Cards

Card Number CVV Expiration Type
5555555555554444 123 10/2029 3D Secure Enrolled Card

Note: Flow scenarios are available for any test MasterCard starting with 555555, but using the same card over and over will automatically switch your request to the challenge flow. To mitigate this, you can change the card number by changing the last two numbers and verifying it with a Luhn calculator.

Test Scenarios

Setting the amount of the transaction to a certain value will simulate certain authentication results.

For these test amounts, currency_code should be set to EUR.

Note: Currently in beta, not all potential flows can be tested. We are working to support testing of a broader variety of situations.

Amount in cents Response Status Flow Description
4 Y Frictionless Authentication/account verified
9996 A Frictionless ACS could not be reached, but Authentication/account verification performed by issuing bank
9997 U Denied Authentication/account verification could not be performed, transaction fails
9998 N Denied Not authenticated/account not verified, transaction fails
9999 R Denied Authentication/account verification rejected, transaction fails
100000 C Challenge Authentication requires Challenge by issuing bank, handled by Lifecycle

Challenge Values

When presented with a challenge, entering the code 123456 will result in a successful authentication.

Note: Our 3DS2 solution partners are based in Spain, so the example ACS challenge page may be in Spanish. This will only occur in the sandbox; for real 3DS2 authentications, the acquiring bank’s page will be displayed instead.

Simulating a 3DS1 fallback

In Production, fallback to 3DS1 will automatically happen for your customers, however during your integration tests triggering conditions can be simulated by passing a custom Window object as a third parameter to our Spreedly.ThreeDS.serialize function.

Following the DOM specification for the Window interface, your object should provide screen and navigator properties. Make one or more of the returned properties be incorrect, such as window height of zero, and our API will interpret that as suspicious, prompting a 3DS1 fallback challenge to the user.

For a complete example, see /public/javascripts/your-code.js in our Spreedly 3DS Reference Implementation.

DO NOT use the third parameter in your production code, else ALL your customers will experience unwanted fallbacks and challenges.

      // Capture browser data by using `Spreedly.ThreeDS.serialize().
      let browser_info = Spreedly.ThreeDS.serialize(
        browser_size,
        acceptHeader,
        new MockFallbackBrowser()
      );

Here’s what MockFallbackBrowser could look like:

/**
 * Wrapper around the regular `window` object.
 *
 */
class MockFallbackBrowser {
  screen = {
    width: "0",
    height: "0",
    colorDepth: "-1"
  };

  navigator = {
    javaEnabled: function () {
      return window.navigator.javaEnabled()
    },
    userAgent: "Mozilla/5.0 (MacOS; Intel Mac OS X 10_15_6) Spreedly 3DS Debugging",
    language: window.navigator.language
  }
}

FAQs

See a list of all 3DS frequently asked questions in the Help Center.