Integrating Stash Webshop

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.

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

Set up account linking by implementing the linking method and configuring your login provider (Apple, Google, Facebook, or custom JWT/OIDC).

Authentication providers

Configure your preferred authentication provider in Stash Studio. Enter your provider credentials in Stash Studio. No code changes are required. For more information, see Player authentication.

Account linking implementation

Implement account linking to enable player authentication. Players authenticate by launching your game through a deep link (on mobile) or by 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 the Stash API with the session code.

For more information, see Account Linking.

Catalog and assets setup

Stash Webshop supports two catalog approaches. Choose the option that best fits your setup and infrastructure.

Managed catalog (recommended for new integrations)

Configure and launch your webshop in Stash Studio with the managed catalog. This option requires no code.

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 more information, see Managed Catalog.

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 more information, see Dynamic Catalog.

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 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 these events to your backend:

• PURCHASE_SUCCEEDED: Sent when a purchase completes successfully.
• MUTATE_CART: Sent when items are added, removed, or modified in cart
• VIEW_ITEM: Sent when a player views a specific item
• CREATE_PAYMENT_INTENT: Sent when a player initiates a payment.
• FREE_ITEM_REDEEMED: Sent when a player initiates a payment.

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 more information, see Webhooks Overview and Webhook List.

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 analytics.
• 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.

All systems operational