Skip to main content

Best practices

Following these best practices is essential for ensuring both security and maximum conversion performance.

Careful integration​

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.

Fallback snippet​

Implement fallback logic to ensure the fraud detection snippet loads even when the JS API fails:

(function(s, o, u, r, k){
    b = s.URL;
    v = (b.substr(b.indexOf(r)).replace(r + '=', '')).toString();
    r = (v.indexOf('&') !== -1) ? v.split('&')[0] : v;
    a = s.createElement(o),
    m = s.getElementsByTagName(o)[0];
    a.async = 1;
    a.setAttribute('crossorigin', 'anonymous');
    a.src = u+'script.js?ak='+k+'&lpi='+r+'&lpu='+encodeURIComponent(b)+'&key=$uniqid&_headers=".base64_encode($h)."';
    m.parentNode.insertBefore(a, m);
})(document, 'script', '".ApiSnippetUrl."', 'uniqid', '".ServiceKey."');

Parameters:

  • ServiceKey - Your service ID provided during provisioning
  • ApiSnippetUrl - Shield's regional endpoint (see API reference)
  • uniqid - Unique identifier for session tracking

Placement: This script should be placed in the <head> section of your web page.

Google traffic​

When using Google traffic, include the gclid URL query parameter on all pages where Shield is implemented. This helps tune Shield's fraud detection algorithms for Google-enabled traffic and achieve optimal conversion rates. Shield can detect fake gclid parameters and will block accordingly.

PIN submit​

Carefully consider when to call Shield's Block API in your PIN flow. If you trigger PIN SMSs before calling the Block API, bad actors could potentially flood your system with SMS requests. However, if you only call the Block API before sending the PIN SMS—and not before the billing attempt—you lose security analysis on the confirmation page.

Recommended approach: Call the Block API twice:

  1. Before sending the PIN SMS
  2. Before processing the billing attempt

Service configuration​

Fill out all fields accurately when configuring a service. Shield considers this information when evaluating transactions, and incorrect setup can lead to unnecessary blocks.

tip

Utilize Custom Variables to segment your traffic in Shield dashboards. This allows you to understand traffic quality per campaign, traffic source, and other dimensions.

Multi-page flows​

Best practice: Integrate Shield into each page of your flow. This provides Shield with comprehensive information to detect anomalies across the entire journey, including cases where fraudsters exhibit different behavior on different pages or MSISDNs change mid-flow.

Session linking across pages:

Sessions are linked by chaining the uniqid returned by the JS API. Here's how it works:

  1. Page 1: Call the JS API and receive a uniqid
  2. Page 2: Pass the Page 1 uniqid as a URL parameter (https://domain/page2?uniqid={page1_uniqid}), then call the JS API to generate a new uniqid for Page 2
  3. Subscription attempt: When the user attempts to subscribe on Page 2, call the Block API with the Page 2 uniqid

Shield will evaluate all information collected from both pages and return a verdict based on the complete flow.

Header enrichment​

tip

Always integrate Shield on pages that have header enrichment enabled.

For best security, Shield should be integrated on page(s) that are header enriched. This allows Shield to identify attempts by bad actors to inject false MSISDNs into the flow.

Encryption/hashing​

To protect user privacy, Shield supports encrypted or hashed MSISDNs instead of plain text. Contact your account manager to configure this feature.

Important: Use a consistent, deterministic hashing method. Shield must recognize when the same MSISDN appears across multiple transactions to detect fraud patterns. Random or salted hashes will break fraud detection capabilities.

Differentiating services by query parameters​

When multiple services share the same landing page and integration, URL query parameters can distinguish one service from another. See the Traffic Segmentation section for more information.

Reconciliation API​

Overview​

The Reconciliation API enables Shield to receive confirmation of subscription outcomes after transactions are cleared. When Shield clears a transaction, the partner's billing system reports back whether that transaction converted into an actual subscription.

This feedback loop unlocks advanced fraud detection capabilities and enables smarter rules that maximize conversions while maintaining protection.

Enabling Subscription-Aware Rules​

With reconciliation data, Shield can implement intelligent rules based on actual subscription history rather than simple attempt-counting.

For example, Shield can apply rules such as "block if this device has successfully subscribed to more than 3 services today." This approach targets genuine subscription fraud while allowing legitimate users who may be experiencing technical difficulties—such as repeated PIN failures—to complete their transactions.

Reconciliation data transforms velocity limits from blunt instruments into precise controls that distinguish between fraudulent patterns and legitimate retry behavior.

Per-Service Intelligence​

Reconciliation data enables Shield to build service-specific baselines and performance profiles. Shield can track conversion rates per service, identify anomalies when patterns shift, and tune thresholds based on how each service actually performs.

This granular visibility allows for tailored protection: services with different traffic profiles and risk characteristics can have rules optimized for their specific patterns.

Charge Pattern Analysis​

The most critical metric in fraud prevention is user complaints, which occur when users discover unexpected charges. Charge frequency and patterns therefore serve as essential signals for fraud risk assessment.

With reconciliation data, Shield gains visibility into charge history across services. This enables detection of subscription stacking—a common fraud pattern where multiple services are subscribed in rapid succession on the same MSISDN. Legitimate users rarely subscribe to multiple premium services within minutes; identifying this pattern allows Shield to intervene before complaints occur.

Implementation Options​

The API accommodates different technical environments. Real-time callbacks provide immediate subscription confirmation. Batch reconciliation—daily or weekly extracts—supports systems where real-time integration is not feasible.

The essential data points are:

  • Shield's original transaction identifier
  • Subscription outcome (success or failure)
  • Timestamp of the subscription event
  • Service identifier

Benefits Summary​

Reconciliation API integration delivers:

  • Improved conversion rates through subscription-aware rules that avoid blocking legitimate retry attempts
  • Enhanced fraud detection via charge pattern analysis and subscription stacking identification
  • Service-specific optimization with tailored thresholds based on actual performance data
  • Proactive protection by catching fraud patterns before they generate user complaints

Reconciliation API integration is recommended as a best practice for all partners seeking to maximize both protection and conversion performance.