🔐 Widget V2 - Secure Integration

Widget V2 provides an enhanced security model that protects your API credentials and adds IP whitelisting capabilities. Unlike Widget V1, your API key is never exposed in client-side code.

✨ Key Security Features

• 🔒 API Key Protection: API keys never exposed in client-side code
• 🛡️ IP Whitelisting: Restrict widget access to authorized IPs only
• ⏱️ Session-Based: Time-limited session keys for enhanced security
• 🎯 Reduced Attack Surface: No sensitive parameters visible in browser

Integration Overview

Widget V2 uses a two-step integration process:

1️⃣

Create Session (Server-Side)

Call API with your parameters to get session key

2️⃣

Initialize Widget (Client-Side)

Use session key to render widget

---

Step 1: Create Session (Server-Side)

First, call the session creation API from your backend server (never from client-side) with the widget parameters.

API Endpoint

POST/v1/merchant/session

Staging:https://stg.api.onmeta.in/v1/merchant/session
Production:https://api.platform.onmeta.in/v1/merchant/session

Headers

Header	Type	Required	Description
Content-Type	string	Yes	application/json
x-api-key	string	Yes	Your API key from merchant dashboard

Request Parameters

All parameters from Widget V1 are supported (except apiKey which goes in header).

📋 Widget V2 Session Parameters

Parameter	Type	Required	Description	Example
chainId	number	Optional	Blockchain network ID. Example: 137 for Polygon.	137
walletAddress	string	Required	Wallet address to receive crypto tokens. Must be provided during widget initialization. Users cannot enter wallet address manually.	"0xEcc24..."
fiatAmount	number	Optional	Pre-filled amount for purchase.	1000
onRamp	string	Optional	Enable buy crypto functionality (on-ramp). Default: "enabled"	"enabled"
offRamp	string	Optional	Enable sell crypto functionality (off-ramp). Default: "disabled"	"disabled"
fiatType	string	Optional	Fiat currency to use. Supported: "inr" (Indian Rupee), "php" (Philippine Peso), "idr" (Indonesian Rupiah)	"inr"
userEmail	string	Optional	User's email address. If provided, skips registration step in widget.	"user@..."
tokenAddress	string	Optional	Contract address of token. Use with chainId to show specific token. Otherwise shows all tokens from chain.	"0xEcc24..."
tokenSymbol	string	Optional	Token symbol (e.g., USDT, USDC). Alternative to tokenAddress for filtering tokens.	"USDT"
paymentMethod	string	Optional	Pre-select Payment Method (e.g., INR_UPI, INR_IMPS).	"INR_UPI"
metaData	object	Optional	Custom data sent with webhook events. Must be key-value pairs of strings only.	{userId: "..."}
successRedirectUrl	string	Optional	URL to redirect on successful order. Must start with http:// or https://	"https://..."
failureRedirectUrl	string	Optional	URL to redirect on order failure. Must start with http:// or https://	"https://..."

Example Request

cURL

curl --location 'https://stg.api.onmeta.in/v1/merchant/session' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
  "chainId": 137,
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "fiatAmount": 1000,
  "onRamp": true,
  "offRamp": false,
  "fiatType": "INR",
  "successRedirectUrl": "https://merchant.example/success",
  "failureRedirectUrl": "https://merchant.example/failure",
  "metaData": {
    "source": "test",
    "userId": "u_1"
  },
  "tokenSymbol": "USDT",
}'

Node.js

const axios = require('axios');

async function createWidgetSession() {
  try {
    const response = await axios.post(
      'https://stg.api.onmeta.in/v1/merchant/session',
      {
        chainId: 137,
        walletAddress: '0x1111111111111111111111111111111111111111',
        fiatAmount: 1000,
        onRamp: true,
        offRamp: false,
        fiatType: 'INR',
        successRedirectUrl: 'https://merchant.example/success',
        failureRedirectUrl: 'https://merchant.example/failure',
        metaData: {
          source: 'test',
          userId: 'u_1'
        },
        tokenSymbol: 'USDT',
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
        }
      }
    );

    return response.data;
  } catch (error) {
    console.error('Error creating session:', error);
    throw error;
  }
}

Python

import requests
import json

def create_widget_session():
    url = "https://stg.api.onmeta.in/v1/merchant/session"
    
    headers = {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    }
    
    payload = {
        "chainId": 137,
        "walletAddress": "0x1111111111111111111111111111111111111111",
        "fiatAmount": 1000,
        "onRamp": True,
        "offRamp": False,
        "fiatType": "INR",
        "successRedirectUrl": "https://merchant.example/success",
        "failureRedirectUrl": "https://merchant.example/failure",
        "metaData": {
            "source": "test",
            "userId": "u_1"
        },
        "tokenSymbol": "USDT",
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as error:
        print(f"Error creating session: {error}")
        raise

Response

{
  "success": true,
  "data": {
    "expiresAt": 1770565300,
    "sessionKey": "eyJhbGciO......."
  },
  "error": {}
}

ℹ️

Session Key Expiration

The sessionKey is time-limited for security. Check the expiresAt timestamp (Unix epoch). Generate a new session key if expired.

---

Step 2: Initialize Widget (Client-Side)

Use the session key received from Step 1 to initialize the widget on your frontend.

Include SDK Script

Add the Widget V2 SDK script to your HTML:

Staging

<script src="https://stg.platform.onmeta.in/onmeta-sdk.v2.js"></script>

Production

<script src="https://platform.onmeta.in/onmeta-sdk.v2.js"></script>

Complete Integration Example

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Onmeta Widget V2 Integration</title>
</head>
<body>
  <!-- Widget container -->
  <div id="onmeta"></div>

  <!-- Include Widget V2 SDK -->
  <script src="https://stg.platform.onmeta.in/onmeta-sdk.v2.js"></script>
  
  <!-- Initialize Widget -->
  <script>
    // Initialize widget with session key from your backend
    const widget = new window.onMetaWidgetV2({
      sessionKey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // From Step 1
      elementId: "onmeta",
      environment: "staging",
      widgetHeight: "54rem" // Optional
    });

    // Render the widget
    widget.init();
  </script>
</body>
</html>

Widget V2 Configuration

Parameter	Type	Required	Description
sessionKey	string	Yes	Session key obtained from /v1/merchant/session API
elementId	string	Yes	ID of HTML element where widget renders
environment	string	Yes	"staging" or "production"
widgetHeight	string	No	Height of widget

---

Widget V1 vs Widget V2

Feature	Widget V1	Widget V2
API Key Exposure	❌ Exposed in URL	✅ Hidden (server-side only)
IP Whitelisting	❌ Not available	✅ Supported
Session Management	❌ Stateless	✅ Time-limited sessions
Integration Steps	1 step (client-side)	2 steps (server + client)
Security Level	⚠️ Basic	✅ Enhanced

---

Troubleshooting

Session Key Expired

Solutions:

• Check the expiresAt timestamp before using the session key
• Generate a new session key from your backend
• Initialize widget with the new key

Widget Not Rendering

Solutions:

• Verify the elementId matches your HTML element ID
• Check browser console for JavaScript errors
• Ensure SDK script loaded successfully
• Confirm session key is valid and not expired

---