Skip to main content
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

  1. Request: Your server calls the launch-url endpoint with player and game metadata.
  2. Validation: We verify your sv-api-key and check player details via your Details URL.
  3. Resolution: Our gateway generates a secure, time-limited link.
  4. 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/generate-launch-url
Base URL: https://api.smatvirtual.com/api/v1.1

​
Query Parameters

ParameterTypeRequiredDescription
gameIdstringYesThe unique slug for the game (e.g., spin-win, odd-even).
playerIdstringYesYour internal unique identifier for the player.
sessionIdstringYesA unique string for this specific session (used for tracking).
modestringNoUse real for money play or demo for free play. Defaults to real.
disableGameLobbybooleanNoSet to true to skip the selection screen and go straight to the game.
currencystringNoISO 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/launch-url?gameId=spin-win&playerId=user_99&sessionId=sess_unique_123&disableGameLobby=true&mode=real](https://api.smatvirtual.com/api/v1.1/operator-api/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'

​
Understanding the Response

A successful request returns a JSON object containing the url. 

{
  "success": true,
  "url": "[https://instant.smatvirtual.com/v1/play?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX](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 CodeMeaningSolution
401 UnauthorizedInvalid API KeyCheck your sv-api-key format (Prefix.Key.Slug).
404 Not FoundInvalid gameIdVerify the game id matches one from the /games list.
504 TimeoutWallet TimeoutYour 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.