Integrating Stash Webshop

This article serves as a hub to highlight the key steps for integrating Stash Webshop. Since every integration is unique, you’ll find links throughout to more detailed articles tailored to your preferred setup and requirements. Use this overview to understand the main components, then dive deeper into the sections that best fit your integration path.

Introduction video

Integration overview

Integrating Stash Webshop involves three core components. While you can implement them in any order, we recommend beginning with account linking for a smoother integration process.

1. Setup Account Linking

• Implement account linking methods.
• Your login provider setup (Apple, Google, Facebook, custom JWT/OICD).

2. Catalog & Assets Setup

• Select webshop catalog approach:
  • Static (Managed Catalog): Setup via Stash Studio; ideal for stable catalogs.
  • Dynamic (Unified Catalog): Real-time catalog sync from your game server.

3. Processing Events

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

1. Setup Account Linking

Authentication Providers

Begin by configuring your preferred authentication provider in Stash Studio. This step does not require any code changes—simply enter your provider credentials in the Studio interface. For detailed instructions, refer to the dedicated article on player authentication.

Account Linking Implementation

Implement account linking to enable seamless player authentication. This method allows players to authenticate by launching your game via a deep link (on mobile) or scanning a QR code (on desktop).

Key steps:

1. Configure deep linking in Stash Studio with your game’s URL scheme
2. Implement deep link handling in your game client
3. Send authentication data to Stash API with the session code

For detailed implementation steps, see our Account Linking guide.

2. Catalog & Assets Setup

Choose between two catalog approaches based on your needs and existing infrastructure:

Managed Catalog (Recommended for new integrations)

The managed catalog is the easiest way to launch your Stash webshop, requiring no code. All catalog management is handled through the Stash Studio interface.

Setup steps:

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

For detailed instructions, see our Managed Catalog guide.

Dynamic Catalog (Advanced)

The dynamic catalog fetches offers in real time from your game server whenever the webshop loads. This approach gives you full control using your existing tools and enables personalized catalogs.

Setup steps:

1. Create a REST API endpoint on your game backend
2. Configure the endpoint URL in Stash Studio
3. Implement the catalog response following the required JSON structure
4. Test with different player IDs to verify personalization

Your endpoint should return a JSON response with catalog rows containing products and banners. Each product includes pricing, images, descriptions, and optional attributes for visual enhancements.

For detailed implementation, see our Dynamic Catalog guide.

3. Processing Events

Stash uses webhooks to notify your backend when players interact with your webshop. These events enable you to grant items, track analytics, and maintain synchronization between your game and the webshop.

Webhook Setup

Configure webhooks in Stash Studio to receive real-time notifications:

1. In Stash Studio, navigate to your game settings
2. Go to Settings → Webhooks
3. Add your webhook endpoint URL
4. Configure authentication if required
5. Test the webhook connection

Key Webhook Events

Stash sends various webhook events to your backend:

• PURCHASE_SUCCEEDED: Fired when a purchase is successfully completed
• MUTATE_CART: Fired when items are added, removed, or modified in cart
• VIEW_ITEM: Fired when a user views a specific item
• CREATE_PAYMENT_INTENT: Fired when a payment process is initiated
• FREE_ITEM_REDEEMED: Fired when a user redeems a free item

Purchase Flow Implementation

The purchase flow follows a failsafe pattern to prevent disputes:

1. Pre-authorization: Stash pre-authorizes payment and holds funds
2. Item Granting: Your server receives a webhook and grants items to the player
3. Confirmation: Your server confirms fulfillment back to Stash
4. Finalization: Stash finalizes the charge only after confirmation

This process ensures players are only charged once fulfillment is complete, preventing disputes due to technical issues.

For detailed webhook implementation, see our Webhooks Overview and Webhook List documentation.

Next Steps

After completing these core integration steps, you can enhance your webshop with additional features:

• UI Customization: Customize your webshop’s appearance to match your brand through Stash Studio
• Advanced Analytics: Track real-time KPIs and player behavior through Stash Studio analytics
• Loyalty Programs: Set up promotional campaigns and reward systems with web-exclusive offers and promo codes
• Performance Optimization: Conduct load testing and optimization for production deployment using Stash Studio monitoring tools

For comprehensive integration support and customization options, contact the Stash team to discuss your specific requirements.

All systems operational