Payment Flow

On a Real-time Catalog integration, your backend owns the catalog: pricing, availability, and per-player limits are all computed by you, at the moment Stash asks. That makes ConfirmPayment required rather than optional. It is the only point in the flow where Stash shows you a purchase that is still in progress and lets you decline it before the payment is captured.

This page covers web shop purchases, both from the cart and from Buy Now. The same ConfirmPayment contract applies when the same backend also powers Stash Pay checkout links; see Stash Pay High-Level Flow for that surface.

RegisterPayment, ConfirmPayment, and the pre-flight checks on this page apply only to the Real-time Catalog. A managed catalog purchase skips them: Stash authorizes and captures the payment, then your backend grants the items from the PURCHASE_SUCCEEDED webhook. See Granting from the webhook.

Where the Money Is at Each Step

ConfirmPayment Is Required

Stash calls ConfirmPayment on every Real-time Catalog purchase. There is no shop configuration that skips it, and no response that means "Stash should decide".

• Success is a non-empty results array. ConfirmPayment has no status field. Returning the granted results in the body is how your backend says yes.
• A 200 with an empty or absent results array is a failure. It confirmed nothing, so Stash treats it the same as an error response rather than as a silent success.
• Every failure looks the same to Stash. A deliberate rejection, an unhandled 500, a timeout, and a malformed body are all handled identically.

When the call does not succeed, Stash does not capture. The authorization is released or left to expire at the payment provider and the player is not charged, so the bad case is "not charged, not granted" rather than "charged, not granted". A payment method that settles at authorization has no hold to release: its funds moved when the payment was authorized, so reversing that purchase takes a refund. If you implement the RegisterPayment and CancelPayment pair, Stash also calls CancelPayment on the cart flow so you can release the reservation you took.

The Catalog Read Before Checkout Is a Snapshot

Stash reads your catalog once more just before checkout. For a cart purchase it reads when the player starts checkout, as it creates the payment. For a Buy Now purchase it reads when the player taps Buy Now, before the checkout opens. Stash validates that the items still resolve and takes the price, the item's expiration, and its maxPurchasable from that read. The read is a snapshot of what your server said, not a reservation:

• Nothing holds stock between the read and the charge. No reservation is taken at catalog-read time on either side. A player can sit on the checkout page, and the same allowance can be spent elsewhere in the meantime.
• The read can be served from cache. It goes through the same catalog path as any other read, so the catalog cache applies to it.

Stash Keeps No Ledger of Your Limits

maxPurchasable is the player's remaining allowance as your server computed it at read time. For the items your catalog returns, Stash keeps no count of its own and never decrements the value: it checks the purchase against what the pre-checkout read returned.

Stash runs two pre-flight checks, both on values from that pre-checkout read rather than on a fresh read when the purchase is confirmed:

A rejected pre-flight check fails the purchase before Stash calls RegisterPayment or ConfirmPayment, and Stash does not capture the payment.

These checks catch the obvious stale cases cheaply. They are not a substitute for your own check, because each value is only as fresh as the read it came from.

What Only Your Backend Can Enforce

Anything that depends on your live state has to be enforced in ConfirmPayment, because that is the last moment before the charge at which you are consulted:

• Limits shared across several offers. Stash sees a per-item maxPurchasable, not a budget spanning a bundle, an offer chain, or a campaign.
• Stock that is also sellable elsewhere. Anything a player can also buy in-game or on another surface can be consumed between the catalog read and the charge.
• Per-player caps and eligibility. Daily caps, cooldowns, progression gates, and anti-abuse rules all live in your systems.
• Anything priced or gated on live state. If the answer can change between the catalog read and the charge, the catalog snapshot cannot hold it.

Next Steps