Connectez votre IA et préparez votre premier jeu
Inscrivez votre studio, préparez la fiche du jeu et livrez une version avec IDC Games Publisher.
Connectez le MCP
Les deux options lancent le même serveur local et nécessitent Node.js 20.19 ou une version ultérieure.
Ajoutez un serveur STDIO local à votre application d’IA avec la configuration ci-dessous. Pour un studio existant, renseignez PANEL_API_KEY. Pour une nouvelle inscription, utilisez une connexion sans clé enregistrée.
Run without installing with npm
Download and extract the official package into its own directory. Dependencies are included; the destination machine only needs Node.js 20.19 or newer. Point your MCP client at the extracted file.
tar -xzf idcgames-publisher.tgz
STDIO
command: node
args: ["/absolute/path/package/dist/index.js"]
Installer le paquet (.tgz)
npm install --ignore-scripts --omit=dev "https://admin.idcgames.com/publisher/download"
Installer le paquet: idcgames-publisher.tgz
npm install --ignore-scripts --omit=dev ./idcgames-publisher.tgz
STDIO
command: node
args: ["/absolute/path/node_modules/@idcgames/mcp-publisher/dist/index.js"]
Depuis le dépôt
cd mcp-server
npm ci
npm run build --workspace=@idcgames/mcp-publisher
STDIO
command: node
args: ["/absolute/path/mcp-server/publisher/dist/index.js"]
PANEL_URL: https://admin.idcgames.com
Créer le paquet pour les clients (.tgz / tar.gz)
cd mcp-server
npm ci
npm run pack:publisher
Inscrivez votre studio
Confirmer le code OTP enregistre seulement le studio, sans le valider. Votre IA doit demander legal_name et le pays légal du studio si ces données manquent. Enregistrer le profil complet le soumet à examen. Attendez uniquement en pending_review ; après 20 minutes sans décision, signalez le retard à IDC.
Confirmez votre nouveau compte éditeur et associez-le à votre agent IA. Communiquez ce code uniquement à l’agent IA auquel vous avez demandé de créer votre compte éditeur. Valable 10 minutes · Usage unique
Content-Type: application/json
request_company_signup → POST https://admin.idcgames.com/api/publisher-signup
{"company_name":"Publisher Name","owner_name":"Owner Name","owner_email":"owner@example.com","country":"ES","currency":"EUR","confirmation_method":"email_otp","locale":"fr"}
→ 201: device_code (private), email_status: queued, code_expires_in: 600
Owner receives email OTP → gives code to AI → explicitly accepts publisher terms
confirm_company_signup → POST https://admin.idcgames.com/api/publisher-signup/confirm
{"device_code":"<private device_code>","code":"<OTP from owner>","accept_terms":true}
→ 200: api_key (MCP stores it privately), company_id, publisher_status: pending
resend_company_signup_code → POST https://admin.idcgames.com/api/publisher-signup/code
{"device_code":"<private device_code>","locale":"fr"}
→ explicit owner request only; one-minute cooldown; previous OTP invalidated
check_company_signup → POST https://admin.idcgames.com/api/publisher-signup/token
{"device_code":"<device_code>"}
→ recover interrupted confirmation; never show or paste API/device keys
get_company_profile → GET https://admin.idcgames.com/api/agent/company
→ onboarding.missing_fields: ["legal_name", "country"]
→ onboarding.required_inputs: field descriptions to ask the owner
→ onboarding.should_wait: false → ask the owner; DO NOT wait
update_company_profile({legal_name: owner_answer, country: publisher_ISO_country})
→ publisher_status: pending_review, onboarding.should_wait: true
→ profile saved AND submitted, not approved
get_company_profile → poll every 60 seconds, stop/escalate after 20 minutes
→ publisher_status: approved, onboarding.ready_for_uploads: true
Legacy complete profile still pending → submit_company_review (safe to repeat)
Préparez la fiche du jeu
Demandez un brouillon avec le titre, les descriptions courte et longue par langue, la couverture, le logo et les images. Indiquez si le jeu de base est gratuit et les niveaux supplémentaires sont des DLC. Vérifiez la fiche enregistrée. L’envoi de fichiers exige l’approbation du studio. L’anglais est obligatoire pour les descriptions courte, longue et SEO et sert de langue par défaut.
Cinq originaux sont obligatoires : un logo aux proportions libres et quatre compositions : 16:9 (minimum 1280 × 720), 2:1 (1080 × 540), 3:4 (540 × 720), 4:5 (576 × 720). Les images plus grandes au même format sont acceptées. Le traitement redimensionne sans recadrer vers un autre format. Les fonds de section sont facultatifs.
Short: 120–500 · Long: 1,000–10,000
ZH / JA / KO: 60–500 · 400–10,000list_store_param_defs → text_policy → set_store_content → validate_publication
DLC: 16:9 · 1920 × 1080 px · PNG / JPEG / WebPupload_asset_file → save_dlc_draft / update_dlc_presentation → submit_game_for_review
create_game · set_store_content · import_asset_from_url
Utilisez le MCP pour préparer des actualités, des illustrations, des guides et des événements, et gérer les offres et les campagnes de coupons.
list_news_kinds · create_news · create_media · create_guide · save_shop_offer · save_shop_coupon
IDC Games · E2E
Store: Cette décision concerne uniquement la page Store. L’App et l’exécutable sont vérifiés séparément.
App: Activez l’App dans Admin ou via MCP, puis choisissez une phase de prélancement (Closed Beta) ou lancement (Production). La validation et la publication Store restent distinctes.
-
Créez le studio avec l’OTP du propriétaire et attendez son approbation.
request_company_signup → confirm_company_signup → update_company_profile → submit_company_review -
Complétez page, images, vidéo et DLC.
create_game → list_store_param_defs → upload_asset_file → set_store_content → save_dlc_draft -
Enregistrez Development dans Auth avec sync_development_game et attendez sent.
sync_development_game → get_game_review.development_registration.state = sent -
Créez un compte joueur IDC ; une personne autorisée attribue user_developer par id_user dans Game Configuration → Developer access, sans outil publisher MCP.
Game Configuration → Developer access · user_developer · id_user -
Téléchargez le Launcher officiel, connectez-vous et laissez-le ouvert. Lancez l’EXE local ; testez DLL, Pipe chiffré, identité Auth, can_play et DLC achetés ; une liste vide ne débloque rien.
IDC Games Launcher → DLL → encrypted Pipe → Auth → can_play / dlcs -
Ensuite seulement, envoyez, analysez, appliquez et synchronisez la version finale.
create_release → get_release_delivery_options → import_release_from_url → get_import_status → apply_import → publish_release → activate_release -
Choisissez la phase, demandez l’évaluation et vérifiez approbation, livraisons WWW/Auth et page. Coming Soon ne nécessite pas de version.
get_game_catalogs → set_game_launch_plan → validate_publication → submit_game_for_review → get_game_review → public_url
Livrez une version
Préparez un ZIP et le chemin relatif de l’exécutable. Demandez la vérification du SHA-256 et attendez les contrôles de sécurité. Vérifiez la livraison avant de l’appliquer, de la publier ou de l’activer.
Phases, sessions et clés
Ouvert ne signifie pas gratuit. L’alpha fermée nécessite une clé ou un accès développeur. Une clé peut couvrir une session, toutes les sessions d’une phase ou le jeu dans toutes ses phases. Les changements nécessitent une révision et une livraison à Auth.
get_game_catalogs → list_game_rounds → create_game_round → update_game → select_game_round → submit_game_for_review → get_game_review
MCP / API · English
Game phases, access rounds and keys
The panel owns phase/round identities; Auth owns player access and keys. Store approval, App readiness, phase, round and price are independent. Open does not mean free. Paid base games and optional DLCs keep their own license requirements.
Call get_game_catalogs: statuses lists selectable real phases, phases explains each
phase's label, access rules, flags and round support, and activation_key_scopes
explains key behavior. Always discover IDs; never infer them from labels or tiers.
| Phase code | Intended access |
|---|---|
developing |
Prepare and test the IDC SDK with an authorized developer account. |
coming_soon |
Public Store and estimated date; no general play or sales. |
closed_alpha |
Valid base-game key or developer only. No subscription trials/general sales. The migration allocates its ID without renumbering existing phases. |
closed_beta, limited_beta |
Restricted testing: keys, developers and eligible Silver/Gold trials. |
early_access |
Historical non-playable announcement. |
play_early_access |
Playable Early Access: paid-game purchase or valid license/key, without Gold or new subscription trials bypassing purchase. Existing trial windows retain their expiry. Explicitly free games remain free. |
open_beta |
Open testing, still subject to the game's free/paid requirements. |
production |
Commercial launch, free or paid as configured. |
inactive |
No new sales; existing owners retain only the access Auth permits, not reinstall rights. |
not_in_idc |
Informational availability without IDC gameplay. |
Catalog flags are not a player's entitlement. Auth alone determines can_play.
Demos are separate games
Demo is not a phase. Call create_game(demo=true, id_commercial_game=...)
with the full game's IDC ID owned by the same publisher. The demo has its own game
ID, App/releases, keys and Store under /demo/<full-game-slug>/ (with the normal
language prefix). Only one demo per full game is supported. Discover and select
its real phase separately, such as Development, Closed Alpha, Closed Beta or
Commercial release. A full-game key or DLC does not implicitly license its demo,
or vice versa. The historical demo status row and existing legacy keys remain
readable; do not use that status for new games, phase/round keys or rounds.
Operational access errors
Change the operational state in Admin's Game Configuration or with
set_release_configuration({game_id, operational_state}). Use operational
for normal operation, maintenance_playable for an advisory that preserves
phase access, or maintenance_blocked to block starts, including for developers.
During maintenance, optionally send maintenance_ends_at as a UTC timestamp
such as 2026-11-18T14:30:00Z. Omit it to keep the current estimate (or start
maintenance without one if none exists). Send null to clear it. Returning to
operational also clears it. Auth supplies the estimate to the Launcher so it
can display the user's local time. Maintenance continues until explicitly changed.
Auth exposes the state in click-login and denies blocked logins with
game_maintenance. WWW shows an advisory on Game Home.
The change queues synchronization for the existing Auth and WWW publications. It keeps the published phase, catalog position and ownership. Check delivery before assuming Auth has applied the change. For a game using a legacy maintenance phase, first select and publish its real phase.
Prepare and publish rounds
Rounds are optional; migrations never enable them on existing games.
Each round belongs to one game/phase, has an immutable ID and an automatically
assigned number, and moves from planned to open to permanently closed.
list_game_rounds(game_id)shows history, selected draft and published round.create_game_round(game_id, phase_id, name)prepares a round. The same phase/name returns the same identity, even if closed; a new round needs a new name. The limit is 250 retained round identities per game.- Select the phase with
update_game(status=phase_id), then callselect_game_round(rounds_enabled=true, round_id=returned_id). - Check Store/App prerequisites, call
submit_game_for_review, and pollget_game_reviewuntil approval and required WWW/Auth deliveries are sent. Selection alone does not change published access. - Approval opens the selected round and permanently closes the previous one. Never reuse or reopen a closed ID.
Publishing rounds_enabled=true, round_id=null creates an interval without
player access (playable=false). Disabling rounds and publishing also closes
the old round; old round keys never become permanent. Panel users have the same
controls in Game Configuration → Phases and rounds. Staff MCP keeps its own
authorization/publication workflow; round management does not bypass approval.
Key scopes
Choose explicitly when calling create_activation_key_batch:
access_scope |
status_id |
round_id |
New key's scope |
|---|---|---|---|
round |
Exact positive phase ID | Required owned round | Only that round; never revives after closure. |
phase |
Exact positive phase ID | Omitted | All present/future rounds of that phase, including later re-entry. |
game |
0 |
Omitted | This product in every phase and round. |
| Omitted | Historical type | Omitted | Legacy phase-exit cutoffs; existing grants are never expanded. |
Omit dlc_id or use 0 for the base game. A positive ID must belong to the
game. A DLC key licenses only that DLC and never grants the base game.
Expiry, revocation, bans, playable=false and intervals without an open round
still apply to every scope.
Keys can be prepared for a planned round. Auth registers an inactive reference
from authenticated issuance; only an approved signed snapshot can open it.
Issuance, claim and explicit redemption are separate. Never redeem, purchase
or grant rights automatically to test issuance. Store codes privately, never in
chat/logs/Git. Use stable idempotency keys and reconcile uncertain results with
list_activation_key_batches / get_activation_operation before reissuing.
get_activation_keys retrieves codes; revoke_activation_key revokes one.
Receiver contract
Optional game.data.access_policy is standard|keys_only|purchase.
rounds_enabled is boolean. access_round is null or
{id:string, phase_id:int, number:int, name:string}. Only the approved round is
sent. Explicit null closes the current round; absence preserves legacy state.
No rounds array is sent. IDs cannot change game/phase or revive after closure.
See docs/web-sync/content-v2.schema.json for the normative shape. WWW displays
metadata; Auth enforces rights and invalidates affected sessions/caches.
EXE · Login · Shop · Payments · Ads
get_integration_guide · idcgames://publisher/integration
MCP / API · English
IDC Games integration: native login, Shop, purchases and ads
Read this guide before writing an integration. Available directly through the
publisher MCP tool get_integration_guide and resource
idcgames://publisher/integration, as well as dist/INTEGRATION.md in its package.
The MCP configures the publisher's game; it is not a player login/payment API.
Two companion contracts ship with it, through the same channels:
| Contract | MCP resource | Package file |
|---|---|---|
| Purchase callback and reading notifications back (sections 4–5) | idcgames://publisher/purchase-callback |
dist/PURCHASE_CALLBACK.md |
| Selling to Steam players (section 6.9) | idcgames://publisher/steam-shop |
dist/STEAM_SHOP.md |
get_integration_guide({topic:"payments"}) appends the purchase callback
contract; topic:"shop" appends both.
0. Start here: choose the work and follow its order
Call get_integration_guide({topic:"publishing"}) for the complete publisher → game
page → development → tested build → release → review → delivery workflow.
studio focuses on OTP, profile, approval and keys; native_login, shop,
payments, ads and checklist focus on implementation. all returns both
full guides. No API key is needed to read them.
| Your case | Next action |
|---|---|
| No publisher | Owner email/OTP/terms → legal profile → submit → wait only in pending_review |
| No game | Discover catalogs → create_game → get_game; distinguish Panel and IDC IDs |
| Working Launcher login | Keep it unchanged; optional backend validation is a separate step |
| F2P articles | Shop catalog → backend ID mapping → export/install payment key → callback → sandbox acceptance |
| Bundled DLC | Unlock DLC catalog → Auth ownership gates; no extra ZIP |
| Build ready | Import/scan/apply/CDN-sync/activate → commercial phase → Store review → check deliveries |
An active build can coexist with a Coming Soon page or a previously published
phase. To change the Store, use get_game_catalogs, set the chosen phase ID
with update_game.status, set availability with set_game_launch_plan,
then validate and submit the Store for review. Check delivery acknowledgements
before reporting that Closed Alpha, Closed Beta, Open Beta, Early Access or
Production is live.
Ask for missing real legal details and the desired business/release plan; never invent those or wait for an unsubmitted profile. The owner supplies the OTP and accepts terms; a human assigns developer access to the test player. Publisher MCP does not bypass these steps.
The official SDK has a runnable C# console at
examples/LauncherDemo.
Use its login/poll lifecycle, then shop and ad sandbox commands. --demo is
offline and --check-native checks DLL exports; neither proves real login.
Configure the operational IDC ID and public token, never the payment key.
Runnable backend examples ship in dist/examples/ and as MCP resources:
idcgames://publisher/examples/verify-native-session.mjsidcgames://publisher/examples/verify-purchase-callback.mjs
node dist/examples/verify-native-session.mjs --self-test
node dist/examples/verify-purchase-callback.mjs --self-test
Node20.19+, no dependencies. These validate the wire contracts with inert tests; the payment example does not implement your inventory database. Implement the durable per-transaction grant/refund policy described below.
1. Identify the system and the credentials
| Value | Source and use | May ship in the EXE? |
|---|---|---|
Panel game_id |
get_game; selects publisher tools and Admin records |
Yes; identification only |
IDC id_game / id_idcgame |
Game's operational identifier in Auth/Launcher; do not substitute the Panel ID | Yes |
game_public_token (compatible game_token) |
get_game; public game identifier for IDCLib (GameSecret in _InitIDCLib), the Launcher and Auth; historical game_secret_key |
Yes; identifies the game, never authorizes anything |
| Publisher MCP key | Publisher Configuration or Game Configuration → MCP keys; scoped X-Agent-Key for Admin |
No |
Native tokenUserGameId |
Live Launcher UserData; short-lived bearer credential for the player/game | Runtime only; never logs, URLs, repository or support messages |
game_server_secret (same name in the API and the MCP file) |
Game Configuration; MCP exports it only to a protected backend file. Signs everything between Admin and the game server: purchase callbacks (section 5) and requests from the game server, such as the Steam shop launch code | No |
Auth X-Internal-Key |
Internal IDC web-account verification; not a publisher credential | No; never delegate to a publisher |
| GamePanel internal game ID | Receiver configuration, if GamePanel is used | Separate from both IDC and Panel IDs |
Two keys per game. The public token identifies the game and may ship in the
EXE, so it never signs or authorizes anything: Admin refuses requests signed
with it. The server secret lives only on the game server and signs in both
directions with the same scheme (X-IDC-Signature, section 5). One server
secret per game covers every server-to-server use.
Existing games got their own private server secret on 12-11-2026, replacing
the old compatibility copy of the public value (legacy_shared), which no game
uses any more; the public token did not change. Admin refuses requests signed
with the public token or with such a copy. New games from the panel, Quick Setup or API
generate independent values at creation: public32hex characters (fits the SDK's
63-character limit) and private64hex characters.
In Game Configuration the fields appear together: game_public_token and
masked game_server_secret, with reveal/copy controls. A human with
game_manage can explicitly regenerate only the server secret, confirming
they will update the game server. The public token remains unchanged. General
game-read responses never reveal the private key.
Neither game key authenticates users. A publisher-scoped MCP key manages its games; a game-scoped one manages that game only. Neither can administer Auth or issue MCP keys.
2. Existing EXE login and optional backend verification
Keep a working StarFetcher/Launcher login unchanged. Server-to-server validation is the next optional integration when the game has a backend: forward the already received credential to that backend, which verifies it with Auth. It does not ask the player to log in again or replace the Pipe/DLL protocol.
Get the official integration SDK and its verified native DLL from
idcgames/idcgames_integration.
Read its docs/launcher-protocol.md, docs/quickstart-csharp.md and
docs/authentication-idc.md. Do not recreate native structs or encryption from
memory. Native Windows x64 ABI: _InitIDCLib, _PullMessage, _EndIDCLib;
StdCall, native bool one byte, JSON callback UTF-16LE, length in bytes. Copy
callback bytes before returning, retain delegates, poll on the game thread,
dispose on exit. A C# .NET8 wrapper is an example, not a requirement for C++ games.
-
Approve the publisher, create the game and DLC catalog, then
sync_development_game. Wait for its Auth delivery acknowledgement before testing login. A human assigns the tester's separate IDC player account via Game Configuration → Developer access (user_developer, numericid_user). -
Download the official IDC Launcher, sign in and leave it open. Initialize IDC's DLL with the operational game ID, public client token and actual process ID. Test the existing encrypted InitLib Pipe flow. Init returning success is not authenticated UserData. An old provisional JSON login path is not an interchangeable implementation.
-
On UserData, send its credential to your backend by HTTPS. Do not trust
userId, nick, email or DLC claims supplied by the client without validation. Do not try/api/web/verify-tokenfor an opaque native credential. -
Admin sends
client_session_protocol="opaque-v1"to Auth on game sync. Once Auth applies the document, the issued-session verifier uses this URL with a new game-scoped session implementation, not the old calculable MD5 check:POST https://auth.idcgames.com/api/launcher/get-access-data Content-Type: application/json {"token":"CREDENTIAL_FROM_LIVE_PIPE","gameId":1614}The backend fixes
1614from its own game configuration. No global S2S key is required by this route: the issued opaque credential is the bearer proof. An invented 32-hex string, public game token or web JWT is not such proof. Prefer POST; never put a player credential in a query string.idctkandidcgameidremain historical aliases. The supportedtokenandgameIdnames above avoid confusing this with the old implementation. Do not implement MD5. -
Require HTTP success and
result===0,can_play===true, expectedgame_id, positiveuser.userid, futureexpires_atin Unix seconds andcatalog_synced===truebefore unlocking catalog content. Bind the internal game session to the verified(game_id,user.userid). Reject a conflicting client user ID; never bind by email/nickname orusercrc. -
dlcscontains purchased/authorized operational DLC IDs. It is not the catalog'spanel_id, a SKU, a slug or an array of all available DLCs.[]unlocks nothing. Developer access to the base game does not grant DLCs. Refresh authorization for protected actions and revocations; an expiry is an upper bound, not a guarantee of access until then. Session TTL is at most 30 minutes and cannot exceed its parent/access right. Renew through the supported InitLib lifecycle; do not silently prolong offline access. -
Handle invalid/expired/revoked/wrong-game credentials (401), maintenance, bans or access denial (403), unavailable dependency (503), timeout and incomplete JSON by denying access and showing the supplied error code and localized message. Do not fall back to an unverified cached identity.
/api/launcher/check-user-game-token is also retained, taking userId, gameId
and tokenUserGameId, but an OK alone is not the full can_play/DLC projection.
/api/web/verify-token belongs to web/account tokens and internal IDC access;
it is not an alternative verifier when an opaque native session is rejected.
Compatibility boundary: Auth dispatches to the new implementation only for an enabled game. Existing GamePanel adapters/documentation may still describe launcher-check followed by web-token fallback and call the credential MD5. Inspect the installed adapter and confirm its mode; do not silently mix these flows. The current Auth implementation and isolated game1614 tests establish the opaque contract. An invalid-token production probe demonstrates rejection, not a successful real-player EXE test. SDK session renewal and the real EXE still need acceptance with the signed-in Launcher. No credentials are included here.
3. Build a Shop with the publisher MCP
Free-to-play is the base-game price model; it does not make Shop articles or
DLCs free. Unlock DLCs are separate catalog entitlements (save_dlc_draft), not
coins or consumable Shop articles. Do not upload another EXE for bundled levels.
| Identifier | Meaning and source |
|---|---|
game_item_id |
Stable string chosen by the game backend, e.g. credits; natural key of save_shop_item |
item id |
Admin row returned by that tool; use as article item_id |
game_article_id |
Stable game pack/SKU string, e.g. credits_100; natural key of save_shop_article |
article id |
Admin row for price, placement, offer and coupon relations |
article_token / idc_article_token |
IDC-generated article token returned as article_token in the catalog and named idc_article_token in the payment callback. Keep it separate from the game SKU and Admin row ID. |
| level/tab/category/country/currency IDs | Discover with get_commerce / get_commerce_catalogs; never guess |
transactionid |
Payment transaction ID; durable delivery/refund idempotency key scoped to the game |
Use these steps, reading back each saved object's IDs before constructing its dependants. Send every required field on edits; inspect each tool's schema.
get_commerce_catalogs→get_commerce→setup_shop(initially inactive). Ask the user if any countries or languages should be excluded. With no exclusions, send onlygame_idfor a new shop. Admin enables all countries and languages in the catalog. To exclude entries, send the exact IDs to keep enabled incountriesand/orlanguagesfor the affected settings. For an existing shop, omitted settings keep their saved selection. To enable all current entries again, callsetup_shop({game_id, active_all_countries: true, active_all_languages: true}). Each flag works independently. A false flag is equivalent to omission. After changing markets, configure prices for the enabled countries before activating sales again.- Create item categories and translated item definitions (
save_shop_category,save_shop_item). Setgame_item_idto the backend's actual grant mapping. save_shop_article: its owngame_article_id, returneditem_id, packnumber_of_items, payment mode, region, text and image. Creating an article does not itself define every regional checkout price or visible placement.- Create the level and tab with
save_shop_levelandsave_shop_tab, then create visible placements withsave_shop_placement. Set regional checkout prices as described below. - Optional offers/coupons (
save_shop_offer,save_shop_coupon,save_coupon_code); relations must belong to the same game. Define how bonus articles map to backend grants. Do not expect the reference receiver to automatically deliver nested bonus arrays. - Read back the complete shop, configure the private signed callback below, perform sandbox acceptance, then explicitly activate commerce with the corresponding activation tool and verify the live destination's result.
The historical bought_notify flag appears on an item; the current producer
does not use it to suppress the game callback. Do not rely on false to prevent
notification or rely on it as a security control.
Regional prices from a EUR or USD reference
Enabling countries with setup_shop does not generate prices. For the Admin
wizard workflow, set the article's reference amount in price and select the
item's reference country (whose configured currency must be EUR or USD). Once
the article is placed in a level, open the Shop wizard's Final Prices step.
The wizard generates missing prices using the configured exchange rates and
the currency assigned to each enabled country. It keeps existing prices.
Review the generated prices before enabling sales.
From MCP, call generate_shop_regional_prices for each article and level.
For example, pass {game_id, article_id, level_id, base_currency: "EUR", base_price: 4.99}.
IDC Games handles regional conversion and uses the reference currency by
default in countries without a configured local currency. The tool fills
missing prices and preserves saved amounts. If prices remain pending, ask
IDC Games to review before enabling sales. Use save_shop_price for an
override and get_commerce to review the result before set_shop_active.
Catalog, artwork and promotions
Before writing to the Shop, read the game's backend catalog. If it calls its
pack identifier id_producto, copy that exact value into game_article_id;
put the backend's deliverable ID in game_item_id. For example, an article
credits_100 grants the item credits in a quantity of 100. Preserve spelling,
case and leading zeroes. Read both IDs back and compare them with the backend
catalog before enabling sales. Never infer a grant from its price, translated
title or Admin row ID. If different packs share a deliverable, use the pack ID
to identify the exact offer and the item ID to identify what to grant.
Create distinct product art that shows what is delivered (a pile of coins, a
crate, or the actual item). Start with square 512×512 WebP or PNG card art,
keep the subject away from edges, and leave labels and prices to the Shop UI.
This is an art recommendation, not an upload constraint. Use upload_asset_file
with an absolute path under IDCGAMES_ASSET_ROOT or import_asset_from_url
for a supported source. Check get_import_status; when ready, call
apply_import and use its media_id in shop_article_image_media_id,
item_image_media_id, tab_image_media_id or item_category_image_media_id.
Preview the resulting cards in the actual Shop.
Design the Shop and arrange its tabs
Read get_commerce and get_commerce_catalogs before proposing a design. Use
the game's artwork, visual identity and actual catalog to choose the background,
theme, product art and tabs. Keep text and prices readable over the artwork.
| Area | What the Publisher MCP can configure |
|---|---|
| Background | setup_shop.presentation sets the game image, sizing and dark overlay. The panel generates the CSS for these controls. |
| Typography, colors and component styles | Select an active theme with setup_shop.default_theme_id or a level-specific save_shop_level.theme_id. Create or update the game-specific theme with save_shop_theme using the variables below. |
| Tabs | save_shop_tab can create several tabs in the same shop. Use a stable internal name, a player-facing title, translations, optional translated tooltip, optional tab_image_media_id and display_order. A new tab includes all currently configured payment modes by default. Set article_payment_filter to a comma-separated list of payment mode IDs to restrict it. Omitting it on an update preserves the saved filter. |
| Product cards | Use save_shop_article with distinct artwork and translated text. Set each card's order within a tab using save_shop_placement. |
For example, create currency (Credits, order 10) and bundles (Bundles,
order 20) if both groups have articles. Use save_shop_placement with the
returned tab_id, article_id and level_id, active: true and a
display_order for each card. The same article can appear in both tabs with
different display orders. Item categories group items and do not place cards
in tabs. Check the tab's optional payment-mode filter, the active level range,
regional prices, date windows and purchase limits when a card is missing.
Create or reuse a theme
For a new game theme, call setup_shop if the shop does not yet exist, then
call save_shop_theme. It creates or updates the game's own theme using the
IDC base stylesheet. By default it selects that theme for the shop without
changing sales activation, countries or languages. Set make_default: false
to save it without changing the selection. Each call replaces the full
override list. Omitted values come from the base stylesheet.
For example:
{
"game_id": 123,
"name": "Arctic Credits",
"variables": {
"font_title": "georgia",
"font_main": "system",
"primary": "#2AC8EE",
"primary_foreground": "#142235",
"card": "#172031",
"card_foreground": "#EDF4FA",
"radius": 10
}
}
| Area | Keys in save_shop_theme.variables |
|---|---|
| Typography | font_title, font_main: system, arial, georgia, monospace |
| Background and text | background, foreground, muted, muted_foreground |
| Cards | card, card_foreground, card_secondary_foreground |
| Buttons and selected payment method | primary, primary_foreground, accent, accent_foreground, highlight |
| Popovers and tooltips | popover, popover_foreground, tooltip, tooltip_text, tooltip_secondary_text, tooltip_border (0–8 px) |
| Borders, focus and errors | border, input, ring, radius (0–32 px), destructive, destructive_foreground |
Use #RRGGBB or #RRGGBBAA for colors. The API generates the CSS from
these values. Use the separate presentation settings for the background
image, sizing and dark overlay.
To reuse an existing theme, find its ID in get_commerce_catalogs and pass it
as setup_shop.default_theme_id. Omit the regional fields to keep the selection.
This setup step disables sales until reactivated. Read back shop.current_theme
with get_commerce and preview it in the Launcher at the intended player
level. A theme URL parameter can override the default. Send
presentation: null in setup_shop to use the theme's own background.
Use save_shop_offer for timed promotions and scope them by article, level
and country; configure discount, bonus units/articles and redemption limits.
Use save_shop_coupon then save_coupon_code for redeemable codes, with
currency, date window and article restrictions. Check get_shop_promotions
and test a promotion before and during its window. The backend must explicitly
support any bonus delivered by the campaign.
For the background, prepare a landscape 1920×1080 WebP/JPEG with a low-detail
center. Import and apply it for the same game, then include
presentation: {background_media_id: 123} in setup_shop. The validated image becomes the game's
default Shop background immediately, without another approval or assignment
step. Optional CSS controls are fit (cover by default) and
shade_percent (65 by default); the panel generates the CSS. For a different
base theme, also pass default_theme_id from get_commerce_catalogs.
Use save_shop_theme to customize the game theme from validated style values.
Omit presentation to keep it, or send null to restore the base theme's
background. Setup disables sales until explicitly reactivated. Read the saved
configuration back, then preview the effective theme, tab order, translations,
card art and prices in the Launcher at narrow and wide sizes. Preview the web
entry as well if the game has an authenticated web Shop route.
4. Server secret and payment callback configuration
signing_mode=private_payment_secret means Admin uses the separate private server secret;
it does not prove an actual checkout or item delivery has succeeded.
Set MCP IDCGAMES_SERVER_SECRETS_DIR (formerly IDCGAMES_PAYMENT_SECRETS_DIR, still accepted) to a protected absolute directory
outside the repository, public uploads and game distribution. Restrict Windows
ACLs to the service/owner, or Unix directory700/files600. Never paste the file
contents into a chat. Back it up as a backend credential.
get_game_payment_callbackreports signing mode/fingerprint only.prepare_game_payment_callbackexports Admin's existing key into that directory, bound to Panel URL and Panel game ID. It requires an approved publisher andcommerce:write. Its result contains only path, signing mode and SHA256 fingerprint. It never prints, regenerates or activates the key. Every game has its own private key. The file carries it asgame_server_secret.- Install that file in the receiver's server-side secret store through an authorized server deployment. No secret goes into client assets or an EXE.
- Once the receiver uses it, call
configure_game_payment_callbackwith the Panel game ID, HTTPScallback_urlandbackend_ready:true. MCP reads the private file itself; the secret is never a tool argument visible to the AI. Admin stores it encrypted in a dedicated table, outside public game props. - Compare fingerprints; repeat with the same key safely. A different existing key returns409: coordinate rotation with IDC and the receiver, not automatic overwriting. If a local file is lost, export the existing key again; do not rotate it just to recover it. If a human rotated the server key, deliberately archive/update the old local file and backend before reconfiguring the callback.
For a direct HTTP API integration the configuration route is
PUT /api/agent/games/{panel_game_id}/payment-callback, publisher profile,
commerce:write, approved publisher, JSON game_server_secret (64 lowercase hex for a
new private key; existing compatibility copies keep their original value),
callback_url, backend_ready:true. GET uses commerce:read and returns no key.
The protected export is POST /api/agent/games/{panel_game_id}/payment-callback/credential,
also commerce:write and approved publisher, with a private/no-store response.
It returns the secret as game_server_secret to the authorized integration client, which must save it
directly into protected backend storage and omit it from logs and AI tool text.
The MCP does that automatically; the AI sees only file path, mode and fingerprint.
This is a game webhook secret, not issuance/delegation of an Agent API key.
Legacy public-token signing (signing_mode=legacy_public_game_token,
migration_required=true, production_ready=false) is off by default and no
game uses it since 12-11-2026: a game without a private key fails closed.
GAME_PAYMENT_ALLOW_LEGACY_GAME_TOKEN would re-enable it; do not turn it on.
A configured private key always wins; there is never a fallback after private
configuration.
5. Signed Admin → game payment delivery
The complete wire contract (every body field, refunds, shop level, retries and
reading notifications back) is PURCHASE_CALLBACK.md, resource
idcgames://publisher/purchase-callback.
IDCPayment confirms to Admin. For ARTICLE purchases, Admin independently sends
one notification to the game's configured callback to deliver items, and one
to IDC/Auth for accounting. Auth receiving its copy does not deliver the
game's coins or turn an article into a base/DLC library entitlement.
POST https://backend.example/your-payment-callback
Content-Type: application/json
X-IDC-Notification-Id: IDCNOTGAME_example
X-IDC-Timestamp: 1794312000
X-IDC-Signature: sha256=HEX_HMAC
{"action":"idcpayment","useridc":"42","transactionid":"example-payment","sandbox":"1","refund":"0","currency":"EUR","gross":2.99,"shop_level":{"id":7,"level_from":1,"level_to":99},"bought_data":[{"game_item_id":"credits","game_article_id":"credits_100","idc_article_token":"example-article-token","number_of_items":100,"article_count":1,"extra_articles":[],"offer_extra_articles":[]}]}
HMAC-SHA256(game_server_secret, timestamp + "." + exact_raw_body) → lowercase
hex, prefixed sha256=. Compare constant-time before parsing/delivering.
Validate timestamp within300 seconds; reject altered JSON bytes, missing headers,
wrong game/key and replayed processing. TLS verification is enabled; timeouts
are10s connect/30s total. Returns any2xx are acknowledged by Admin, so respond
2xx only after durably storing the accepted event/delivery. A retry carries the
same notification ID/body, fresh timestamp/signature. Automatic retries are
hourly, up to5; an operator can resend pending notifications.
To recover a lost notification or reconcile after an outage, the game server
calls the signed POST /api/purchase/notifications (same headers and server
secret, by transactionid or since with a cursor; see section 8 of
PURCHASE_CALLBACK.md) and delivers what it returns with the same
idempotent rules. Reading does not mark a notification as delivered.
In one database transaction: verify buyer's stable IDC identity and game
mapping, require recognized SKUs and validate deliverable quantities,
record unique (game,transactionid) purchase state and ledger grants, commit.
Duplicate callbacks must return success without a second grant. An outbox may
handle downstream rewards only if the acceptance is durable and retryable.
IDC verifies the money. The game must not recalculate or compare amounts, VAT,
currency or fees to decide whether to deliver a signed purchase.
number_of_items and article_count are separate wire fields. Admin currently
forwards them rather than multiplying. GamePanel's reference receiver consumes
number_of_items directly (fallback article_count); do not multiply twice.
Before accepting multi-pack orders, test quantity1 and quantity>1 end to end
and define the agreed total-grant semantics. Test bonuses separately.
For refunds, keep a separate idempotent reversal state for the same transaction, including refund-before-purchase and partially consumed currency policy. Sandbox must not create production grants/revenue. Invalid signatures return401; transient failures must not masquerade as successful delivery.
GamePanel receiver reference and its limits
GamePanel exposes POST /api/v1/webhooks/idcpayment/games/{game}; {game} is
its internal ID, not the IDC game ID. Its service resolves products by
game_item_id, then idc_article_token, then game_article_id, scoped to the
game, and requires an existing IDC-linked user. Missing user/product is not a
reason to guess a different account or grant an arbitrary item.
The reference currently documents HMAC and transaction idempotency, but does not automatically reverse previously delivered inventory/currency on refund, and does not automatically expand Admin's nested bonus arrays. Add those game policies and tests before claiming a complete paid consumables integration. Its old IDC credential field has also been used for web-auth verification: do not reuse a global Auth key as the new per-game payment secret. Configure a dedicated receiver payment key and coordinate its adapter/version explicitly.
6. Open the shop
The shop is a page of Admin: https://admin.idcgames.com/shop/frontend/index.
It never takes the buyer from its URL. Whoever opens it first asks Admin for a
launch code for the player, then opens the page with ?launch=<code>; the
shop exchanges the code for its own session. The code is valid for 60 seconds
and only once, so request a new one every time the shop opens and never store,
log or reuse it.
A game that uses IDCLib always starts from the IDC Launcher and opens the shop through it (6.5); the other channels are for web games and Steam players.
What you get back from the shop's page (postMessage, a return URL, a Launcher
notice) only tells your interface to refresh. Only the signed purchase
callback (section 5) proves a payment and may cause a delivery.
6.1 Choose how to open it
| You open the shop from | channel |
You register | The page reports the result by |
|---|---|---|---|
The IDC Launcher (IDCLib _OpenShop) |
(the Launcher does it) | Nothing | PurchaseNotification through IDCLib (6.5) |
| Your own WebView (WebView2, CEF, Electron, Unity plugins), Steam players | webview (default) |
Return URLs, optional | Navigating to your return URL (6.6) |
| The system browser or the Steam overlay | url |
Return URLs, optional | Navigating to your return URL (6.7) |
| An iframe in your web or WebGL page | iframe |
Web origins | postMessage to your page (6.8) |
A window your page opens (window.open) |
window |
Web origins | postMessage to window.opener (6.8) |
| Steam, for Steam players | url (overlay) or any of the above |
As for that channel | As for that channel (6.9) |
Whatever the channel, the game refreshes its inventory from its own server when the shop closes.
6.2 Register your web origins and return URLs
Game Configuration → Shop integration (permission game_manage), or the
publisher MCP tools get_shop_integration and configure_shop_integration
(scope commerce:write). One record per game; another game's record never
applies.
If Shop launch returns sandbox_disabled, read get_shop_integration and
enable testing with configure_shop_integration({game_id, sandbox_enabled: true}).
Send false to disable it again. A sandbox-only update preserves both URL
lists. Open the Shop with sandbox=1 for the test.
| Field | Rules |
|---|---|
| Web origins | https://host[:port], no path. http://localhost and http://127.0.0.1 (any port) for local tests. They become the shop's Content-Security-Policy: frame-ancestors and the only targets of its postMessage. One list for iframe and window |
| Return URLs | https://host/path or your game's own scheme (mygame://shop-result), without query or fragment: the shop adds the result. http only for localhost. javascript, data, file, blob and other system schemes are refused |
Up to 10 entries per list; one invalid entry rejects the whole save. Values are
compared exactly after normalizing (lowercase scheme and host, no trailing
/). The same configuration page has the Shop sandbox (testing) switch
(6.10) and the server secret (section 1).
6.3 Get a launch code
Player with an IDC account, with the player's IDC auth token (the JWT the player got when logging in with IDC). The game's keys are not used here: the token proves who buys.
POST https://admin.idcgames.com/api/shop/session/launch
Authorization: Bearer <player's IDC JWT>
Content-Type: application/json
{"game":"1615","userlevel":"12","sandbox":true,"channel":"iframe","parent_origin":"https://play.example.com"}
| Field | Required | Value |
|---|---|---|
game |
Yes | IDC game id (id_idcgame). The session only works in that game's shop |
userlevel |
No | Player level in your game; picks the shop level (6.11). Without it, the lowest active level |
sandbox |
No | true for test purchases, only while the game's sandbox switch is on |
channel |
No | webview (default), url, iframe or window |
return_url |
No | Only with webview or url; must be a registered return URL |
parent_origin |
With iframe/window |
The origin of the page that shows the shop; must be a registered web origin. If a browser asks for the code (it sends Origin), it must be that same origin |
Steam player: the game server asks for the code, signed with the server secret, for the player's SteamID64 (6.9). There is no server-signed code for IDC accounts and none is needed: desktop games with IDC accounts use IDCLib, start from the Launcher and open the shop through it (6.5).
Response 200: {"success":true,"launch":"<code>","expires_in":60}. Open:
https://admin.idcgames.com/shop/frontend/index?game=1615&lang=en&userlevel=12&article=<checkout article>&launch=<code>
game and lang pick the theme and language before the session exists;
article (optional) opens a configured article directly. Never add the buyer,
a token, sandbox or a price to the URL: the shop ignores them and the session
decides. Prices follow the buyer's country by IP (Steam: the wallet's country).
Never use game_public_token here, and never put the server secret or the
player's JWT in a URL, a log or the EXE.
6.4 Errors
| Status | code / message |
Meaning |
|---|---|---|
| 401 | Not logged in |
No token, the token is not a valid IDC JWT, or Auth does not confirm it |
| 401 | Invalid game signature |
Server-signed request (Steam): wrong, expired or replayed signature, or no private server secret |
| 403 | sandbox_disabled |
sandbox asked while the game's sandbox switch is off |
| 422 | Game not found |
Unknown game |
| 422 | invalid_channel |
channel is not one of the four |
| 422 | return_url_not_allowed |
return_url not registered, or sent with iframe/window |
| 422 | parent_origin_not_allowed |
Missing or unregistered parent_origin, sent with webview/url, or different from the browser's Origin |
| 422 | Unsupported store or user id |
Steam: store is not steam or the id is not a SteamID64 |
| 429 | Too many requests | |
| 503 | Shop sessions unavailable: contact IDC |
In the shop page: an expired or used code shows "open the shop again from the
game" (request a new code; do not reload the same URL). An IDC session inside
the Steam overlay is refused (steam_overlay_requires_steam_session): Valve only
allows the Steam Wallet there.
6.5 From the IDC Launcher (IDCLib _OpenShop)
The game asks the Launcher to open the shop; the Launcher gets the code with the player's session and shows an error page with "Retry" if it cannot. The game needs no code of its own and registers nothing.
idc.OpenShop(Guid.NewGuid().ToString(), article: "", sandbox: true);
// Empty article opens the shop. Use the actual IDC checkout article identifier
// from the catalog to target a pack; never guess it from the Panel row ID.
Native _OpenShop(transactionId,extra,userLevel,sandbox,article) is not a
payment verification API. extra/userLevel are client hints, never
authorization. Use a unique order/correlation ID and keep the backend mapping
to buyer and product. The included DLL can return 0 even when its notifier is
not running: that return value alone does not prove a window opened or a
shop/catalog loaded. Require the actual UI and callback evidence for that claim.
PurchaseNotification (dllTransaction, idcpaymentTransaction) tells the
game that a purchase has been charged: Auth lists a checkout only once
IDCPayment has confirmed and not refunded its payment. Cancelled or failed
checkouts never appear. The Launcher asks right after the purchase and again at
every game start, and repeats the notice until the game closes it. It carries
no articles or quantities, so it is a signal to refresh, never a delivery:
- On
PurchaseNotification, ask your backend for the player's inventory/balance. The signed callback usually arrives first; if your backend has not received it yet, retry with bounded backoff (e.g. 2, 5 and 10 seconds). - Replace the displayed balance with the absolute balance your backend returns.
Deduplicate notices by transaction and never infer the pack from
extraor the transaction id. - Call
AcknowledgePurchase/_ClosePurchaseonce your backend has delivered it. Closing only stops the notice: it never delivers, refunds or cancels a payment.
A charge confirmed after the Launcher's last check (a few seconds after the purchase) is notified at the next game start; the signed callback has already delivered it.
The Launcher closes the shop window after PurchaseEnd (8 seconds at most).
The Launcher's own shop events (emitShop) are internal; games do not receive
them.
Language when opening the Shop
In Launcher 7.1.34, the Shop opens in the account language
(session.user.language). The Launcher sends that value as lang to
GET /shop/frontend/index along with the normal opening code. The game
cannot override the language of an individual opening in this version:
_OpenShop(transactionId,extra,userLevel,sandbox,article) has no language
argument, and the Launcher does not read a language override from the
PurchaseInit Pipe message (0xFFEECCE6).
Configure and test the languages enabled on the game's Shop. The Panel
matches lang against its language catalog without regard to letter case,
then checks that the selected Shop includes that language. The catalog and
the Shop's enabled languages are separate. The endpoint defaults to en
when lang is omitted. An unknown code or a language absent from the
Shop can yield an error. To test a different language in the published
Launcher, use an account configured for that language and open the Shop
in sandbox. Keep the standard Launcher opening flow for authentication.
Use _OpenShopWithLanguage(transactionId, extra, userLevel, sandbox, article, language)
with the updated signed IDCLib2 DLL and Launcher 7.1.35. The last argument is
a language enabled on the Shop, such as es. The DLL sends the language in
the opening message internally. Resolve the export by name. It takes UTF-16
strings and a one-byte native bool (C# UnmanagedType.I1). _OpenShop remains
available at ordinal 3 for opening in the account language.
The Launcher normalizes regional variants such as pt-BR to pt. An
omitted, empty or malformed language falls back to the account language,
then the Launcher or system language, then English. To verify the selected
language, sign in to Launcher 7.1.35 and use a game with Shop sandbox enabled.
In the C# LauncherDemo, run shop-lang en with an account set to another
language and English enabled on the Shop. Confirm the catalog itself appears
in English. This procedure was verified with the signed DLL and Launcher
7.1.35. It requires only opening the catalog.
Concrete C# F2P example, game1599
The current CSharp_Test_1599/Program.cs example supplied with the Launcher
initializes login first, then DoShop(null, sandbox:true) calls:
IDCLib._OpenShop(uniqueTransactionId, "", 0, true, "");
This opens the F2P game's article shop, not purchase of its free base game.
An empty article opens the full shop; a configured article targets that pack.
Do not copy that example's actual identifiers/credentials into a different game.
Its interactive [6] is sandbox shop; [3] and [4] use live mode. [8s]
requests sandbox video, [8] live video. In the test application login is [1].
The example's [p] separately forwards UserData to GamePanel's
POST /api/v1/auth/third-party/login with platform:"idc", credential token,
user_id, internal GamePanel game_id, operational idc_game_id and that
installation's gamepanel_secret_token. These are not the Admin MCP key or
payment signing key. A successful GamePanel login issues its own bearer
access_token; /auth/validate validates that new game session. GamePanel is
optional; another backend can call Auth directly as above.
Do not copy the diagnostic example's raw UserData/DLL logging or automatic
_ClosePurchase from PurchaseNotification into a production game. Replace
automatic acknowledgement with the sequence above.
6.6 From your own WebView
For a desktop game that sells to Steam players and shows the shop in its own WebView; its server requests the code (6.9). Games with IDC accounts use IDCLib and open the shop through the Launcher (6.5).
- Register a return URL, e.g.
mygame://shop-result(6.2). - Request the code with
channel: "webview"and thatreturn_url. - Open the shop URL in a top-level WebView window (not inside another page).
- When the purchase ends the shop navigates to
<return_url>?result=completed|cancelled|failed&transaction_id=WOT_…. Intercept it, cancel the navigation and refresh from your server: WebView2NavigationStarting, CEFOnBeforeBrowse, or the URL-change event of your Unity WebView plugin. - Also refresh when the player closes the window.
result and transaction_id are only a hint: your server confirms the state.
Payment pages that cannot run inside the shop open in a separate window and
close themselves at the end; allow pop-ups from https://admin.idcgames.com.
There is no JavaScript bridge to your WebView.
6.7 From the system browser or the Steam overlay
Request the code with channel: "url" and, optionally, a registered
return_url (a custom scheme brings the player back to the game; an
https:// page of yours can show the result). Open the shop URL. Without
return_url the shop shows the result and the player returns to the game by
hand: refresh when the game regains focus.
6.8 In an iframe or a window of your web
- Register your page's origin, e.g.
https://play.example.com(6.2). Admin only lets registered origins embed the shop (frame-ancestors). - Get the code with
channel: "iframe"(or"window") andparent_origin: "https://play.example.com". Request it from your server with the player's IDC JWT, or from the page itself (the browser'sOriginmust then matchparent_origin). - Show it:
<iframe id="idc-shop" src="https://admin.idcgames.com/shop/frontend/index?game=1615&lang=en&launch=CODE"
allow="payment" style="width:100%;height:720px;border:0"></iframe>
or const shop = window.open(url, 'idc-shop'); (keep the reference and do not
use noopener: the shop answers to window.opener).
- Listen to the shop's messages and check both the origin and the source: another window of the same origin could send fake messages that pass the origin check.
const frame = document.getElementById('idc-shop');
window.addEventListener('message', (event) => {
if (event.origin !== 'https://admin.idcgames.com') return;
if (event.source !== frame.contentWindow) return; // window channel: !== shop
const msg = event.data;
if (!msg || msg.v !== 1 || typeof msg.type !== 'string') return;
switch (msg.type) {
case 'idc:purchase_completed': // payment confirmed
case 'idc:items_delivered': // your server answered 2xx to the signed callback
refreshInventoryFromYourServer();
break;
case 'idc:purchase_cancelled':
case 'idc:purchase_failed':
break;
}
});
Messages carry only type, v and transactionId: no personal data or
amounts. They go only to the session's parent_origin; without one, nothing is
sent. Never deliver from a message.
6.9 Steam players
The game server requests the code for the player's SteamID64, signed with the server secret, and the shop charges the Steam Wallet:
POST https://admin.idcgames.com/api/shop/session/launch
Content-Type: application/json
X-IDC-Game: 1615
X-IDC-Timestamp: 1794312000
X-IDC-Signature: sha256=<HMAC-SHA256(game_server_secret, timestamp + "." + exact_raw_body)>
{"store":"steam","store_user_id":"76561198000000001","userlevel":"12","channel":"url","return_url":"mygame://shop-result"}
The SteamID64 you send is the account that buys and receives the items.
Your server takes it from the player's validated Steam session (a Steam session
ticket checked with AuthenticateUserTicket, or your backend's existing Steam
authentication), never from a value the client sends.
Each signature is accepted once, within 300 seconds: sign every request again,
also retries. sandbox, channel, return_url and parent_origin work as in
6.3. Open the shop URL in the Steam overlay, passing the wallet's currency
when you know it: Steam rejects other currencies. The callback's useridc is
that SteamID64 and its store is steam.
Before the first sale a person with store_credentials_manage enters the game's
Steam AppID and Publisher Web API Key in the panel (Shop → External stores);
never pass that key through a chat or an MCP tool input. Steam setup, ticket
validation, the overlay code, limitations and common problems are in
STEAM_SHOP.md, resource idcgames://publisher/steam-shop.
6.10 Sandbox
With Shop sandbox (testing) on, a code requested with sandbox: true opens
a shop whose purchases charge nothing and are notified with sandbox: 1. Never
deliver them in production (section 5). With the switch off, sandbox is
refused (403 sandbox_disabled).
The game's phase sets a default; IDC approval does not change it:
- A new game in Development, Coming Soon, Closed Alpha or Closed Beta starts with it on; in Open Beta, playable Early Access or Commercial Release, off.
- Reaching Open Beta, playable Early Access or Commercial Release from any other phase turns it off.
- Going back from one of those to Development, Coming Soon, Closed Alpha or Closed Beta turns it on.
- Any other change keeps your setting: within the test phases, within the public ones, and to or from other phases such as Maintenance or Inactive.
Turn it off yourself when you are not testing.
6.11 Delivery and shop levels
The signed callback decides delivery, whatever the page reported (section 5).
A shop may have several levels with different articles, offers or prices,
picked by userlevel. IDC cannot verify that value: unless your server signs
the code (Steam), a modified client can claim another level. The callback
carries shop_level (id, level_from, level_to): if your levels differ,
check on your server that the buyer's real level is inside that range before
delivering. If you cannot check it, use a single level.
6.12 Games without a server
Not supported yet. Every game that sells in the shop needs a server that
receives the signed callback (section 5): the Launcher's PurchaseNotification
carries no articles or quantities (6.5). Ask IDC if your game is single-player
or offline and has no server.
7. Launcher video advertisements
The current SDK wrapper provides:
await idc.OpenVideoAdAsync(sandbox: true);
There is no _OpenVideoAd export in the included native DLL. The wrapper uses
the local IDCGamesPipe JSON videoAd request and receives VideoAdResult.
Layouts: fullscreen_monitor, fullscreen_game, windowed. Connect timeout3s;
one active request only. Statuses: STARTED (not completion), OK, SKIPPED,
NO_FILL, ERROR; the current Launcher can report BUSY (older guides call it
ALREADY_ACTIVE). Handle both and late/duplicate events. Current results
contain gameId, sessionId, errorCode, but do not echo requestId, so do
not promise guaranteed correlation. Never loop endlessly on NO_FILL.
The Launcher manages its session and provider bridge; do not manually construct an Auth video-page URL as a substitute. Sandbox/preview does not prove revenue. A local OK is not a trusted reward receipt: valuable rewards require a separate verified backend receipt and once-per-session ledger. This guide does not claim that a public rewarded-ad verification endpoint already exists. Do not invent one or award production currency from a spoofable local callback.
The C# example sends this actual message as UTF-8 bytes to IDCGamesPipe,
then Flush; retain and poll the native callback for the result:
{"videoAd":true,"gameId":"1599","sandbox":true,"requestId":"unique-request-id","layout":{"mode":"fullscreen_monitor"}}
It also supports layout:{"mode":"rect","x":100,"y":80,"width":800,"height":450};
the simpler SDK wrapper intentionally exposes only the first three modes.
Do not confuse UTF-8 request encoding with native UTF-16LE JSON callback
encoding. Video compatibility callbacks may be UTF-8 text
VIDEO_AD|STATUS|gameId|sessionId|errorCode.
8. Acceptance checklist the AI must report honestly
| Test | Required result |
|---|---|
| Real EXE + signed-in Launcher | Verified backend identity for the expected IDC game |
| Missing Launcher, malformed/wrong-game/expired token, maintenance | Denied with useful error; no cached authorization fallback |
| DLC none/owned/refunded | Only the verified operational IDs unlock levels; revocation observed |
| Session renewal | No access beyond expiry; supported InitLib refresh tested in the real SDK |
| Shop sandbox pack1 and pack>1 | Correct backend quantity exactly once; all IDs mapped explicitly |
| Invalid HMAC/altered body/stale timestamp | Rejected, no inventory changes |
| Duplicate, restart, delayed callback | Durable eventual delivery once, not repeated grants |
| Refund, refund-first, consumed balance, bonus articles | Explicit tested game policy; reference gaps fixed or disclosed |
| Web and Launcher checkout | Real configured route opens correct game/product; cancellation handled |
| IDCLib game started from the Launcher | Shop opened with _OpenShop; PurchaseNotification refreshes from the backend and is closed after delivery |
| Shop opened outside the Launcher | Origins/return URLs registered; one launch code per opening; 401/403/422 handled; postMessage checks origin and source; nothing delivered from browser signals |
| Shop levels | A single level, or the server checks shop_level against the real player level |
| Lost or delayed callback | Recovered through the signed POST /api/purchase/notifications and delivered once |
| Steam player (if sold on Steam) | SteamID64 from a validated Steam session; signed launch code per opening; overlay with wallet currency; Steam sandbox purchase delivered once |
| Ads complete/skip/no-fill/error/late/duplicate | Correct UI; no unverified valuable reward |
Offline tests and sandbox payments are not real purchases. Do not charge a player, replay a production payment, rotate keys or grant entitlements to make a test pass without the corresponding authorization. Report configured, deployed, simulated and real verified outcomes separately.
idcgames://publisher/purchase-callback
Purchase callback · English
IDC Games purchase callback: contract for game servers
The complete contract of the signed notification that tells your game server about a Shop purchase or refund, and of the signed request your server uses to read those notifications back. Section 5 of the integration guide summarizes it.
Available through the publisher MCP resource
idcgames://publisher/purchase-callback, as dist/PURCHASE_CALLBACK.md in its
package, and on the publisher onboarding page.
This notification is the only proof of payment. What the Shop page reports
(postMessage, a return URL, the Launcher's PurchaseNotification) only tells
your interface to refresh.
1. Configure it
prepare_game_payment_callbackexports the game's server secret (game_server_secret, the same name in the API and the file) to a protected file on the MCP host, without showing it. Install that file in your game server's secret store.configure_game_payment_callback({game_id, callback_url, backend_ready: true})activates the callback at yourhttps://URL.get_game_payment_callbackreads back the signing mode and the key's fingerprint, never the key.
The server secret lives only on your game server: never in the executable,
public assets, logs, a URL or a chat. The public game_public_token (historical
game_secret_key) ships in the executable and never signs anything. Only a
human regenerates the server secret, in Game Configuration; update your server
when they do.
2. Request
POST <your callback URL>
Content-Type: application/json
Accept: application/json
X-IDC-Notification-Id: IDCNOTGAME_66f7a1b2c3d4e
X-IDC-Timestamp: 1759050000
X-IDC-Signature: sha256=5f0c...e9
{"action":"idcpayment","useridc":"4181858", ... ,"bought_data":[{...}]}
| Header | Meaning |
|---|---|
X-IDC-Notification-Id |
Notification id. Constant across retries of the same notification. |
X-IDC-Timestamp |
Unix seconds when this attempt was sent. |
X-IDC-Signature |
sha256= + lowercase hex HMAC-SHA256 (section 5). |
TLS certificates are verified: an invalid or self-signed certificate makes the callback fail. Timeouts: 10 s to connect, 30 s in total.
3. Body
A JSON object. Values forwarded from the payment gateway (ids, codes, flags)
usually arrive as strings; computed amounts are numbers. Parse leniently ("1"
and 1 for flags).
| Field | Description |
|---|---|
action |
Payment action reported by the payment gateway. |
useridc |
Buyer id: the IDC user id, or for Steam players the SteamID64 sent in the launch code (store_user_id). |
gamer_ip |
Buyer IP. |
transactionid |
Payment transaction id. Idempotency key, scoped to your game. |
sandbox |
1 for sandbox (test) payments: nothing was charged. Never deliver them in production (section 4). |
refund |
1 when the notification is a refund of transactionid. |
country, currency, provider |
Country code, payment currency, payment provider. |
gross, net, vat, provider_fee |
Amounts in the payment currency. |
gross_eur, net_eur, vat_eur, provider_fee_eur |
The same amounts in EUR. |
net_game_revenue_eur, net_idc_revenue_eur |
Revenue split in EUR. |
shop_currency, shop_gross |
Currency and total shown in the Shop. |
store, store_user_id |
External store (steam) and its user id, if any. |
shop_level |
Optional. Shop level the articles were priced with: {"id": 7, "level_from": 10, "level_to": 19} (section 6). |
bought_data |
Array of purchased articles (below). |
Amounts are informative. IDC verifies the payment: never recalculate or compare amounts, VAT, currency or fees to decide whether to deliver a signed purchase.
bought_data[] entries:
| Field | Description |
|---|---|
game_item_id |
Your item id, configured on the article's item (save_shop_item). |
game_article_id |
Your article/pack id (save_shop_article). |
idc_article_token |
IDC article token (article_token in the catalog). |
number_of_items |
Items granted per article. |
article_count |
Number of articles bought. |
currency, price_gross, price_net, price_eur_gross, price_eur_net |
Article prices. |
has_offer, offer_discount, has_coupon, coupon_discount |
Discounts applied. |
extra_articles |
Extra articles granted with this one (each with its game_item_id). |
offer_extra_articles |
Extra articles granted by an offer. |
number_of_items and article_count are separate fields: IDC forwards them
without multiplying. Agree the total-grant rule for multi-pack orders, test
quantity 1 and quantity > 1 end to end, and test bonus articles
(extra_articles, offer_extra_articles) separately.
Example:
{"action":"idcpayment","useridc":"42","transactionid":"WOT_example","sandbox":"1","refund":"0",
"currency":"EUR","gross":2.99,"shop_level":{"id":7,"level_from":1,"level_to":99},
"bought_data":[{"game_item_id":"credits","game_article_id":"credits_100",
"idc_article_token":"example-article-token","number_of_items":100,"article_count":1,
"extra_articles":[],"offer_extra_articles":[]}]}
4. Sandbox
The Shop opens in sandbox only when the launch code asks for it and the game's
Shop sandbox (testing) switch is on (configure_shop_integration
sandbox_enabled, or Game Configuration). The game's phase sets its default:
on in test phases, off when the game reaches Open Beta, playable Early Access or
Commercial Release (GAME_INTEGRATION.md, 6.10). IDC approval does not change
it, and the owner can override it at any phase. Sandbox purchases charge nothing and are
notified to the same URL with sandbox: 1.
Your server must not deliver them in production: check sandbox before granting
anything (deliver only to test accounts or on a test server). With the switch
off, a sandbox launch is refused (403 sandbox_disabled).
5. Signature
X-IDC-Signature = "sha256=" + hex( HMAC-SHA256( key = server secret,
msg = X-IDC-Timestamp + "." + raw body ) )
The signature covers the exact bytes of the body. Verify it against the raw body before parsing it; never re-serialize the parsed JSON. The same key and scheme sign your server's requests to IDC in the opposite direction (section 8, and the Steam launch code).
Receiver checklist
- Read the raw body.
- Recompute the signature and compare it with a constant-time function
(
hash_equals,crypto.timingSafeEqual). Reject with401on mismatch. - Reject timestamps more than 300 seconds away from your clock.
- Parse the JSON.
- Resolve the buyer and the exact
game_article_idandgame_item_idin your catalog. Unknown buyer or article: do not guess another account or item. Check the grant quantity, the sandbox flag and, if your levels differ, the shop level (section 6). - In one database transaction, record the purchase under a unique
(game, transactionid)and its grants, then commit. Deliver once pertransactionidand reverse once per refund. Duplicates are expected: answer2xxagain without delivering twice. - Answer
2xxonly after the delivery is stored. Transient failures must not answer2xx.
PHP
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_IDC_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_IDC_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
http_response_code(401);
exit;
}
$data = json_decode($raw, true);
Node (Express)
app.post('/idc/callback', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-IDC-Timestamp') || '';
const sig = Buffer.from(req.get('X-IDC-Signature') || '');
const expected = Buffer.from('sha256=' + crypto
.createHmac('sha256', secret)
.update(ts + '.' + req.body.toString('utf8'))
.digest('hex'));
if (sig.length !== expected.length || !crypto.timingSafeEqual(sig, expected)
|| Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
return res.sendStatus(401);
}
const data = JSON.parse(req.body);
// ...
});
Use express.raw, not express.json: the signature needs the raw bytes. The
runnable example idcgames://publisher/examples/verify-purchase-callback.mjs
(dist/examples/) implements this check with offline self-tests.
6. Shop level
A shop can have several levels, each with its own range of player levels,
articles, offers and prices. The Shop picks the level from the userlevel the
game passes when it opens the Shop (IDCLib _OpenShop, or the userlevel of the
launch code). IDC does not know the player's level and cannot verify it:
unless your server signs the launch code (Steam), a modified client can claim
any level and buy another level's articles or prices.
shop_level tells you which level was applied: its id and the range
level_from–level_to it had when the purchase was created. If your levels
differ, check on your server, before delivering, that the buyer's real level is
inside that range, and decide what happens when it is not (refuse and contact
support, or deliver and flag the account). If you cannot check it, use a single
level.
The field is optional: it is absent for game/DLC purchases and for purchases made before it existed. Refunds carry the level of the original purchase.
7. Refunds
A refund arrives as a notification with the same transactionid and
refund: 1, signed and retried like a purchase. Keep a separate idempotent
reversal state per transaction: a duplicate refund reverses nothing twice, and a
refund that arrives before its purchase must not let that purchase be delivered
later. Decide your policy for currency the player has already spent.
8. Delivery, retries and reading notifications back
- Any
2xxresponse marks the notification as received. - Other responses or network errors leave it pending. The first attempt is sent right after the purchase is recorded; pending notifications are retried hourly, up to 5 attempts in total. Each attempt carries the same notification id and body with a new timestamp and signature.
- After the last attempt the notification is
failed; IDC Games support can send it again.
Your server can ask which notifications IDC sent it, to recover one its receiver lost or to reconcile after an outage:
POST https://admin.idcgames.com/api/purchase/notifications
Content-Type: application/json
X-IDC-Game: <id_idcgame>
X-IDC-Timestamp: <unix seconds>
X-IDC-Signature: sha256=<HMAC-SHA256(server secret, timestamp + "." + exact raw body)>
The timestamp is accepted within 300 seconds of IDC's clock and each signature
only once: sign every request again, also retries and the next page. The public
game_public_token never signs.
Bodies:
{"transactionid": "WOT_..."}: that purchase's notification.{"since": "2026-11-01T00:00:00Z", "limit": 100}: notifications created on or aftersince(ISO 8601; without a zone it is UTC), oldest first.limitis 1 to 100 (100 by default). Whennext_cursoris notnull, send the same body with"cursor": "<next_cursor>"for the next page.
Response 200:
{
"notifications": [
{
"notification_id": "IDCNOTGAME_6731...",
"transactionid": "WOT_6731...",
"status": "delivered",
"sandbox": false,
"refund": false,
"created_at": "2026-11-02T10:00:00Z",
"attempts": 1,
"last_attempt": {"http_code": 200, "date": "2026-11-02T10:00:03+0000"},
"notification": {"action": "idcpayment", "transactionid": "WOT_6731...", "...": "..."}
}
],
"next_cursor": null
}
status:delivered(your receiver answered2xx),pending(not tried yet),retrying(it will be tried again) orfailed(no attempts left).notification: the body described in section 3. Deliver it with the same rules as a callback: idempotently bytransactionid, sandbox and refunds included. This response is not signed; TLS and your own signed request protect it.last_attempt: the HTTP code your receiver answered and when;nullbefore the first attempt.
Errors: 401 (missing, expired, replayed or wrong signature, or a game without a
private server secret), 404 (transaction not found for this game), 422
(invalid body), 429 (more than 120 requests per minute from one IP).
Reading a notification back does not mark it as delivered: only a 2xx to a
callback does. The former GET api/purchase/get_notification, authenticated
with the public token, no longer exists.
idcgames://publisher/steam-shop
Steam players · English
Selling to Steam players through the IDC Games Shop
How a game sold on Steam lets its Steam players buy Shop articles with their Steam Wallet, inside the Steam overlay. Section 6.9 of the integration guide summarizes it.
Available through the publisher MCP resource idcgames://publisher/steam-shop,
as dist/STEAM_SHOP.md in its package, and on the publisher onboarding page.
How it works
Game client (launched from Steam)
└─ asks your game server for the Shop URL, authenticated with the player's Steam session
└─ your server validates that session and gets the player's SteamID64
└─ your server asks IDC for a launch code for that SteamID64, signed with the server secret
└─ your server returns the Shop URL with ?launch=<code>
└─ the client opens it in the Steam overlay; the Shop offers only Steam Wallet
└─ the player approves the payment on Steam's page
└─ IDC sends the signed purchase callback to your server
Steam players have no IDC account: your game server vouches for them. That is why the launch code is signed with the game's server secret and why a game sold to Steam players always needs a server.
1. Prerequisites
At IDC Games:
- The game is approved and has its IDC game id (
id_idcgame;get_game). - The Shop is configured (section 3 of the integration guide) and the signed
purchase callback is active (
PURCHASE_CALLBACK.md). The server secret that verifies the callback also signs the launch code. - IDC enables the Steam payment method for the Shop and its countries. Ask IDC if no Steam payment method appears.
In Steamworks (your team):
- The game's AppID.
- In-game purchases (microtransactions) enabled for the app. See Steamworks: Microtransactions.
- A Publisher Web API Key with access to the app: Users & Permissions → Manage Groups, in the group that includes the app, Create WebAPI Key (32 hexadecimal characters). Treat it as a password.
2. Enter the Steam credentials
A person with the store_credentials_manage permission (Company Admin for their
own games) enters them in the panel: Shop → External stores, the game, the
Steam row, Configure:
- Steam AppID.
- Publisher Web API Key.
On Save the key goes straight to IDC's payment service and is never shown again (only its last four characters). To change the AppID only, edit and leave the key empty. To rotate the key: create a new one in Steamworks, enter it, make a test purchase, then revoke the old one in Steamworks. Delete stops Steam purchases for the game.
Never send the Web API Key through a chat, an email or an MCP tool input.
list_external_store_schemas and get_external_store_credential (masked) let an
agent check the configuration; set_external_store_credential accepts only public
fields and references to secrets IDC has already provisioned on its servers,
never a raw key.
3. Get the player's SteamID64 on your server
The SteamID64 you send is the account that buys and that receives the items. Your server must take it from the player's Steam session, never from a value the client sends: validate a Steam session ticket (GetAuthTicketForWebApi in the client and AuthenticateUserTicket on your server), or use the Steam authentication your backend already has.
4. Request a launch code
From your server, every time the player opens the Shop:
POST https://admin.idcgames.com/api/shop/session/launch
Content-Type: application/json
Accept: application/json
X-IDC-Game: 1615
X-IDC-Timestamp: 1794312000
X-IDC-Signature: sha256=<HMAC-SHA256(game_server_secret, timestamp + "." + exact_raw_body)>
{"store":"steam","store_user_id":"76561198000000001","userlevel":"12","channel":"url"}
| Header or field | Required | Value |
|---|---|---|
X-IDC-Game |
Yes | IDC game id. The Shop always opens for the game that signs. |
X-IDC-Timestamp |
Yes | Current Unix seconds. |
X-IDC-Signature |
Yes | sha256= + lowercase hex HMAC-SHA256, below. |
store |
Yes | steam. |
store_user_id |
Yes | The player's SteamID64 (17 digits), from section 3. |
userlevel |
No | Player level, if your Shop has levels. Signed by your server, so IDC can trust it. |
sandbox |
No | true for test purchases through Steam's sandbox (nothing is charged). Only while the game's Shop sandbox (testing) switch is on. |
channel |
No | url for the Steam overlay or a browser. Default webview; iframe and window are also accepted (integration guide 6.1). |
return_url |
No | With url or webview: a registered return URL (integration guide 6.2). |
parent_origin |
With iframe/window |
A registered web origin of the page that shows the Shop. |
Signature:
X-IDC-Signature = "sha256=" + hex( HMAC-SHA256( server secret, X-IDC-Timestamp + "." + body ) )
- The key is the game's server secret (
game_server_secret, also in the MCP file), exported withprepare_game_payment_callback: the same key that verifies the purchase callback. The publicgame_public_tokennever works. bodyis the exact bytes you send: sign the serialized JSON and send that same string without serializing it again.- Each signature is accepted once and only within 300 seconds: keep the server clock synchronized (NTP) and sign again on every request, retries included.
Responses:
| Status | Body | Meaning |
|---|---|---|
| 200 | {"success":true,"launch":"…","expires_in":60} |
Launch code, valid 60 seconds and once. |
| 401 | {"success":false,"message":"Invalid game signature"} |
Wrong, expired or replayed signature; unknown game or no private server secret; or signed with the public token. |
| 403 | {"success":false,"code":"sandbox_disabled",…} |
sandbox asked while the game's sandbox switch is off. |
| 422 | {"success":false,"message":"Unsupported store or user id"} |
store is not steam or store_user_id is not a SteamID64. |
| 422 | return_url_not_allowed, parent_origin_not_allowed, invalid_channel |
As in the integration guide 6.4. |
| 429 | Too many requests (600 per minute per server IP). | |
| 503 | Shop sessions unavailable: contact IDC. |
Request the code right before opening the Shop and a new one every time; never store, log or reuse it.
5. Build the Shop URL
https://admin.idcgames.com/shop/frontend/index?game=<id_idcgame>&lang=<lang>¤cy=<wallet currency>&article=<article>&launch=<code>
| Parameter | Required | Value |
|---|---|---|
game |
Yes | IDC game id (the same as X-IDC-Game). |
launch |
Yes | The launch code. |
lang |
No | Shop language (en, es, fr, de…). Default en. |
currency |
No | The player's Steam Wallet currency (section 8). |
article |
No | A configured article, to open it directly. |
utm_source, utm_medium, utm_campaign |
No | Campaign statistics. |
The URL never carries the SteamID64, the level, sandbox or a signature: the
Shop takes them from the code.
PHP example, on your game server:
function idcShopUrl(string $serverSecret, int $idcGameId, string $steamId64, string $lang, string $currency = ''): string
{
$body = json_encode(['store' => 'steam', 'store_user_id' => $steamId64, 'channel' => 'url']);
$timestamp = (string) time();
$signature = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $serverSecret);
$ch = curl_init('https://admin.idcgames.com/api/shop/session/launch');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body, // exactly the signed bytes
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Accept: application/json',
'X-IDC-Game: ' . $idcGameId,
'X-IDC-Timestamp: ' . $timestamp,
'X-IDC-Signature: ' . $signature,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$response = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200 || empty($response['launch'])) {
throw new RuntimeException("IDC shop launch code failed: HTTP $status");
}
return 'https://admin.idcgames.com/shop/frontend/index?' . http_build_query([
'game' => $idcGameId, 'lang' => $lang, 'currency' => $currency,
'launch' => $response['launch'],
]);
}
If the code expires or was already used (for example, the player reloads the page), the Shop shows "Your session has expired": the player closes the overlay and opens the Shop again from the game, which requests a new code.
6. Open it in the Steam overlay
The overlay is available only if the game was launched from Steam,
SteamAPI_Init() succeeded and the player has not disabled it.
C++ (Steamworks SDK):
// url: requested from your game server (section 5) right before opening the overlay
if (SteamUtils()->IsOverlayEnabled())
{
SteamFriends()->ActivateGameOverlayToWebPage(url.c_str());
}
else
{
// Overlay disabled: ask the player to enable it in Steam (Settings → In Game)
}
Unity (Steamworks.NET):
if (SteamUtils.IsOverlayEnabled())
SteamFriends.ActivateGameOverlayToWebPage(url);
- Listen to
GameOverlayActivated_tto pause the game while the overlay is open and, when it closes, refresh the inventory or balance from your server. - Open the Shop for Steam players only in the overlay: the payment approval on
Steam's page relies on the overlay's Steam session. An IDC-account session
inside the overlay is refused (
steam_overlay_requires_steam_session): Valve only allows the Steam Wallet there.
Reference: ISteamFriends::ActivateGameOverlayToWebPage.
7. What happens on purchase
- The Shop shows only Steam payment methods.
- On paying, IDC starts the Steam transaction with the game's AppID and key and opens Steam's page, where the player approves it with their wallet.
- Steam returns the player to IDC, which finalizes the payment. The payment window closes by itself.
- IDC sends the signed purchase callback to your server like any other Shop
purchase (
PURCHASE_CALLBACK.md). Itsuseridcis the SteamID64 you sent asstore_user_id;storeissteam.
Deliver only from that callback, idempotently by transactionid.
8. Known limitations
- Currency: Steam requires the player's wallet currency and rejects the
purchase otherwise. Without
currencyin the URL the Shop picks it from the player's IP, which does not always match. Pass the wallet currency when the game knows it. - One game per purchase: every article in the cart must belong to the same game.
- Web flow only: the approval happens on Steam's page inside the overlay. The
native in-game Steam dialog (
MicroTxnAuthorizationResponse_t) is not available yet. - Closing the payment window before returning from Steam leaves the purchase unfinished, with no automatic reconciliation. Steam refunds and chargebacks are not processed yet.
9. Common problems
| Symptom | Likely cause |
|---|---|
401 Invalid game signature |
The signed JSON differs from the one sent, the . between timestamp and body is missing, the key is not the server secret (the public token never works), the server clock is more than 300 s off, or a signature was reused in a retry. |
| Your session has expired right after opening | The code expired (60 s) or was already used: request a new one every time. |
| Game not found! | game is not the IDC game id. |
| No Steam payment method | Steam is not enabled for the Shop or the player's country: contact IDC. |
| Steam's payment page never opens | Steam rejected the transaction (currency, AppID, key, or microtransactions not enabled). Contact IDC with the time and transaction. |
| Internal error with articles of several games in the cart | Steam allows articles of one game per purchase. |
| Another game has the same IDC game id when saving credentials | Contact IDC support. |