Skip to main content

​
Overview

As a partner, you integrate with mgPass Rewards by publishing events when users take actions on your platform. The rewards engine matches events to rules, calculates points, and credits them to the user’s balance.

​
Onboarding

  1. MG Digital creates your partner account in the admin console
  2. You receive an API key and a list of allowed event types
  3. You map your user accounts to mgPass user IDs (via email or the mgPass OAuth flow)
  4. You start publishing events

​
Publishing Events

​
Basic Event

curl -X POST https://auth.mgpass.net/api/partner/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "user_id": "usr_abc123",
    "event_type": "article_read"
  }'

​
Event with Metadata

Include metadata for per-unit calculations or audit trails: 
curl -X POST https://auth.mgpass.net/api/partner/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "user_id": "usr_abc123",
    "event_type": "purchase",
    "metadata": {
      "reference_id": "order_789",
      "amount": 150.00,
      "currency": "GHS",
      "item_count": 3
    }
  }'
The reference_id in metadata serves as an idempotency key. Publishing the same reference_id twice will not double-award points.

​
Event Types

Event types are strings that you define with MG Digital during onboarding. Common patterns:
Event TypeDescriptionTypical Points
article_readUser read an article5 per read
video_watchedUser completed a video10 per video
purchaseUser made a purchase1 per GHS spent
signupUser registered on your platform50 (one-time)
referralUser referred someone100 (one-time)
daily_loginUser logged in today5 per day
shareUser shared content10 per share
Your partner config specifies which event types you’re allowed to publish. Attempting to publish an unlisted type returns 403.

​
Points Calculation

Points are calculated using this formula: 
base_points = rule.points (or rule.points * metadata[unit_field] for per-unit rules)
tier_multiplier = user's tier multiplier (e.g., 1.0x for Bronze, 1.5x for Silver)
partner_multiplier = your partner multiplier (default: 1.0x)

final_points = base_points * tier_multiplier * partner_multiplier

​
Example: Per-Unit Rule

If the rule for purchase is “1 point per GHS spent” and the user is Silver tier (1.5x): 
Event: { event_type: "purchase", metadata: { amount: 100 } }
Rule: { points: 1, points_type: "per_unit", unit_field: "amount" }
Calculation: 1 * 100 (amount) * 1.5 (tier) = 150 points

​
Caps and Frequency

Rules can have daily and monthly caps to prevent abuse:
Cap TypeDescription
daily_capMaximum points from this event type per user per day
monthly_capMaximum points from this event type per user per month
frequencyHow often the event can be counted: once, daily, weekly, monthly, unlimited
If a cap is reached, the event is still accepted but points_awarded will be 0 or reduced.

​
Response Handling

​
Success

{
  "accepted": true,
  "points_awarded": 150,
  "event_id": "evt_xyz789"
}

​
No Matching Rule

{
  "accepted": true,
  "points_awarded": 0,
  "event_id": "evt_xyz789"
}
Events with no matching rule are still accepted and logged. Points awarded will be 0. This allows you to start publishing events before rules are configured.

​
Errors

StatusErrorDescription
400invalid_requestMissing user_id or event_type
401unauthorizedInvalid or missing API key
403forbiddenEvent type not in your allowed list
429rate_limit_exceededToo many requests (30/min)

​
Code Examples

const response = await fetch('https://auth.mgpass.net/api/partner/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.MGPASS_API_KEY,
  },
  body: JSON.stringify({
    user_id: userId,
    event_type: 'article_read',
    metadata: { reference_id: articleId },
  }),
});

const result = await response.json();
console.log(`Awarded ${result.points_awarded} points`);

​
Webhooks

You can receive notifications when points-related events occur. See the Webhooks guide for setup details.

​
Single Sign-On for Your Users

If your users also have mgPass accounts, you can offer seamless SSO using the One Tap SDK. When a user visits your site while logged into mgPass, the SDK shows a “Continue as [Name]” banner that lets them sign in with a single click — no passwords, no redirects.

One Tap SDK Guide

Full integration guide for the One Tap SDK. One script tag, one function call.

SSO Architecture

How mgPass SSO works across same-domain and cross-domain applications.

​
Testing

Use the staging environment for testing: 
Base URL: https://auth.mgpass.net
Staging uses the same API key format but with a separate key issued for testing.