SupportBlog
Guides

3DS Global

Configure and execute 3DS Global with Spreedly through Dodgeball.

Configure Spreedly 3DS Global in Dodgeball by enabling both Spreedly services, adding the required checkpoint steps, and sending request data for initialization and execution.

In a checkpoint, 3DS runs in two steps: initialization and execution.

💡

To learn more about Spreedly 3DS, check out the Spreedly 3DS2 Global guide

Enable 3DS Global services

Enable 3DS Initialization

  1. From the Service Catalog, click View All Services.
  2. Select the Spreedly service.
  3. Complete the configuration section with these credentials:
    • Environment Key
      • Required. You can override this value per request with spreedly.scaAuthentication.inputs.environmentKey.
    • Access Secret
    • SCA Provider Key
      • Required to execute 3DS. Although the service marks this field as optional, 3DS authentication needs it. You can override this value per request with spreedly.scaAuthentication.inputs.scaProviderKey.
  4. Click Enable to save your configuration.

Enable 3DS Execution

  1. From the Service Catalog, click View All Services.
  2. Select the Spreedly Checkout service.
  3. Complete the configuration section with these credentials and options:
    • Environment Key
    • Enable Custom Iframe Location (optional)
      • Enable this option when you want to control where Spreedly places the challenge iframe.
      • When enabled, pass challengeIframeLocation and challengeIframeClasses in the request body.
      • challengeIframeLocation is the ID of the HTML container where Spreedly places the challenge.
      • challengeIframeClasses are the CSS classes Spreedly applies to the iframe inside that container.
  4. Click Enable to save your configuration.

Configure 3DS in a Checkpoint

  1. Open the Step Palette in Checkpoint Studio and click the Services tab to find available step templates.
  2. Add these steps to the checkpoint flow where 3DS should run:
    1. Sca Authentication (Spreedly)
    2. Perform 3DS Authentication (Spreedly Checkout)
  3. Click the Perform 3DS Authentication (Spreedly Checkout) step to open the flyout configuration panel.
  4. Expand Advanced Options at the bottom of the panel and click Manage Input Data Sources.
  5. Set threeds.inputs.transaction.token to use spreedly.scaAuthentication.outputs.transaction.token as its data source. This connects the 3DS execution step to the SCA authentication step that runs earlier in the workflow.

Request Data

Spreedly requires request data for both SCA authentication and 3DS execution.

💡

You can view detailed descriptions of input fields in Checkpoint Studio. Send data that meets the specifications for each field.

Minimum Required Data

Use this minimum payload to execute Spreedly 3DS. You can send additional fields to improve authentication results, but omitting the optional fields in the full example will not cause an error.

{
  "paymentMethod": {
    "token": "01KGT7TQTC921Y33BR4TSYEHJC"
  },
  "transaction": {
    "amount": 2999,
    "currency": "USD"
  },
  "spreedly": {
    "scaAuthentication": {
      "inputs": {
        "browserInfo": "eyJ3aWR0aCI6MjU2MCwiaGVpZ2h0IjoxNDQwLCJkZXB0aCI6MzAsInRpbWV6b25lIjoyNDAsInVzZXJfYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMC4xNTsgcnY6MTIzLjApIEdlY2tvLzIwMTAwMTAxIEZpcmVmb3gvMTIzLjAiLCJqYXZhIjpmYWxzZSwibGFuZ3VhZ2UiOiJlbi1VUyIsImFjY2VwdF9oZWFkZXIiOiJ0ZXh0L2h0bWwsYXBwbGljYXRpb24veGh0bWwreG1sLGFwcGxpY2F0aW9uL3htbCJ9=="
      }
    }
  }
}

Full Data Example

Use this example to send all supported fields for Spreedly 3DS. Some fields may not be relevant to your business, so include only the fields that apply to your use case.

If you use a test scaProviderKey, include testScenario to define the 3DS test outcome.

{
  "paymentMethod": {
    "token": "01KGT7TQTC921Y33BR4TSYEHJC"
  },
  "transaction": {
    "amount": 2999,
    "currency": "USD",
    "orderNumber": "123order123",
    "billingAddress": {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+15555550100",
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "customer": {
    "primaryEmail": "[email protected]"
  },
  "runtimeEvent": {
    "ipAddress": "203.0.113.42"
  },
  "spreedly": {
    "scaAuthentication": {
      "inputs": {
        "browserInfo": "eyJ3aWR0aCI6MjU2MCwiaGVpZ2h0IjoxNDQwLCJkZXB0aCI6MzAsInRpbWV6b25lIjoyNDAsInVzZXJfYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMC4xNTsgcnY6MTIzLjApIEdlY2tvLzIwMTAwMTAxIEZpcmVmb3gvMTIzLjAiLCJqYXZhIjpmYWxzZSwibGFuZ3VhZ2UiOiJlbi1VUyIsImFjY2VwdF9oZWFkZXIiOiJ0ZXh0L2h0bWwsYXBwbGljYXRpb24veGh0bWwreG1sLGFwcGxpY2F0aW9uL3htbWwreG1sLGFwcGxpY2F0aW9uL3htbCJ9==",
        "scaProviderKey": "2275CJZNR68K2AT26YQ48FRNPG",
        "testScenario": "challenge",
        "callbackUrl": "https://example.com/webhooks/spreedly/callback",
        "callbackFormat": "json",
        "environmentKey": "HTAOEXTKBA32TMAEKM"
      }
    }
  },
  "spreedly-checkout": {
    "threeds": {
      "inputs": {
        "challengeIframeClasses": "challenge_css_classes",
        "challengeIframeLocation": "challenge_div_id"
      }
    }
  }
}

Optional: Override service settings

You can override the globally configured environment key or SCA provider key by passing those values in the request body, as shown in the full data example. Use overrides when you have separate SCA providers for different payment service providers (PSPs) or sub-merchants.

When you override service settings, follow these requirements:

  1. The SCA provider must match the environment used for the request.
  2. If you override the global environment, the configured access secret must be an organization-level access secret so it can access each environment you use.

Optional: Custom iframe location settings

Enable custom iframe location when you want Spreedly to place the challenge iframe in a specific container on your page instead of showing it in a modal.

To use a custom iframe location, pass these fields in spreedly-checkout.threeds.inputs:

  • challengeIframeLocation: the ID of the HTML container where Spreedly places the challenge iframe.
  • challengeIframeClasses: the CSS classes Spreedly applies to the iframe inside that container.

You must also handle Spreedly iframe events so your page knows when to show and hide the challenge container. See Spreedly's 3DS Global guide for more details. https://developer.spreedly.com/update/docs/3ds2-global-integration-guide-web

Updated 9 days ago