Stash Documentation
Integration GuidesAPI ReferencePartner with usChangelog

Integrating Stash Webshop

Learn the key steps for integrating Stash Webshop including account linking setup, catalog and assets configuration, and processing events through webhooks. Follow this comprehensive guide to implement your webshop integration.

Use this article to learn the key steps for integrating Stash Webshop. It outlines the main components of the integration and helps you choose the path that fits your setup. The video below walks you through the process.

Apple Pay and Google Pay do not work in the test environment without individual setup. Both require sandbox accounts. Contact your Stash representative to provision them for your test environment if needed.

Integration overview

Stash Webshop integration has three core components. You can implement them in any order, but start with account linking to simplify the integration process.

1. Setup account linking

  • Implement account linking methods.
  • Set up your login provider (Apple, Google, Facebook, custom JWT/OIDC).

2. Catalog and assets setup

Select webshop catalog approach:

  • Static (Managed Catalog): Set up in Stash Studio. Use this option for stable catalogs.
  • Dynamic (Unified Catalog): Sync the catalog in real time from your game server.

3. Processing events

  • Pre-authorizes payments.
  • Notifies your backend to grant items.
  • Confirms the transaction before finalizing the charge.
  • Uses signed webhooks for secure, reliable communication.

Setup account linking

Stash Webshop supports two authentication methods — Direct Sign-in (SSO) in the browser, and Account Linking via deep links and QR codes for passwordless login through the game client. Pick the method that fits your players, configure one or more identity providers in Stash Studio, then implement the chosen flow.

Authentication Methods

Compare Direct Sign-in (SSO) and Account Linking and choose which to implement.

Authentication Providers

Configure Apple, Google, Facebook, Game Center, Play Games, Cognito, or custom JWT/OIDC.

Account Linking Setup

Deep link scheme, game client handling, and session-code API call.

Catalog and assets setup

Stash Webshop supports two catalog approaches. Pick the one that matches your team's workflow and infrastructure.

Recommended for new integrations — configure and launch your webshop entirely in Stash Studio with no code required. Best for stable catalogs that don't change frequently per player.

Setup:

In Stash Studio, select your game.
Navigate to Webshop → Products.
Create and configure your products with images, descriptions, and pricing.
Organize products into sections and set visibility rules.

For full configuration details, see the Managed Catalog guide.

Advanced — fetch offers in real time from your game server whenever the webshop loads. Best for personalized catalogs, A/B testing, or when offers depend on player state.

Setup:

Create a REST API endpoint on your game backend that returns catalog rows (products + banners) as JSON.
Configure the endpoint URL in Stash Studio.
Test with different player IDs to verify personalization.

For the required JSON schema, attribute reference, and full implementation details, see the Dynamic Catalog guide.

Processing events

Stash Webshop uses signed webhooks to notify your backend when a purchase completes. The flow follows a failsafe pattern: Stash pre-authorizes the charge first, your server grants items, and the charge is only finalized after your server confirms fulfillment — preventing disputes from technical issues.

Purchase flow

Pre-authorization — Stash pre-authorizes the payment and holds funds.
Item granting — your server receives the PURCHASE_SUCCEEDED webhook and grants items to the player.
Confirmation — your server confirms fulfillment back to Stash.
Finalization — Stash finalizes the charge only after confirmation.

The primary event for granting items is PURCHASE_SUCCEEDED, where the source field is "Cart" for Webshop purchases.

Stash Webshop also emits optional analytics events (MUTATE_CART, VIEW_ITEM, VIEW_CHECKOUT_PAGE, VIEW_PRODUCT_DETAIL_PAGE, CART_BUTTON_CLICK, CREATE_PAYMENT_INTENT, FREE_ITEM_REDEEMED) that you can subscribe to for cart-abandonment tracking, product interest, and promo campaign analytics. See the Webhook List for full payload schemas.

Configuring webhooks

Configure your webhook endpoint URL and authentication in Stash Studio under Settings → Webhooks, then implement a listener that verifies the signature and grants items idempotently. See the webhook guides for full implementation details:

Testing your integration

To test your Stash Webshop integration, use test card numbers that work with Stash's test environment. These test cards allow you to complete transactions without creating real charges, making it safe to test your integration repeatedly.

Environment Requirements:

  • Test/Development/Staging: Use test cards only. Test cards work in test environments and will be rejected in production.
  • Production: Use real, live payment cards only. Real cards are required for production transactions and will be rejected in test environments.

When testing your webshop:

  • Use test cards in your development and staging environments only
  • Verify that webhooks are received correctly for test transactions
  • Test the complete purchase flow from catalog browsing to item granting
  • Confirm that your server properly verifies and grants items after test purchases
  • Test account linking flows with different authentication providers
  • Always verify you're using the correct environment (test vs production) before processing transactions

For a complete list of test cards and testing guidelines, see Test Card Numbers.

Next steps

After you complete the core steps, add features to improve your webshop:

For advanced support or custom solutions, contact the Stash team.

How is this guide?

On this page

Integration overviewSetup account linkingCatalog and assets setupProcessing eventsPurchase flowConfiguring webhooksTesting your integrationNext steps