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:

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:

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:

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:

Stash Webshop Webhook Events

Stash Webshop sends the following webhook events to your backend:

Required Events:

• PURCHASE_SUCCEEDED: Sent when a purchase completes successfully. The source field will be "Cart" for Webshop purchases. This is the primary event for granting items to players.

Optional Analytics Events:

• MUTATE_CART: Sent when items are added, removed, or modified in cart. Use for tracking cart abandonment and shopping behavior.
• VIEW_ITEM: Sent when a player views a specific item (debounced to once per 100 seconds per item). Use for product interest tracking.
• VIEW_CHECKOUT_PAGE: Sent when a user views the checkout page. Use for tracking checkout page visits and identifying drop-off points.
• VIEW_PRODUCT_DETAIL_PAGE: Sent when a user views a product detail page. Use for product interest tracking and content engagement metrics.
• CART_BUTTON_CLICK: Sent when a user clicks the cart button/icon. Use for tracking cart interactions and shopping behavior analysis.
• CREATE_PAYMENT_INTENT: Sent when a player initiates a payment. Use for tracking checkout initiation and payment method selection analytics.
• FREE_ITEM_REDEEMED: Sent when a user redeems a free item (promotional items, rewards, etc.). Use for tracking promotional campaign effectiveness.

Note: The source field in PURCHASE_SUCCEEDED events will be "Cart" for purchases made through Stash Webshop.

Purchase flow implementation

The purchase flow follows a failsafe pattern to prevent disputes:

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

For more information, see:

• Webhooks Overview - Learn about webhooks and how to configure them
• Webhook Listener - Create a webhook listener and verify signatures
• Webhook List - View all available webhook event types
• Webhook Troubleshooting - Common issues and solutions
• Webhook Retries - Understand retry behavior and implement 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.

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.