High-Level Flow
Learn how Stash Pay's purchase flow works and discover three integration patterns for granting purchases based on your existing infrastructure.
This article walks through three Stash Pay integration patterns and when to use each one, based on:
- Your game-specific technical requirements and limitations.
- Your backend architecture (async/event-based vs. synchronous).
- Your preferred in-game purchase-granting behavior.
Initial Setup
Set up Stash Pay instance
To set up Stash Pay, contact the Stash team. After onboarding, you'll receive access to Stash Studio, our developer portal. Your game instance (including payment processing) will be created for you so you can begin the integration.
Get your API key
Once you have your Stash Studio instance all set up, the only prerequisite is creating your first API key. You'll use this key to call Stash Pay API endpoints from your game backend. Specifically, you'll need an Ingress API key for the GetPaymentEvent endpoint, and an Egress API key for the ConfirmPayment endpoint.
Core Checkout Flow (Common to All Options)
All three options share the same basic checkout flow:
Requesting Checkout
From your game backend, request a checkout session via the Stash API.
Get Checkout URL
Receive a customized checkout URL and a checkout link order ID (UUID) from Stash. Store this ID on your backend, associated with the player and the pending purchase.
Show Checkout
Display the checkout to the player via redirect, popup, or in-app browser. The player reviews the purchase and completes payment using the configured payment methods.
While these three steps are always consistent, the way you finalize the purchase and grant items can vary. Choose the granting flow that best fits how your game handles reward delivery and payment confirmation below:
Choosing Your Granting Flow
Select the pattern that best matches your backend architecture and reward-granting requirements. You can also combine patterns — for example, use ConfirmPayment for pre-purchase validation alongside GetPaymentEvent for client-side confirmation.
Async post-purchase — Stash sends your backend a PURCHASE_SUCCEEDED event after the payment completes.
Direction: Stash → Game (your backend exposes a webhook endpoint).
Best for: Backends that already process events via queues, workers, or background jobs. Rewards may appear slightly after purchase.
Flow:
PURCHASE_SUCCEEDED webhook to your backend.For full implementation details see the Webhook guides.
Synchronous post-purchase — your backend queries Stash for the final payment status immediately after checkout.
Direction: Game → Stash (your backend calls GetPaymentEvent).
Best for: Games where the client needs to show rewards immediately, or backends designed for synchronous request–response patterns without incoming webhooks.
Flow:
GetPaymentEvent with the purchase ID.See the GetPaymentEvent API Reference for request/response details.
How is this guide?