Game Launch Sequence

The Launch Sequence is the final step in the integration. Your backend requests a signed URL from the smatvirtual gateway, which you then use to redirect the player into the game interface.

The Workflow

Request: Your server calls the launch-url endpoint with player and game metadata.
Validation: We verify your sv-api-key and check player details via your Details URL.
Resolution: Our gateway generates a secure, time-limited link.
Redirect: You send the player to that link.

Currency Synchronization

When initiating a launch request, it is vital to ensure that your player’s wallet currency aligns with your account configuration.

Important: Currently, both the player’s currency and the operator’s base currency of operation must match exactly (e.g., if your operator account is set to NGN, the player must also be playing in NGN).

Multi-Currency Roadmap

We are currently developing a robust multi-currency engine that will allow players to play in any currency regardless of the operator’s base setting.

Experimental Phase: This feature is currently in an experimental phase. Our engineering team is testing the automated conversion and settlement logic. All merchants and partners will receive an official notification once this restriction is lifted and multi-currency support is globally available.

The Launch Request

Endpoint: GET /operator-api/games/generate-launch-url
Base URL: https://api.smatvirtual.com/api/v1.1

Query Parameters

Parameter	Type	Required	Description
`gameId`	`string`	Yes	The unique slug for the game (e.g., `spin-win`, `odd-even`).
`playerId`	`string`	Yes	Your internal unique identifier for the player.
`sessionId`	`string`	Yes	A unique string for this specific session (used for tracking).
`mode`	`string`	No	Use `real` for money play or `demo` for free play. Defaults to `real`.
`disableGameLobby`	`boolean`	No	Set to `true` to skip the selection screen and go straight to the game.
`currency`	`string`	No	ISO code (e.g., `USD`). If omitted, we use the player’s default currency.

Implementation Example

Your backend should construct the request as follows. Ensure your sv-api-key is included in the headers.

curl --request GET \
  --url 'https://api.smatvirtual.com/api/v1.1/operator-api/games/generate-launch-url?gameId=spin-win&playerId=user_99&sessionId=sess_unique_123&disableGameLobby=true&mode=real' \
  --header 'sv-api-key: SV.pk_live_xxxx.smatvirtual-slug'

const axios = require("axios");

async function getLaunchLink() {
  const response = await axios.get(
    "https://api.smatvirtual.com/api/v1.1/operator-api/games/generate-launch-url",
    {
      params: {
        gameId: "spin-win",
        playerId: "user_99",
        sessionId: "unique_session_001",
        disableGameLobby: true,
        mode: "real",
      },
      headers: { "sv-api-key": "SV.pk_live_xxxx.smatvirtual-slug" },
    },
  );

  // Redirect the user to the returned URL
  return response.data.url;
}

Understanding the Response

A successful request returns a JSON object containing the url.

{
  "success": true,
  "url": "https://instant.smatvirtual.com/v1/play?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX..."
}

Important Considerations

Token Expiry

Launch URLs are time-sensitive. You should redirect the player immediately after receiving the URL. Do not cache these links.

Iframe vs. Redirect

You can either redirect the player’s browser or embed the URL in an <iframe>. If using an iframe, ensure it is set to 100% width and height for the best experience.

Troubleshooting common errors

Error Code	Meaning	Solution
401 Unauthorized	Invalid API Key	Check your sv-api-key format (Prefix.Key.Slug).
404 Not Found	Invalid gameId	Verify the game id matches one from the /games list.
504 Timeout	Wallet Timeout	Your Details URL took too long to return the player’s balance.

Next Step: Once the player is in the game, all bets and wins will be communicated to your system via Webhooks.

Getting started

Customization

Webhooks

The Workflow

Currency Synchronization

Multi-Currency Roadmap

The Launch Request

Query Parameters

Implementation Example

Understanding the Response

Important Considerations

Token Expiry

Iframe vs. Redirect

Troubleshooting common errors

​The Workflow

​Currency Synchronization

​Multi-Currency Roadmap

​The Launch Request

​Query Parameters

​Implementation Example

​Understanding the Response

​Important Considerations

Token Expiry

Iframe vs. Redirect

​Troubleshooting common errors

The Workflow

Currency Synchronization

Multi-Currency Roadmap

The Launch Request

Query Parameters

Implementation Example

Understanding the Response

Important Considerations

Troubleshooting common errors