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.
- Real-time Catalog: Sync the catalog in real time from your game server.
3. Processing events
- Authorizes the payment and holds the funds.
- Calls your backend to grant items, or delivers a webhook after the charge, depending on how the shop is configured.
- Captures the charge only after your backend grants, when the shop grants through
ConfirmPayment. - 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:
For full configuration details, see the Managed Catalog guide.
Processing events
Stash Webshop notifies your backend about a purchase in one of two ways, fixed when the shop is configured.
Granting through ConfirmPayment
This is the failsafe pattern, and the only one where your server can reject a purchase.
ConfirmPayment on your server, which validates the purchase and grants the items.PURCHASE_SUCCEEDED webhook once the capture request is accepted.Real-time Catalog integrations always use this pattern. See Real-time Catalog Payment Flow for the full sequence and for the checks only your backend can enforce.
Granting from the webhook
PURCHASE_SUCCEEDED webhook.On this pattern the charge has already been requested by the time the event reaches you, so your backend cannot reject a purchase. Delivery is queued rather than guaranteed: Stash retries a failed delivery, but a purchase never fails because its webhook could not be delivered, and there is no way to ask Stash to replay an event that never landed. Make your handler idempotent and reconcile missed events.
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:
- Webhooks Overview — configure webhooks in Stash Studio
- Webhook Listener — create a listener and verify signatures
- Webhook List — all event types and payload structures
- Webhook Retries — retry behavior and idempotent handlers
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:
- UI customization: Customize the webshop appearance in Stash Studio to match your brand.
- Advanced analytics: Track KPIs and player behavior in Stash Studio dashboard.
- Loyalty programs: Set up promotions and rewards with web-exclusive offers and promo codes.
- Performance optimization: Run load tests and optimize your deployment with Stash Studio monitoring tools.
For advanced support or custom solutions, contact the Stash team.
How is this guide?
High-Level Flow
Learn how Stash Webshop connects players to your game economy through a web-based storefront. Understand the core flow including account linking, catalog presentation, and event processing, plus the failsafe purchase flow that ensures secure transactions.
Catalog Management
Learn about the two ways to manage your Stash Webshop catalog: Static Managed Catalog for stable, Studio-managed catalogs, and Real-time Catalog for real-time synchronization with your game server.