Skip to main content

Integration Patterns

In order to integrate Shield, you must first be registered as a customer and you must have provisioned at least one service.

info

While Shield is designed for straightforward integration, effective fraud detection requires careful implementation. Fraudsters continuously evolve their techniques, exploiting even minor integration gaps to bypass protection systems. Shield's accuracy depends on receiving complete, consistent data throughout the user journey—from initial page load through final subscription. Small details matter: the timing of when Shield loads, which pages include the snippet, how session data flows between pages, and ensuring header information remains intact. A well-executed integration not only maximizes fraud detection but also minimizes false positives that could block legitimate users. The initial effort invested in proper integration pays dividends in both security and conversion rates, protecting your revenue while maintaining a smooth user experience.

Getting started​

First, you need to be very clear on who will be executing the JS API call and the Block API call. Multiple calls of the Block API for the same transaction will result in Block responses.

Shield supports the following integration methods. Each integration scenario below includes a logical flow and a sequence diagram to clarify how MCP Shield is invoked.

Regional endpoints​

Shield technology is deployed in several regions to provide the best latency between your servers and our regional endpoints.

In each region, the architecture is set up to provide high availability through autoscaling technology. As Shield relies on real time detection technology, our server availability needs to match our clients' capacity needs and variations.

RegionAPI Endpoint
Southern Africahttps://sa.apiserver.shield.monitoringservice.co
Singaporehttps://sg.apiserver.shield.monitoringservice.co
United Kingdomhttps://uk.apiserver.shield.monitoringservice.co
United Arab Emirateshttps://dc-ae-01.apiserver.mena.mcpshield.com

Latency test​

We provide a script to test latency between your webservers and each shield region. This bash script will run a few curl commands and print performance results.

wget https://docs.shield.monitoringservice.co/shield-latency 
sh shield-latency

CSP-Hosted Landing Page with Split API Execution​

Scenario: CSP runs the JS API, while the Block API decision is enforced by an Aggregator.

Flow​

  • User lands on CSP-hosted page.
  • CSP web server retrieves MCP Shield JS snippet.
  • Web page is delivered to the user with Shield integrated in the HTML.
  • MCP Shield JS API is executed in-browser to collect device, network, and behavioural signals.
  • User clicks on CTA button.
  • The CSP backend sends request to Aggregator for subscription
  • Aggregator invokes the Block API to validate the transaction.
  • MCP Shield returns a clear / suspect / block decision before payment confirmation.

CSP Hosted Landing Page with Both APIs

Pros & Cons​

Pros:

  • Server to server JS API call is more secure than client side call
  • By being embedded into the HEAD of the HTML page, Shield snippet is active from the moment the page is loaded
  • Aggregator enforces the use of MCP Shield by making Block API call before charging
  • The user journey stays fully on CSP pages until billing
    • No redirect complexity
    • CSP has full control of content (within compliance rules)

Cons:

  • Each CSP must integrate with Shield

Aggregator-Hosted Payment Page with Full Shield Enforcement​

Scenario: In this scenario, the Aggregator integrates MCP Shield directly, executing the JS API on the payment page and enforcing the Block API decision upon user subscription confirmation.

Flow​

  • User visits CSP-hosted page 1
  • User click Subscribe
  • User lands on the Aggregator-hosted payment confirmation page
  • Aggregator call JS API to retrieve the JS snippet
  • Web page is delivered to the user with Shield integrated in the HTML.
  • MCP Shield JS API is executed in-browser to collect device, network, and behavioural signals
  • User clicks Confirm CTA
  • Aggregator backend invokes the Block API to validate the transaction
  • MCP Shield returns a clear / suspect / block decision before the Aggregator triggers operator billing.

Aggregator-Hosted Payment Page with Full Shield Enforcement

Pros and Cons​

Pros:

  • Server to server JS API call is more secure than client side call
  • By being embedded into the HEAD of the HTML page, Shield snippet is active from the moment the page is loaded
  • Aggregator enforces the use of MCP Shield since they host the payment page
  • Only the aggregator needs to intergrate MCP Shield

Cons:

  • User is redirected between two different web servers
  • MCP Shield only has visibility of the second page
  • Payment page content is controlled by the aggregator, limiting the CSPs' choices

CSP-Hosted Pages And API Calls​

Scenario: CSP hosts the landing pages, calls the Shield JS API, and calls the Shield Block API when subscription attempted, before initiating billing.

Flow​

  • User lands on the CSP-hosted landing page.
  • The CSP calls the Shield JS API (server-to-server) to initialise a Shield session.
  • Web page is delivered to the user with Shield integrated in the HTML.
  • When the user reaches the subscription trigger point, the CSP calls the Shield Block API.
  • MCP Shield returns a clear / suspect / block decision.

CSP-Hosted Pages And API Calls

Pros & Cons​

Pros:

  • Only the CSP needs to integrate MCP Shield. Aggregator and Operator agnostic.
  • Server to server JS API call is more secure than client side call
  • By being embedded into the HEAD of the HTML page, Shield snippet is active from the moment the page is loaded
  • No Redirect Complexity. The user journey stays fully on CSP pages until billing.

Cons:

  • Limtied to scenario's where the CSP is given full control

MCP-Hosted Payment Page with Full Shield Enforcement​

Scenario: User is redirected from a CSP landing page to an MCP-hosted payment page where Shield performs full behavioural analysis and enforces the final billing decision.

Flow​

  • User lands on the CSP landing page and initiates a subscription journey.
  • The CSP redirects the user to an MCP-hosted payment page.
  • MCP Shield is initialised on the payment page.
  • Device fingerprinting and behavioural signals are collected directly from the user’s device.
  • When the user confirms the payment, MCP invokes the Shield Block API.
  • MCP Shield returns a real-time decision (Clear / Suspect / Block).

CSP-Hosted Landing Page with Both API Execution

Pros & Cons​

Pros:

  • Minimal partner integration required, MCP handles everything
  • Strongest possible security

Cons:

  • Less flexibility around page content and styling

MSISDN & PIN Entry Flow with Shield Enforcement on Both Pages​

Scenario: A two-step MSISDN and PIN flow where Shield correlates activity across both pages before billing.

Flow​

  • User lands on the MSISDN Entry Page and enters their mobile number.
  • MCP Shield is initialised on the MSISDN Entry Page and generates a Step-1 UNIQID.
  • Device fingerprinting and behavioural signals are collected during MSISDN entry.
  • The Step-1 UNIQID is passed from the MSISDN Entry Page to the PIN Entry Page via the URL
    • The uniqid is persisted or appended to the URL when redirecting to page two: https://example.com/page2?uniqid=page1_uniqid
  • The user is redirected to the PIN Entry Page to enter the received PIN.
  • MCP Shield is initialised on the PIN Entry Page and generates a Step-2 UNIQID, while also receiving the Step-1 UNIQID, allowing Shield to correlate both steps into a single journey.
  • Additional behavioural signals are collected during PIN entry.
  • Upon PIN submission, the backend invokes the Shield Block API using the Step-2 UNIQID.
  • MCP Shield evaluates the full journey (MSISDN + PIN behaviour) and returns a clear / suspect / block decision before payment confirmation.

CSP-Hosted Landing Page with Both API Execution

Pros & Cons​

Pros:

  • Shield integrated on two pages, offering increased security
  • Server to server JS API call is more secure than client side call
  • By being embedded into the HEAD of the HTML page, Shield snippet is active from the moment the page is loaded

Cons:

  • Slightly more complex integration since uniqid must be passed from page 1 to page 2

MSISDN & PIN Flow with Single-Page Shield Enforcement​

Scenario: Shield is implemented on only one page of a two-step MSISDN and PIN flow, either the MSISDN Entry Page or the PIN / OTP Entry Page and enforces the final decision before billing.

Flow​

  • User lands on the MSISDN Entry Page and enters their mobile number.
  • The user is redirected to the PIN / OTP Entry Page to enter the received PIN.
  • MCP Shield is initialised on one selected page only:
    • Either the MSISDN Entry Page, or
    • The PIN / OTP Entry Page.
  • MCP Shield generates a UNIQID on the page where it is deployed.
  • Device fingerprinting and behavioural signals are collected only on that page.
  • Upon PIN submission, the backend invokes the Shield Block API using the generated UNIQID.
  • MCP Shield returns a clear / suspect / block decision before payment confirmation.

MSISDN & PIN Flow with Single-Page Shield Enforcement

Pros & Cons​

Pros:

  • Simpler integration, Shield is deployed on only one page
  • Server to server JS API call is more secure than client side call
  • By being embedded into the HEAD of the HTML page, Shield snippet is active from the moment the page is loaded

Cons:

  • Shield observes only one step of the user journey.
  • MSISDN and PIN behaviour are not fully linked.
  • Lower fraud detection accuracy. Certain multi-step fraud patterns may not be detected.
  • Effectiveness depends on whether Shield is deployed on MSISDN or PIN page.

When to Use This Scenario​

  • Low-to-medium risk campaigns
  • Fast-deployment requirements
  • Legacy flows with limited modification scope
  • Operator environments allowing single-point enforcement

Redirect Flow Integration (Shield on Redirect Page)​

Scenario: Client controls a redirector step, where Shield JS is executed and the Block API decision is enforced before forwarding the user.

Contact support if you want further instructions on how to implement the redirect integration.

Frontend integration​

warning

This integration pattern is not recommended

Frontend

Pros & Cons​

Pros:

  • Simple integration
  • Compatible with content delivery network static page deployments

Cons:

  • Exposes sensitive information in front end code
  • More prone to tampering by bad actors
  • Fraud detection does not begin at the moment the page is loaded