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.

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.

Where the Money Is at Each Step

Every Stash Pay purchase runs the same payment sequence, whichever granting flow you choose. The sequence tells you what has already happened to the player's money by the time your backend hears from Stash.

Authorize

Stash asks the player's bank to check and reserve the funds. The money is held, not taken.

Grant (`ConfirmPayment` pattern only)

Stash calls your backend here and waits for your response. The funds are already held at this point, so your response decides whether they are taken or released. The other two patterns have no step here.

Capture

Stash requests the capture that draws the held funds. On the ConfirmPayment pattern, capture runs only after your backend returns success.

`PURCHASE_SUCCEEDED`

Stash queues the webhook as soon as the capture request is accepted.

PURCHASE_SUCCEEDED marks the capture request, not settlement. Stash sends the event as soon as the payment provider accepts the capture, and settlement happens asynchronously after that. Read the event as "the purchase completed and capture was requested", not as a settlement receipt.

Not every payment method has a separate capture step. Some settle at authorization, and which ones do depends on the method and on the provider processing it. The sequence above is otherwise unchanged, but there is no hold to release: the funds moved when the payment was authorized, so reversing such a purchase takes a refund. Standard card payments follow the authorize-then-capture sequence. If the behaviour of a specific method matters to your integration, check with your Stash engineering partner.

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`	After the funds are held, before they are captured	Stash calls your server	Yes. See the warning in that tab.	Inventory limits, purchase caps, multi-client locking
`PURCHASE_SUCCEEDED` webhook	After capture is requested	Stash calls your server	No	Backends that process events asynchronously through queues, workers, or jobs
`GetPaymentEvent`	After the purchase 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 captures the payment and then sends your backend a PURCHASE_SUCCEEDED event. Your server has no say in whether the charge goes through.

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:

Player completes checkout.

Stash authorizes the payment, then captures it.

Stash queues a PURCHASE_SUCCEEDED webhook to your backend.

Your backend consumes the event, runs game logic, and grants rewards.

Delivery is queued, not guaranteed. Stash hands the event to a delivery queue and retries a failed delivery, but a purchase never fails because its webhook could not be delivered, and there is no way to ask Stash to replay an event that never landed. On this pattern the webhook is your only delivery signal, so make your handler idempotent and reconcile missed events with GetPaymentEvent. See Webhook Retries and Idempotency.

For full implementation details see the Webhook guides.