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. The three differ mainly in when they fire relative to the charge, and only one of them lets your server reject a purchase:
| Pattern | When it fires | Direction | Can your server reject? | Best for |
|---|---|---|---|---|
ConfirmPayment | Before the charge is captured | Stash calls your server | Yes. See the warning in that tab. | Inventory limits, purchase caps, multi-client locking |
PURCHASE_SUCCEEDED webhook | After the payment completes | Stash calls your server | No | Backends that process events asynchronously through queues, workers, or jobs |
GetPaymentEvent | After the payment completes, when you ask for it | Your server calls Stash | No | Showing rewards in the client immediately after purchase |
This is an integration-time choice, not a runtime one. Which delivery mechanism a shop uses is fixed when the shop is configured, not selected per purchase. A single shop uses one of these patterns rather than switching between them, so treat the table above as a decision you make once per integration.
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.
How is this guide?
About Stash Pay
Discover Stash Pay - a direct-to-consumer payment system designed for games and apps that offers a modern alternative to traditional in-app purchases. Integrate through browser checkout, in-game popups, websites, or custom shops.
Integrating Stash Pay
Learn how to integrate Stash Pay into your game or app with minimum setup. This guide covers creating checkout links, displaying checkouts in browser or in-app, and handling webhook events for secure payment processing.