Midasbuy Minigame SDK API Protocol

1. Overview

Midasbuy Minigame SDK is a unified mini-game SDK loader and adapter that provides consistent API interfaces for Menu, Payment, and Login function modules.

2. SDK Integration

<script src="https://cdn.midasbuy.com/js/minigame.stable.js"></script>

3. API Protocol

3.1 Initialization `midas.minigame(options)`

const minigameApi = midas.minigame({
  // Basic Configuration
  appid: '1460000904',
  region: 'us',
  language: 'en',
  sandbox: 1,
  shopcode: 'ludoinapp',
  reportDevMode: 0,
  
  // Menu Module Configuration, optional
  menu: {
    isWithPcHeader: true
  },
  
  // Payment Module Configuration, optional
  payment: {
    openid: '1018553529511732',
    charac_name: 'Player1',
    useIpCountry: true,
  },
  
  // Login Module Configuration, optional
  login: {
    environment: 'sandbox',
    debug: true,
    timeout: 30000
  }
});

Parameter Description

Parameter	Type	Required	Description
appid	string	Yes	Application ID
region	string	Yes	Region code, 2 characters
language	string	No	Language code, default 'en'
sandbox	number	No	Environment: 0-production, 1-sandbox, 2-test, default 0
shopcode	string	No	Shop code
reportDevMode	number	No	Report development mode: 0-off, 1-on, default 0
menu	MenuConfig	No	Menu module configuration
payment	PaymentConfig	No	Payment module configuration
login	LoginConfig	No	Login module configuration

MenuConfig Type

interface MenuConfig {
  isWithPcHeader?: boolean;  // Whether to include top header on PC
}

PaymentConfig Type

interface PaymentConfig {
  openid?: string;           // User openid
  charac_name?: string;      // Character name
  useIpCountry?: boolean;    // Whether to use IP country
}

LoginConfig Type

interface LoginConfig {
  environment?: 'production' | 'sandbox';  // Environment configuration
  debug?: boolean;                          // Debug mode
  timeout?: number;                         // Request timeout (milliseconds)
}

3.2.1 Show Menu `minigameApi.showMenu(options)`

// Show game menu
minigameApi.showMenu({
  gradually: true
});

Parameter Description

Parameter	Type	Required	Description
gradually	boolean	No	Whether to show progressively, default true

3.2.2 Hide Menu `minigameApi.hideMenu(options)`

// Hide game menu
minigameApi.hideMenu({
  gradually: true
});

Parameter Description

Parameter	Type	Required	Description
gradually	boolean	No	Whether to hide progressively, default true

3.3 Payment Functions

3.3.1 Show Payment Page `minigameApi.showPayment(options)`

Event-based Style (Legacy):

// Show payment page with event listeners
minigameApi.on('payment:success', (data) => {
  console.log('Payment successful:', data);
});

minigameApi.on('payment:failed', (error) => {
  console.log('Payment failed:', error);
});

minigameApi.showPayment({
  params: {
    game_openid: '1018553529511732',
    role_id: '1555629938',
    product_id: 'coins_01-midasbuy'
  },
  extra: {
    hideResultPage: true
  }
});

Promise Style (Recommended):

// Show payment page with Promise
minigameApi.showPayment({
  params: {
    game_openid: '1018553529511732',
    role_id: '1555629938',
    product_id: 'coins_01-midasbuy',
    server_id: 'server_001'
  },
  extra: {
    hideResultPage: true
  }
})
.then(data => {
  console.log('Payment successful:', data);
  // data contains: { order_no, openid, order_no_hash }
})
.catch(error => {
  console.log('Payment error:', error);
  
  // Handle different error types
  switch(error.type) {
    case 'failed':
      console.log('Payment failed:', error.data);
      break;
    case 'hide':
      console.log('Payment dialog was closed');
      break;
    case 'queryChannelsFailed':
      console.log('Failed to load payment channels:', error.data);
      break;
  }
});

// Using async/await
async function handlePayment() {
  try {
    const result = await minigameApi.showPayment({
      params: {
        game_openid: '1018553529511732',
        role_id: '1555629938',
        product_id: 'coins_01-midasbuy',
        server_id: 'server_001'
      }
    });
    console.log('Payment successful:', result);
  } catch (error) {
    console.log('Payment failed:', error.type, error.message);
  }
}

Parameter Description

Parameter	Type	Required	Description
params	PaymentParams	Yes	Payment parameters
extra	PaymentExtra	No	Additional payment parameters

PaymentParams Type

interface PaymentParams {
  game_openid: string;    // Game user ID
  role_id: string;        // Role ID
  product_id: string;     // Product ID
  server_id?: string;     // Server ID for game partitioning
  is_vip_product?: boolean; // Whether it's a VIP product
}

PaymentExtra Type

interface PaymentExtra {
  hideResultPage?: boolean; // Whether to hide result page
}

PaymentError Type

interface PaymentError extends Error {
  code: string;                                    // Error code
  type: 'failed' | 'hide' | 'queryChannelsFailed'; // Error type
  data?: any;                                      // Additional error data
  timestamp: number;                               // Error timestamp
}

Error Types

Type	Description	When it occurs
`failed`	Payment transaction failed	User payment was unsuccessful
`hide`	Payment dialog closed	User closed the payment dialog
`queryChannelsFailed`	Failed to load payment channels	Network error or invalid product

3.3.2 Hide Payment Page `minigameApi.hidePayment()`

// Hide payment page
minigameApi.hidePayment();

3.4.1 User Login `minigameApi.login(options)`

Callback Style:

// User login with callbacks
minigameApi.login({
  success: function(result) {
    console.log('Login successful:', result);
  },
  fail: function(error) {
    console.log('Login failed:', error);
  }
});

Promise Style:

// User login with Promise
minigameApi.login()
  .then(result => {
    console.log('Login successful:', result);
  })
  .catch(error => {
    console.log('Login failed:', error);
  });

// Or using async/await
async function handleLogin() {
  try {
    const result = await minigameApi.login();
    console.log('Login successful:', result);
  } catch (error) {
    console.log('Login failed:', error);
  }
}

Parameter Description:

Parameter	Type	Required	Description
success	Function	No	Login success callback function
fail	Function	No	Login failure callback function

Note: When using Promise style, you can omit the success and fail callbacks and use .then() and .catch() instead.

Success Callback Parameters:

{
  code: 0,
  message: 'success',
  data: {
    jwtToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    expiresIn: 3600,
    refreshToken: 'rt_xxxxxxxxxxxxxxxx'
  }
}

Failure Callback Parameters:

{
  code: -1,
  message: 'Error description',
  error: 'ERROR_CODE'
}

3.5 Event Listening `minigameApi.on(event, callback)`

// Game menu events
minigameApi.on('menu:show', (data) => {
  console.log('Game menu shown successfully', data);
});

minigameApi.on('menu:hide', () => {
  console.log('Game menu hidden');
});

minigameApi.on('menu:error', (error) => {
  console.error('Game menu error', error);
});

// Payment events
minigameApi.on('payment:success', (data) => {
  console.log('Payment successful', data);
});

minigameApi.on('payment:failed', (error) => {
  console.log('Payment failed', error);
});

minigameApi.on('payment:hide', () => {
  console.log('Payment page hidden');
});

minigameApi.on('payment:queryChannelsFailed', (error) => {
  console.log('Query channels failed', error);
});

// Login events
minigameApi.on('login:success', (data) => {
  console.log('Login successful', data);
});

minigameApi.on('login:failed', (error) => {
  console.log('Login failed', error);
});

minigameApi.on('login:statusChanged', (status) => {
  console.log('Login status changed', status);
});

minigameApi.on('login:tokenExpired', () => {
  console.log('Token expired');
});

// Common events
minigameApi.on('sdk:loaded', (modules) => {
  console.log('SDK loaded successfully', modules);
});

minigameApi.on('sdk:error', (error) => {
  console.error('SDK error', error);
});

Event Types

Event Name	Description	Callback Parameters
`menu:show`	Game menu shown successfully	`{ res: string, size?: { width?: string, height?: string } }`
`menu:hide`	Game menu hidden	None
`menu:error`	Game menu error	`Error`
`payment:success`	Payment successful	`{ order_no: string, openid: string, order_no_hash: string }`
`payment:failed`	Payment failed	`Error`
`payment:hide`	Payment page hidden	None
`payment:queryChannelsFailed`	Query channels failed	`Error`
`login:success`	Login successful	`{ jwtToken: string, userInfo: object }`
`login:failed`	Login failed	`Error`
`login:statusChanged`	Login status changed	`'logged_in' \| 'logged_out' \| 'token_expired'`
`login:tokenExpired`	Token expired	None
`sdk:loaded`	SDK loaded successfully	`string[]` (List of loaded modules)
`sdk:error`	SDK error	`Error`

3.6 Remove Event Listener `minigameApi.off(event, callback?)`

// Remove specific callback
minigameApi.off('payment:success', callback);

// Remove all callbacks
minigameApi.off('payment:success');

3.7 Utility Methods

3.7.1 Get Module Instance `minigameApi.getModule(module)`

Get direct access to specific module instances for advanced usage.

// Get menu module instance
const menuModule = minigameApi.getModule('menu');
if (menuModule) {
  // Direct access to menu module methods
  menuModule.show({ gradually: false });
}

// Get payment module instance
const paymentModule = minigameApi.getModule('payment');
if (paymentModule) {
  // Direct access to payment module methods
  paymentModule.emit('checkout', params);
}

// Get login module instance
const loginModule = minigameApi.getModule('login');
if (loginModule) {
  // Direct access to login module methods
  const isLoggedIn = loginModule.isLoggedIn();
}

Parameter Description

Parameter	Type	Required	Description
module	string	Yes	Module name: 'menu', 'payment', or 'login'

Return Value

Returns the corresponding module instance, or null if the module is not loaded or invalid.

3.7.2 Hide All Modules `minigameApi.hideAll()`

// Hide all modules (menu, payment, etc.)
minigameApi.hideAll();

4. Error Handling

4.1 Error Types

```typescript
interface MinigameError extends Error {
  code: string;
  module?: 'menu' | 'payment' | 'login' | 'core';
  details?: any;
}

4.2 Error Codes

Error Code	Description
`INIT_FAILED`	Initialization failed
`MODULE_NOT_LOADED`	Module not loaded
`INVALID_PARAMS`	Invalid parameters
`SHOW_FAILED`	Show failed
`HIDE_FAILED`	Hide failed
`PAYMENT_FAILED`	Payment failed
`NETWORK_ERROR`	Network error

4.3 Global Error Handling

minigameApi.setErrorHandler((error) => {
  console.error('Minigame SDK Error:', error);
  // Custom error handling logic
});

5. Type Definitions

declare namespace midas {
  interface MinigameAPI {
    showMenu(options?: MenuShowOptions): Promise<ShowResult>;
    hideMenu(options?: MenuHideOptions): void;
    showPayment(options: PaymentShowOptions): Promise<PaymentResult>;
    hidePayment(): void;
    hideAll(): void;
    login(options: LoginOptions): Promise<LoginResult>;
    getLoginStatus(): boolean;
    getUserInfo(): UserInfo | null;
    logout(): void;
    on(event: string, callback: Function): void;
    off(event: string, callback?: Function): void;
    getModule(module: 'menu' | 'payment' | 'login'): any;
    setErrorHandler(handler: (error: MinigameError) => void): void;
  }

  interface MenuShowOptions {
    gradually?: boolean;
  }

  interface MenuHideOptions {
    gradually?: boolean;
  }

  interface PaymentShowOptions {
    params: PaymentParams;
    extra?: PaymentExtra;
  }

  interface ShowResult {
    res: string;
    size?: {
      width?: string;
      height?: string;
    };
  }

  interface LoginOptions {
    success?: (result: LoginResult) => void;
    fail?: (error: LoginError) => void;
  }

  interface LoginError {
    code: number;
    message: string;
    error: string;
  }

  interface LoginResult {
    code: number;
    message: string;
    data: {
      jwtToken: string;
      expiresIn: number;
      refreshToken: string;
    };
  }

  interface PaymentResult {
    order_no: string;        // Order number
    openid: string;          // User ID
    order_no_hash: string;   // Order hash
  }

  interface PaymentError extends Error {
    code: string;
    type: 'failed' | 'hide' | 'queryChannelsFailed';
    data?: any;
    timestamp: number;
  }

  function minigame(options: MinigameOptions): MinigameAPI;
}

6. Usage Examples

6.1 Complete Example

// Initialize SDK
const minigameApi = midas.minigame({
  appid: '1460000904',
  region: 'us',
  language: 'en',
  sandbox: 1,
  shopcode: 'ludoinapp',
  reportDevMode: 0,
  menu: {
    isWithPcHeader: true
  },
  payment: {
    openid: '1018553529511732'
  },
  login: {
    environment: 'sandbox',
    debug: true,
    timeout: 30000
  }
});

// Listen to events
minigameApi.on('sdk:loaded', (modules) => {
  console.log('SDK loaded successfully:', modules);
  
  // Get module instances for direct access
  const menuModule = minigameApi.getModule('menu');
  const paymentModule = minigameApi.getModule('payment');
  const loginModule = minigameApi.getModule('login');
  
  console.log('Menu module:', menuModule);
  console.log('Payment module:', paymentModule);
  console.log('Login module:', loginModule);
});

minigameApi.on('payment:success', (data) => {
  console.log('Payment successful:', data);
  // Hide payment page
  minigameApi.hidePayment();
});

minigameApi.on('login:success', (data) => {
  console.log('Login successful:', data);
  // Show game menu after login
  minigameApi.showMenu({
    gradually: true
  });
});

minigameApi.on('login:statusChanged', (status) => {
  console.log('Login status changed:', status);
});

// User login - Callback style
minigameApi.login({
  success: function(result) {
    console.log('Login successful:', result);
  },
  fail: function(error) {
    console.log('Login failed:', error);
  }
});

// User login - Promise style
minigameApi.login()
  .then(result => {
    console.log('Login successful:', result);
    // Show game menu after successful login
    return minigameApi.showMenu({ gradually: true });
  })
  .catch(error => {
    console.log('Login failed:', error);
  });

// Show game menu
minigameApi.showMenu({
  gradually: true
});

// Show payment page - Promise style (recommended)
minigameApi.showPayment({
  params: {
    game_openid: '1018553529511732',
    role_id: '1555629938',
    product_id: 'coins_01-midasbuy',
    server_id: 'server_001'
  },
  extra: {
    hideResultPage: true
  }
})
.then(result => {
  console.log('Payment successful:', result);
  // result contains: { order_no, openid, order_no_hash }
})
.catch(error => {
  console.log('Payment error:', error.type, error.message);
  
  // Handle specific error types
  if (error.type === 'queryChannelsFailed') {
    console.log('Please check your network connection');
  } else if (error.type === 'hide') {
    console.log('Payment was cancelled by user');
  }
});

7. Best Practices

7.1 Error Handling

minigameApi.setErrorHandler((error) => {
  // Report error to monitoring system
  reportError(error);
  
  // User-friendly error messages
  if (error.code === 'PAYMENT_FAILED') {
    showToast('Payment failed, please try again later');
  }
});

7.2 Promise-based Payment Flow

// Modern async/await payment flow
class PaymentManager {
  constructor(minigameApi) {
    this.minigameApi = minigameApi;
  }

  async processPayment(productId, userId, roleId) {
    try {
      console.log('Starting payment process...');
      
      const result = await this.minigameApi.showPayment({
        params: {
          game_openid: userId,
          role_id: roleId,
          product_id: productId,
          server_id: 'server_001'
        },
        extra: {
          hideResultPage: true
        }
      });

      // Payment successful
      console.log('Payment completed successfully:', result);
      this.handlePaymentSuccess(result);
      return result;

    } catch (error) {
      console.log('Payment error occurred:', error);
      this.handlePaymentError(error);
      throw error;
    }
  }

  handlePaymentSuccess(result) {
    // Update game state, unlock content, etc.
    console.log(`Order ${result.order_no} completed for user ${result.openid}`);
    
    // Show success message
    this.showNotification('Payment successful! Your purchase is now available.');
  }

  handlePaymentError(error) {
    switch (error.type) {
      case 'failed':
        this.showNotification('Payment failed. Please try again.');
        this.trackEvent('payment_failed', error.data);
        break;
      
      case 'hide':
        this.showNotification('Payment was cancelled.');
        this.trackEvent('payment_cancelled');
        break;
      
      case 'queryChannelsFailed':
        this.showNotification('Unable to load payment options. Please check your connection.');
        this.trackEvent('payment_channels_failed', error.data);
        break;
    }
  }

  showNotification(message) {
    // Show user-friendly notification
    console.log(`[Notification] ${message}`);
  }

  trackEvent(eventName, data = null) {
    // Track analytics event
    console.log(`[Analytics] ${eventName}`, data);
  }
}

// Modern async/await login flow
class GameManager {
  constructor() {
    this.minigameApi = midas.minigame(config);
    this.setupEventListeners();
  }

  async initializeGame() {
    try {
      // Wait for SDK to load
      await this.waitForSDKLoad();
      
      // Attempt login
      const loginResult = await this.minigameApi.login();
      console.log('User logged in:', loginResult.data.jwtToken);
      
      // Show game menu after successful login
      await this.minigameApi.showMenu({ gradually: true });
      
    } catch (error) {
      console.error('Game initialization failed:', error);
      this.handleInitError(error);
    }
  }

  waitForSDKLoad() {
    return new Promise((resolve) => {
      this.minigameApi.on('sdk:loaded', resolve);
    });
  }

  handleInitError(error) {
    // Handle initialization errors
    if (error.code === 'MODULE_NOT_LOADED') {
      console.error('SDK modules not loaded properly');
    }
  }
}

7.4 Event Management

// Use event delegation pattern
class GameManager {
  constructor() {
    this.minigameApi = midas.minigame(config);
    this.setupEventListeners();
  }

  setupEventListeners() {
    this.minigameApi.on('payment:success', this.handlePaymentSuccess.bind(this));
    this.minigameApi.on('menu:show', this.handleMenuShow.bind(this));
  }

  handlePaymentSuccess(data) {
    // Handle payment success
    this.updateGameState(data);
  }

  handleMenuShow(data) {
    // Handle menu show
    this.trackEvent('menu_show', data);
  }
}

1. Overview​

2. SDK Integration​

3. API Protocol​

3.1 Initialization midas.minigame(options)​

Parameter Description​

MenuConfig Type​

PaymentConfig Type​

LoginConfig Type​

3.2 Menu Functions​

3.2.1 Show Menu minigameApi.showMenu(options)​

Parameter Description​

3.2.2 Hide Menu minigameApi.hideMenu(options)​

Parameter Description​

3.3 Payment Functions​

3.3.1 Show Payment Page minigameApi.showPayment(options)​

Parameter Description​

PaymentParams Type​

PaymentExtra Type​

PaymentError Type​

Error Types​

3.3.2 Hide Payment Page minigameApi.hidePayment()​

3.4 Login Functions​

3.4.1 User Login minigameApi.login(options)​

3.5 Event Listening minigameApi.on(event, callback)​

Event Types​

3.6 Remove Event Listener minigameApi.off(event, callback?)​

3.7 Utility Methods​

3.7.1 Get Module Instance minigameApi.getModule(module)​

Parameter Description​

Return Value​

3.7.2 Hide All Modules minigameApi.hideAll()​

4. Error Handling​

4.1 Error Types​

4.2 Error Codes​

4.3 Global Error Handling​

5. Type Definitions​

6. Usage Examples​

6.1 Complete Example​

7. Best Practices​

7.1 Error Handling​

7.2 Promise-based Payment Flow​

7.3 Promise-based Login Flow​

7.4 Event Management​

1. Overview

2. SDK Integration

3. API Protocol

3.1 Initialization `midas.minigame(options)`

Parameter Description

MenuConfig Type

PaymentConfig Type

LoginConfig Type

3.2 Menu Functions

3.2.1 Show Menu `minigameApi.showMenu(options)`

Parameter Description

3.2.2 Hide Menu `minigameApi.hideMenu(options)`

Parameter Description

3.3 Payment Functions

3.3.1 Show Payment Page `minigameApi.showPayment(options)`

Parameter Description

PaymentParams Type

PaymentExtra Type

PaymentError Type

Error Types

3.3.2 Hide Payment Page `minigameApi.hidePayment()`

3.4 Login Functions

3.4.1 User Login `minigameApi.login(options)`

3.5 Event Listening `minigameApi.on(event, callback)`

Event Types

3.6 Remove Event Listener `minigameApi.off(event, callback?)`

3.7 Utility Methods

3.7.1 Get Module Instance `minigameApi.getModule(module)`

Parameter Description

Return Value

3.7.2 Hide All Modules `minigameApi.hideAll()`

4. Error Handling

4.1 Error Types

4.2 Error Codes

4.3 Global Error Handling

5. Type Definitions

6. Usage Examples

6.1 Complete Example

7. Best Practices

7.1 Error Handling

7.2 Promise-based Payment Flow

7.3 Promise-based Login Flow

7.4 Event Management