API Reference - Merso Modal Documentation

🌐 Base URLs

Environment	URL
Development	`https://modal.dev.merso.io`
Production	`https://modal.merso.io`

⚠️ Before Starting

Prior to integrating the Merso System API into your game, follow these preliminary steps:

🔑 API Credentials

When a company expresses the desire to integrate Merso into their game, we generate an API Key and a Game ID for them. These are unique identifiers for your project and should be kept confidential to prevent unauthorized access.

⏱️ JWT Token Expiration

The JWT is generated when you first authenticate with the /auth endpoint and will expire every 12 hours, requiring you to re-authenticate to continue making requests.

Required Parameters for /auth

To call the /auth endpoint, the client needs to send the following parameters in the request body:

gameId string Required

Your unique Game ID provided during onboarding.

apiKey string Required

Your secret API Key provided during onboarding.

📋 How to Get Credentials

We provide both parameters to companies once they decide to implement Merso in their games. Contact your Merso representative or reach out to dev@merso.io to get started.

💚 GET /health

Health check endpoint to verify the server is running.

Request

GET /health

Response 200

{
  "success": true,
  "message": "Hello world! Merso Modal Backend is running",
  "timestamp": 1703980800000
}

📄 POST /modal

Returns the modal HTML with injected configuration. Use this endpoint when you need server-side rendered modal with pre-configured data. Send the Item/NFT data to the endpoint to get the modal HTML with the correct data.

Request

POST /modal
Content-Type: application/json

{
  "jwt_token": "eyJhbGciOiJIUzI1NiIs...",
  "product_type": "ITEM",
  
  // For ITEM purchases
  "game_name": "My Game",
  "item_price": "29.99",
  "item_id": "123",
  "item_name": "Premium Sword",
  "player_email": "player@example.com",
  "player_level": "42",
  "player_country": "US",
  
  // For NFT purchases
  "wallet_address": "0x1234...",
  "collection_address": "0xNFT...",
  "token_id": "42",
  "user_email": "user@example.com",
  "token_price": "100",
  "token_name": "Epic NFT",
  "chain_id": "1",
  "token_address": "0xToken..."
}

Response 200

Content-Type: text/html

<!DOCTYPE html>
<html>
  <!-- Modal HTML with injected config -->
  <script>
    window.STRIPE_PUBLISHABLE_KEY = "pk_test_...";
    window.INJECTED_MODAL_CONFIG = {...};
    window.INJECTED_PAYLOAD = {...};
  </script>
  ...
</html>

💡 When to use POST /modal

Use this endpoint when you want the server to fetch the modal configuration from the backend API based on the JWT token's game_id. The configuration (colors, logos, etc.) will be pre-rendered into the HTML. Use it when users select an Item/NFT to purchase.

🎨 Modal Configuration Object

The modal configuration is fetched from the backend API based on the game_id in the JWT token. You can modify the modal configuration inside Merso Dashboard -> Configuration. Here's the complete structure:

TypeScript

interface ModalConfig {
  // Colors
  primaryColor: string;      // Main brand color (default: "#1d4ed8")
  secondaryColor: string;    // Secondary color (default: "#06b6d4")
  backgroundColor: string;   // Modal background (default: "#ffffff")
  textColor: string;         // Primary text (default: "#0f172a")
  accentColor: string;       // Success/accent (default: "#10b981")
  errorColor: string;        // Error states (default: "#ef4444")
  
  // Typography
  fontFamily: string;        // Font stack (default: "Inter, system-ui")
  fontUrl: string | null;    // Google Fonts URL (optional)
  
  // Branding
  logoUrl: string | null;    // Logo image URL (optional)
  modalTitle: string;        // Main heading
  modalSubtitle: string;     // Subheading text
  
  // Styling
  borderRadius: string;      // Modal corners (default: "1.25rem")
  buttonBorderRadius: string;// Button corners (default: "0.75rem")
  
  // Features
  availableBnpl: boolean;    // Enable BNPL option
  availableUpfront: boolean; // Enable Upfront option
}

🔗 Backend API Integration

The modal server communicates with the Merso backend for configuration and payment processing:

Endpoint	Purpose	Called When
`/modal-config`	Fetch modal styling configuration	Modal loads with JWT
`/merso-buy-item`	Create payment intent for items	User selects "Pay with Card" for Item
`/merso-buy-token-with-fiat`	Create payment intent for NFTs	User selects "Pay with Card" for NFT
`/merso-user-approval`	Get approval transaction data	Crypto payment - step 1
`/merso-buy-token`	Get mint transaction data	Crypto payment - step 2

🔐 Auth + JWT Token

Authentication is required to access the Merso API. You'll need your Game ID and API Key (provided during onboarding) to obtain a JWT token.

POST /auth

Verify API connectivity and obtain a JWT token for subsequent requests.

cURL

curl -X POST https://modal.dev.merso.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "YOUR_GAME_ID",
    "api_key": "YOUR_API_KEY"
  }'

Response 200

{
  "authResult": {
    "token": "YOUR_NEW_JWT_TOKEN",
    "expires_at": "2025-08-05T21:21:13.000Z"
  }
}

JavaScript Example

JavaScript

const axios = require('axios');

async function authenticateGame() {
  try {
    const response = await axios.post('https://modal.dev.merso.io/auth', {
      game_id: 'exampleGameId',
      api_key: 'exampleApiKey'
    });
    console.log('Authentication successful:', response.data.authResult);
    return response.data.authResult.token;
  } catch (error) {
    if (error.response) {
      console.error('Error:', error.response.data.error);
    } else {
      console.error('Failed to authenticate game. Error Message:', error.message);
    }
  }
}

🔑 Authentication Setup

JWT Token Setup

During onboarding, you'll receive a custom Game ID token for API access:

JavaScript

// Your custom GameID (provided during onboarding)
const GAME_ID = 'YOUR_GAME_ID';

// API base URL for your game
const API_BASE_URL = 'https://api3.merso.io/game/YOUR_GAME_ID';

Request Headers

All API requests require these headers:

JavaScript

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${JWT_TOKEN}`
};

⚠️ Security Note

Generate JWT tokens server-side only. Never expose your API Key or JWT secret in client-side code. Store tokens securely and refresh them before expiration.

💡 Token Expiration

JWT tokens have an expiration time (returned in expires_at). Implement token refresh logic to ensure uninterrupted API access.

⚠️ Error Handling

The modal displays user-friendly error messages and sends error events via postMessage:

Error Type	Cause	User Message
Missing Parameters	Required URL params missing	"Missing required parameters: ..."
JWT Token Missing	No jwt_token provided	"JWT token is required"
Payment Failed	Stripe/crypto error	"Failed to process payment: ..."
Invalid Combination	Item + Crypto payment	"BNPL Item cannot be paid with crypto"