One app. One configuration reference.
Try it first
Configure one game and its services#
You need A studio-owned game and a choice of managed, self-hosted or hybrid services.
- Confirm the selected app and its unique Game ID.
- Configure browser settings and keep server secrets in your backend or vault.
- Test a purchase and contest entry beside the running game; inspect verification and delivery separately.
Check your result Each enabled service has an owner, configuration and a tested integration path.
Start with your selected app in Developer tools → Game setup. Configure only the services your game uses. Keep the same game, studio, environment and player identity through checkout, verification and fulfillment.
1. Decide who runs each part#
| Mode | Payment processing | Trusted game backend | Wallet responsibility |
|---|---|---|---|
| Self Hosted | Your processor, or Playmos by explicit choice | Your server creates orders, verifies receipts, grants items and validates scores | Player approves purchases; your authorized operator manages server signing. |
| Hybrid Managed | Playmos Managed IAP / contest payment rail | Your server owns fulfillment and admission; callback server can be yours | Player checkout and studio payout wallets remain separate. |
| Fully Managed | Configured Playmos services | Provisioned services must explicitly support the game’s inventory, admission and scoring | Managed custody needs a configured signing provider; vaulted API keys do not authorize signing. |
Hosting the browser page, processing money, granting inventory and signing server operations are four separate capabilities. The game’s service readiness checks show what is actually configured. An uploaded ZIP or successful payment does not enable the other capabilities automatically.
2. App identity and hosting#
| Value | Required when | Where it comes from / where it belongs |
|---|---|---|
| App name | Every game | Your studio app record. Visible above the testing tabs. |
| Game identifier / externalId | Creating a Managed IAP app connection | Choose 1–80 letters, numbers, dashes or underscores. Availability is checked within your SDK studio; saving claims it atomically. Keep it stable. |
| gameId / registered SDK game ID | Playmos payment calls | Use the exact server-returned ID. Do not substitute a draft UUID, Studio session ID, product ID or display name. |
| Studio session + build version / buildSha256 | Studio managed credential access | Select the exact saved build. New builds require their own credential binding. |
| Draft ID + package build ID | Uploaded browser game | Your Publisher draft and the uploaded build record. These identify the game release, not its payment rail. |
| entryPath / entryQuery | ZIP hosting | Relative HTML entry file, usually index.html, and optional public launch parameters. No credentials in query strings. |
| Playable URL / selfHostedOrigin | External hosting | Separate-origin HTTPS page. Local HTTP is supported for development. |
| backendOrigins | Uploaded builds calling a backend | Exact HTTPS API origins allowed by the build’s CSP. Never wildcard an authenticated API. |
| Hub / portal origin | SDK checkout bridge or development adapter | Exact parent origin, such as https://test.playmos.io. Your frame-ancestors policy must permit it. |
3. Browser-safe SDK values#
| SDK value | Required when | Rule |
|---|---|---|
| apiKey: pk_test_… | Playmos payment processing | Publishable key from the same studio as the registered game. An external processor needs no Playmos payment credentials. |
| network: base-sepolia | Test payments | Base Sepolia chain ID 84532. Test USDC has no cash value. |
| apiBaseUrl | Explicit test service routing | SDK API base including /v1, currently https://api.test.playmos.io/v1 on the test Hub. Keep the same environment on client and server. |
| playerId | Each paid order / attempt | Authenticated game player from your server. Do not trust a player ID supplied by an arbitrary browser. |
| wallet.provider | Wallet-funded standalone / parent-host checkout | Your EIP-1193 provider. Embedded Hub games request checkout through createCheckoutBridge; no wallet provider crosses the iframe. |
| wallet.delegatedBatch | Same-address atomic Base Sepolia checkout | Pinned implementation + bytecode hash, payer, chain reads, receipt lookup and authorization hook. SDK batches approval and payment; no sequential fallback. |
| gas.mode / paymasterUrl | Choosing who pays gas | Player-funded gas or an explicitly configured sponsored provider. Never switch payer after uncertainty. |
| services.purchase / services[contest-entry] | Registered Hub checkout host | Declare processing and fulfillment independently. The host registers these capabilities; the iframe does not choose its own authority. |
npm install @playmos/sdk@0.3.38
4. IAP catalogue and fulfillment#
| Value / contract | Required when | Owner and behavior |
|---|---|---|
| sku, name, amount, type, active | Managed IAP product | Payment server catalogue. CSV / Excel import manages these records; the game keeps item effects and inventory logic. |
| catalogVersion | Freezing an order | Server-returned catalogue revision. The saved quote pins the product and amount before payment. |
| App Store / Google Play product IDs | Native store integration | Keep native IDs mapped to the same logical SKU. Native billing, server receipt verification, notifications and restore remain separate provider integrations. |
| order ID + idempotencyKey / requestId | Every checkout | Create and persist before signing. Retry the same order and payment; do not create a replacement on timeout. |
| onIntent / onSigning / onWalletCalls | Wallet checkout recovery | Durably bind the intent, signing uncertainty and wallet batch before the next operation. |
| Create / bind / complete backend methods | Self-hosted or hybrid fulfillment | Authenticated game backend creates the frozen quote, binds its exact payment and verifies before granting once. Route names are yours. |
| Callback URL + webhook signing secret | Webhook delivery | HTTPS receiver on your backend. Verify raw bytes with verifyWebhook from @playmos/sdk/server and X-Playmos-Signature, then deduplicate. A callback acknowledgement is not inventory delivery. |
Manual backend walkthrough · Checkout variants · Webhook verification
5. Contests and prize pools#
| Value | Required when | Keep it consistent |
|---|---|---|
| poolAddress / prizePool contract | Playmos contest payments | Use your registered pool and its chain. Legacy rounds and epoch series have different APIs. |
| series + epoch OR roundId / roundKey | Your chosen contest contract | Persist the exact server-created round identity. Never mix an epoch ID with the legacy enterRound API. |
| identity / attempt ID | Paid entry | Unique server-owned paid attempt, bound to player, round and payment. Reconcile that same identity before admission. |
| Entry price, round duration / closesAt | Competition rules | Server clock and immutable saved fee. A game’s displayed timer cannot extend admission. |
| Pool, next seed, studio and platform split | Creating a contest series | Third-party default: 60% current, 30% next, 9% studio, 1% Playmos. Playmos game default: 60/30/10. Your saved contract configuration is authoritative. |
| Winner shares + score verifier + settlement operator | Prizes | Trusted backend validates gameplay, ranks accepted scores and locks payouts. A simulation or confirmed entry is not a winner payout. |
| Attempt lifecycle / expiry | Paid replays | No new entry during an active run or unused paid attempt. Paid replay after completion is allowed until closing. Unused entries expire at closing. A running attempt may finish under its server deadline and score in the then-current round. |
Contest integration · Pool and series setup
6. Server secrets and wallet roles#
| Value | Where it lives | What it authorizes |
|---|---|---|
| PLAYMOS_SECRET_KEY | Your backend, or the studio-bound managed vault | Server verification / catalogue administration within the configured SDK studio. Never ship an sk_ key in the game. |
| APP_ORIGIN / SESSION_MODULE | Manual backend example | Trusted application origin and your authenticated session adapter. These are example application environment names, not automatically loaded SDK settings. |
| Webhook signing secret | Receiver secret store | Authenticates raw callback bodies; it is not a wallet key. |
| Player checkout wallet | Player wallet / parent Hub checkout | Pays entry and IAP amounts after approval. Test payer selection does not relink the account. |
| Studio payout address | Studio payment setup | Receives studio revenue on its configured rail. Replacement review does not rewrite old pool sinks or saved orders. |
| Privy appId | Standalone wallet connection, when using Privy | Public connection configuration. Hub games inherit the host’s wallet flow. |
| Privy server credentials / signing authorization | Authorized backend signing provider only | Custodial or delegated server signing. Provision through the provider/vault; never put signing authority in frontend variables. Non-custodial publishers can retain their signer. |
7. Optional services#
| Service | Additional configuration | Owner / guide |
|---|---|---|
| JavaScript diagnostics | portalOrigin + development adapter for external URLs | Studio builds and uploaded test previews connect automatically. Error, rejected-promise and console.error / warn reports remain in the current tab; disconnected does not mean error-free. |
| Analytics | Consent, analytics.logger, context, optional meter/exporter | Your browser instrumentation and configured telemetry destination. Analytics setup |
| Anti-Cheat | anticheat.transport: begin / checkpoint / submit / get; authenticated run and ruleset | Your trusted game backend. Browser errors or telemetry never verify scores. Anti-Cheat setup |
| Live multiplayer | Session token, input reader, simulation and snapshot/state mapping | Backend provisioned room / session; short-lived player token in memory. Live setup |
| Controllers / Mo / trophies | Registered host bridge, current player/session and game event hooks | Use host-provided capabilities inside the Hub; configure standalone adapters explicitly. Controllers · Mo · Game services |
| Streaming / media | Configured provider, authorized stream/source and playback/session policy | Backend provisioning and provider secrets; only authorized playback data in the client. Streaming API reference |
8. Verify the complete configuration#
- Open the exact game build and confirm the app name and Game ID at the top.
- Check diagnostics are connected; exercise gameplay, cancellation and rejected promises.
- Make one test item purchase. Confirm the same receipt on the payment server and one inventory grant on the game backend.
- Buy one entry, confirm admission, finish the run, then test paid replay and expiry. Pending or cancelled payment must not admit a run.
- Restart / reconnect and recover the original order. Check a real callback separately from browser-only completion.
- Verify the deployed build, network and service configuration before recording or releasing. Store compatibility requires testing native billing and restore separately.
If it did not work#
If a service is unavailable, check its registered Game ID, environment and backend credentials before retrying the saved order.
Try one variation Disable one optional service and confirm free play still works without a wallet.
Continue with the next guide →