Service Onboarding Form

Introduction

The new service form is located here.

The new MCP Shield service onboarding form captures detailed configuration information to ensure Shield is optimally integrated for your specific service flow. This guide walks you through each field and helps you complete the form efficiently.

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.

Time to Complete: 5-10 minutes per service (first time)

What's New:

• More detailed configuration fields for optimal security
• Auto-generated service summary for easy verification
• Service Flow Profiles to save and reuse common configurations
• Better guidance with tooltips and hints for each field

Before You Begin

Information You'll Need

Have the following information ready before starting:

Basic Service Details:

• Service name
• Content Service Provider (CSP/Merchant) name
• Country and Mobile Network Operator (MNO)
• Type of service (Games, Video, Music, etc.)

Technical Configuration:

• Number of pages in your subscription flow
• Landing page URL(s)
• Which pages Shield is integrated on
• Whether you use header enrichment (HE)

If Using Header Enrichment:

• HTTP header name (usually X-MSISDN)
• Payment flow type (1-click, 2-click, etc.)
• WiFi backup flow details

Optional (for Analytics):

• URL parameters you want to track (campaign IDs, traffic sources, etc.)

Who Should Complete This Form?

This form should be completed by someone with technical knowledge of your service integration, such as:

• Technical Account Manager
• Integration Developer
• Marketing resource with technical understanding

Getting Started

Accessing the Form

1. Log in to your MCP Shield account
2. Navigate to Services in the main menu
3. Click Add New Service
4. The service onboarding form will appear

Using Service Flow Profiles (Optional)

If you're setting up multiple services with similar configurations (common for aggregators), consider using Service Flow Profiles to save time:

1. First Service: Complete the form normally
2. After Submission: Click "Save as Profile" to save your configuration
3. Subsequent Services: Select your saved profile from the dropdown at the top of the form to pre-fill common fields

See Service Flow Profiles section for detailed instructions.

Step-by-Step Guide

Section 1: Basic Information

Service Name

Required | Text field

What it is: A unique name to identify this service in Shield.

How to fill it in:

• Use clear, descriptive names
• Include key identifiers like service type, country, or MNO
• Use consistent naming conventions if you have multiple services

Examples:

• GameZone UK MTN
• Horoscope NG Airtel
• MusicStreaming SA Vodacom

Tips:

• Avoid generic names like "Service1" or "Test"
• Use 3-100 characters
• You can use letters, numbers, spaces, dashes, and underscores
• International characters (Arabic, Thai, French, etc.) are fully supported

CSP/Merchant Name

Required | Dropdown

What it is: The Content Service Provider or Merchant who owns this service.

How to fill it in:

1. Click the dropdown
2. Select your CSP from the list
3. If not listed, click the + icon to add a new CSP

Adding a New CSP:

1. Click the + icon next to the dropdown
2. In the popup, enter:
   • CSP Legal Name (required): Official registered business name
   • CSP Display Name (optional): How you want it displayed (defaults to Legal Name)
   • Contact Email (optional): Main contact email
   • Notes (optional): Any additional information
3. Click Add CSP
4. Your new CSP will be automatically selected

Tips:

• Add all your CSPs at once to save time later

Type of Service

Required | Dropdown

What it is: Category of your service for analytics and benchmarking.

Tips:

• This field helps with reporting
• Select "Other" if none fit your service type
• Our team may follow up if you select "Other" to expand our categories

Section 2: Geographic & Network Configuration

Country

Required | Dropdown

What it is: The country where this service operates.

How to fill it in: Select the country from the dropdown list.

Tips:

• This determines which MNOs appear in the next field
• Each service should target one country
• For multi-country services, create separate service entries

Mobile Network Operator (MNO)

Required | Dropdown

What it is: The mobile network operator for this service.

How to fill it in:

1. After selecting Country, the MNO list will populate
2. Select your MNO from the available options
3. If your MNO is not listed, select Other

If You Select "Other": Our operations team will contact you within 24 hours to add your MNO to the system.

Carrier Grade NAT

info

This field is decprecated and will soon be removed. Every MNO uses Carrier Grade NAT.

Required | Radio buttons (Yes / No / I don't know)

What it is: Carrier Grade NAT (CGN) is when multiple subscribers share the same public IP address.

How to fill it in:

• Yes: If you know the MNO uses CGN
• No: If you know the MNO doesn't use CGN
• I don't know: If you're unsure (we'll follow up)

Why it matters: Shield's fraud detection algorithms account for CGN when analyzing IP-based patterns. Many subscribers appearing from the same IP is suspicious unless CGN is enabled.

Tips:

• CGN is common in Africa and Asia due to IPv4 scarcity
• If you've noticed many different subscribers using identical IPs, the MNO likely uses CGN
• When in doubt, select "I don't know" and we'll help you determine it

Section 3: Service Flow Configuration

Header Enriched Flow

Required | Radio buttons (Yes / No)

What it is: Header Enrichment (HE) is when the mobile operator automatically injects the subscriber's phone number (MSISDN) into HTTP headers.

How to fill it in:

• Yes: Your service uses header enrichment
• No: Your service does not use header enrichment

How it works:

1. User clicks "Subscribe" on mobile data
2. MNO adds MSISDN to HTTP header (e.g., X-MSISDN: +27821234567)
3. Your server reads the header to identify the subscriber
4. Subscription processed without manual phone number entry

Key points:

• Only works on mobile data (not WiFi)
• Enables one-click or two-click subscription flows
• Less friction than manual PIN entry

If Yes: Additional fields will appear for HE configuration.

WiFi Backup Flow

Conditional: Only appears if Header Enriched Flow = Yes
Required | Radio buttons (Yes / No)

What it is: Alternative authentication method when users access your service via WiFi (where HE doesn't work).

How to fill it in:

• Yes: You have a backup flow for WiFi users
• No: Your service only works on mobile data (no WiFi support)

Why it matters: When users are on WiFi, header enrichment doesn't work because the traffic doesn't pass through the MNO's network. You need an alternative authentication method.

Common WiFi backup flows:

• MSISDN + PIN (user enters phone number and PIN)
• MSISDN + MO (user enters number, receives SMS to confirm)
• MSISDN + USSD (user enters number, confirms via USSD code)

If Yes: You'll need to specify the WiFi payment flow type in Section 5.

Number of HTML Pages in Flow

Required | Dropdown

What it is: How many separate web pages (HTML documents) are in your subscription flow.

How to fill it in: Count each distinct HTML page from landing to payment completion:

• Landing page = 1
• Landing page + confirmation page = 2
• Landing page + details page + confirmation = 3

Examples:

1-Page Flow:

User lands → Clicks subscribe → Payment completes (all one page)

2-Page Flow:

Page 1: User lands → Clicks subscribe → Redirects to...
Page 2: Confirmation page → Finalizes payment

Tips:

• Count HTML pages, not form steps on the same page
• If unsure, ask your developer
• Shield uses this information to optimize fraud detection
• "Other" or "I don't know" will trigger follow-up from our team

If You Select 2 or 3: Additional fields will appear to configure each page.

Landing Page URL(s)

Required for Page 1, Optional for others | URL fields

What it is: The web address(es) where users access your service.

How to fill it in:

1. For each page in your flow, you'll see a separate section
2. Enter at least one URL for Page 1 (required)
3. Click + Add Another URL if you have multiple URLs for the same page
4. Enter URLs for subsequent pages if applicable

Format:

• Must include protocol: https:// or http://
• Complete URL including domain and path

Examples:

Page 1 URLs:
- https://games.example.com/subscribe
- https://subscribe.example-games.com
- https://www.example.com/en/games/subscribe

Page 2 URL (if applicable):
- https://confirm.example.com/finalize

Why multiple URLs per page: You may use different domains or URL patterns for the same service (subdomains, language paths, campaign variations).

Tips:

• Shield will accept traffic from ANY of these URLs
• Include all variations to prevent legitimate traffic from being blocked
• Don't include URL parameters (campaign IDs, etc.) - just the base URL
• Traffic originating from URLs not listed here may be considered suspicious.

Section 4: Multi-Page Configuration

This section only appears if Number of HTML Pages > 1

Page X Hosted By

Required for each page | Dropdown per page

What it is: Who hosts and controls each page in your flow.

Why it matters: Shield needs to understand your integration architecture to ensure proper security configuration.

Example:

2-page flow where:
- Page 1: Hosted by Content Provider
- Page 2: Hosted by Aggregator (redirect to aggregator's confirmation page)

If You Select "Other": Our team will contact you to understand your setup.

Page(s) Where Shield is Implemented

Required | Multi-select dropdown

What it is: Which pages have the Shield JavaScript snippet integrated.

How to fill it in:

1. Select all pages where Shield is integrated
2. You can select multiple pages
3. At minimum, one page must be selected

Best Practice: Integrate Shield on ALL pages in your flow for maximum protection.

Why multiple pages matters:

✅ Shield on all pages:

• Fraud can't bypass detection by targeting unprotected pages
• Cross-page behavior analysis improves accuracy
• Maximum security coverage

⚠️ Shield only on Page 1 (2-page flow):

• Page 2 is vulnerable to direct attacks
• Reduced fraud detection capability
• You'll receive a warning but can proceed

Page(s) Where Header Enrichment Occurs

Conditional: Only if Header Enriched Flow = Yes AND Number of Pages > 1
Required | Multi-select dropdown

What it is: Which page(s) receive the header-enriched HTTP request from the MNO.

How to fill it in: Select which page(s) have the MSISDN injected into headers.

Requirement: 🚨 Shield SHOULD be integrated on the same page where header enrichment occurs.

Why this matters: Shield needs to be on the HE page to capture and validate the MSISDN header. If Shield is on Page 2 but HE occurs on Page 1, Shield cannot validate the header data, creating a security vulnerability.

Validation: If you select different pages for Shield and HE, you'll see a critical warning:

"Header enrichment occurs on a page without Shield. This increases the risk of MSISDN injection attacks."

Correct Configuration:

✅ HE on Page 1, Shield on Page 1 (and optionally Page 2)
✅ HE on Page 1 and 2, Shield on Page 1 and 2
❌ HE on Page 1, Shield only on Page 2 (HIGH RISK)

If You See the Error: You should either:

1. Add Shield to the page where HE occurs, OR
2. Move HE to the page where Shield is integrated

Section 5: Payment Flows

Header Enrichment HTTP Header Name

Conditional: Only if Header Enriched Flow = Yes
Required | Text field

What it is: The exact HTTP header name that contains the subscriber's MSISDN.

How to fill it in: Enter the header name provided by your MNO. Default is X-MSISDN.

Common header names:

• X-MSISDN (most common)
• X-Subscriber-Number
• X-Nokia-MSISDN
• X-User-MSISDN
• HTTP-X-MSISDN

Tips:

• Ask your MNO or aggregator for the exact header name
• It's case-insensitive
• Usually starts with X- or HTTP-
• If using "Other" headers for MSISDN that aren't configured here, Shield may flag them as suspicious
• MSISDN injection is a common practice by bad actors. Identifying the correct header used by the MNO helps detect fraud.

HE Payment Flow

Conditional: Only if Header Enriched Flow = Yes
Required | Dropdown

What it is: How the subscription is completed after header enrichment.

How to fill it in: Select the flow type:

• 1-click (direct charge): User charged immediately upon clicking subscribe
• 2-click (confirmation required): User must confirm on a second page/button
• 1-click + PIN: User enters PIN after clicking subscribe
• 1-click + MO confirmation: User must reply to an SMS
• Other: Custom flow not listed
• I don't know: Unsure (we'll follow up)

Examples:

1-click:

User clicks "Subscribe" → Charged immediately → Done

2-click:

User clicks "Subscribe" → Page 2 shows "Confirm subscription" → User clicks "Confirm" → Charged

1-click + PIN:

User clicks "Subscribe" → User received PIN by SMS → User Enters PIN on Page → Charged

If You Select "Other" or "I don't know": Our team will contact you to clarify your flow configuration.

WiFi Payment Flow

Conditional: Only if (HE=Yes AND WiFi Backup=Yes) OR HE=No
Required | Dropdown

What it is: Authentication method when header enrichment is unavailable.

How to fill it in: Select the authentication method:

• MSISDN + PIN: User enters phone number and receives PIN via SMS
• MSISDN + MO (SMS): User enters number, sends/receives SMS to confirm
• MSISDN + USSD: User enters number, confirms via USSD code (e.g., *123#)
• Other: Custom method not listed
• I don't know: Unsure (we'll follow up)

When this applies:

• All services without header enrichment
• Services with HE that also support WiFi users

Section 6: Advanced Tracking (Optional)

Custom URL Parameters to Track

Optional | Multi-value text fields

What it is: URL parameter names from your landing page that you want Shield to extract and display in your dashboard.

info

These URL parameters are extracted from the lpu parameter of the JS snippet API call. See Traffic Segmentation for more info.

How to fill it in:

1. Enter the parameter name (key only, not the value)
2. Click + Add Parameter to add more
3. Click Remove to delete parameters

Why use this: Compare performance across campaigns, traffic sources, or other segments. Shield creates separate analytics graphs for each parameter value.

Example:

Your Landing URL:

https://games.example.com/subscribe?campaign_id=summer2025&source=facebook

Parameters to track:

campaign_id
source

⚠️ Do not track unique fields!

• gclid
• fbclid

Result in Dashboard: You'll see separate charts showing clear vs. blocked traffic for:

• campaign_id: summer2025, winter2024, spring2025...
• source: facebook, google, smadex...

Common parameters:

• campaign_id, campaign_name
• source, traffic_source, utm_source
• affiliate_id, partner_id
• variant (for A/B testing)

Tips:

• Only enter the parameter name, not values
• Parameter names are case-sensitive
• Leave blank if you don't need this feature

Custom Referrers (Referrer URL Parameters)

Optional | Multi-value text fields

What it is: URL parameter names from the HTTP Referrer header that you want to track.

How to fill it in: Same as Custom URL Parameters, but these come from the referrer URL (the page that sent users to your service).

⚠️ Important Limitation: Due to browser privacy protections, referrer parameters are typically only available for same-origin navigation (e.g., Page 1 → Page 2 on your domain).

Parameters from external referrers (ads, affiliates, partner sites) will NOT be captured because browsers strip query parameters on cross-origin requests.

Recommendation: Use Custom URL Parameters instead for tracking external traffic sources. Put tracking IDs in your landing page URL, not the referrer URL.

When Custom Referrers works:

Your Page 1: https://example.com/landing?ref_source=email
↓ (user clicks) ↓
Your Page 2: https://example.com/confirm
→ Referrer header includes ref_source parameter ✓

When Custom Referrers DOESN'T work:

External Ad: https://facebook.com/ads?campaign=xyz
↓ (user clicks) ↓
Your Landing: https://example.com/subscribe
→ Referrer header = "https://facebook.com/" only (params stripped) ✗

Tips:

• Most users should leave this blank
• Only use for multi-page same-origin flows
• For external traffic, use Custom URL Parameters instead

Block API Variables

Optional | Multi-value text fields

What it is: Additional variables you pass via the Block API (server-side integration).

How to fill it in:

1. Enter variable names you send via the Block API
2. Click + Add Variable to add more

This is an advanced feature. Most partners won't use this.

Use case: If your server-side integration passes additional context to Shield via the Block API (e.g., user account age, previous purchase count), list those variables here.

Example variables:

• user_account_age
• previous_purchase_count
• payment_method
• user_risk_score

Tips:

• Requires server-side Block API integration
• Leave blank if you're only using the JavaScript snippet
• Contact your account manager if you need help with Block API integration

Section 7: Service Summary

Service Description (Auto-Generated)

Auto-generated | Text area (editable)

What it is: A plain English summary of your service configuration, automatically generated based on your form inputs.

How it works:

1. Complete all required fields in the form
2. Shield automatically generates a summary in plain language
3. Review the summary to ensure accuracy
4. Edit if needed (but keep it accurate)

Why it matters:

• Confirms you've configured everything correctly
• Used by our operations team for review
• Serves as documentation for your service setup

Tips:

• Wait for all required fields to be completed before the summary generates
• If the summary doesn't match your actual setup, review your form inputs
• You can edit the text, but ensure it remains accurate

Confirmation Checkbox

Required | Checkbox

What it is: Your confirmation that the service description is accurate.

How to fill it in: Check the box to confirm:

"I confirm that the service summary above accurately describes my service integration and I understand that Shield will enforce these parameters for fraud detection."

Why it's important:

• Shield uses this configuration to validate your traffic
• Incorrect configuration can cause legitimate traffic to be blocked
• This serves as your acceptance of the documented setup

You cannot submit the form without checking this box.

Form Footer: Actions

Cancel

Discard all changes and return to the services list. Your form data will not be saved.

Save as Profile

Only enabled after form is valid

Save your current configuration as a reusable Service Flow Profile. See Service Flow Profiles for details.

Save Service

Only enabled after form is valid and confirmed

Submit the form to create your service in Shield. This will:

1. Provision your service in the Shield system
2. Generate a Service ID for integration
3. Send you confirmation

Service Flow Profiles

What Are Service Flow Profiles?

Service Flow Profiles let you save common configuration patterns and reuse them when setting up new services. This is especially useful for aggregators with multiple services that share the same flow structure.

What Gets Saved in a Profile?

Included in Profile:

• Country
• MNO
• Carrier Grade NAT
• Header Enriched Flow settings
• WiFi Backup Flow settings
• Number of HTML Pages
• Landing Page URLs (as templates)
• Pages Hosted By
• Shield Integration Pages
• HE Page configuration
• Header names and payment flows
• Custom Referrers, Custom Variables, Block API Variables

NOT Included in Profile (service-specific):

• Service Name
• CSP/Merchant Name
• Type of Service

How to Create a Profile

After Submitting a Service:

1. Fill out and submit your first service completely
2. Click the "Save as Profile" button at the bottom of the form
3. A popup will appear
4. Enter:
   • Profile Name (required): Descriptive name (max 50 characters)
     • Example: "MTN SA - Standard 2-Page HE Flow"
   • Description (optional): Additional details (max 200 characters)
     • Example: "Standard setup for MTN South Africa with 2-page flow, HE on page 1, Shield on both pages"
5. Click Save Profile
6. Your profile is now saved and ready to use

How to Use a Profile

When Creating a New Service:

1. Start the service onboarding form
2. At the top, you'll see "Load Service Flow Profile (Optional)"
3. Click the dropdown and select your saved profile
4. All included fields will be pre-filled automatically
5. Complete the service-specific fields:
   • Service Name
   • CSP/Merchant Name
   • Type of Service (optional)
6. Adjust any pre-filled values if needed for this specific service
7. Submit as normal

Managing Profiles

Viewing Your Profiles: Your profiles are saved in your browser and accessible from the profile dropdown on the onboarding form.

Editing a Profile: Currently, you cannot edit existing profiles directly. To update:

1. Load the profile
2. Make your changes in the form
3. Save as a new profile with an updated name

Deleting a Profile: Currently, there's no delete function. Speak to your account manager if you need to delete or edit a profile.

Profile Best Practices

Naming Conventions: Use clear, descriptive names that identify the configuration:

• Include MNO: "MTN SA..."
• Include flow type: "...2-Page HE Flow"
• Include key details: "...WiFi Backup Enabled"

Good Profile Names:

• MTN SA - Standard 2-Page HE Flow
• Vodacom - 1-Page HE No WiFi
• Airtel KE - 2-Page No HE MSISDN+PIN

When to Create Profiles:

• You have multiple services with identical flow structures
• You're an aggregator onboarding many services
• You frequently set up services on the same MNO

When NOT to Use Profiles:

• Each service has unique configuration
• You're only setting up one or two services
• Configuration varies significantly per service