Stash Documentation
Integration GuidesAPI ReferencePartner with us
Web Integration

Web Apps & WebGL

Integrate Stash Pay in websites, web apps, and WebGL games using the Stash Pay web SDK.

Repository

github.com/stashgg/stash-web

NPM Package

@stashgg/stash-pay

Playground

Live config and callback playground.

Install the SDK

npm install @stashgg/stash-pay

The package supports three integration modes from one install:

  • React component (@stashgg/stash-pay)
  • Framework-agnostic API (@stashgg/stash-pay/vanilla)
  • Script-tag UMD bundle (window.StashPay.open(...))

Presentation modes

React component

Use this when checkout state is controlled by your app UI and component lifecycle.

import { StashPay } from '@stashgg/stash-pay';
import '@stashgg/stash-pay/styles';

<StashPay
  isOpen={isOpen}
  checkoutUrl={checkoutUrl}
  onSuccess={(e) => console.log('paid', e.orderId)}
  onFailure={(e) => console.log('failed', e.message)}
  onClose={() => setIsOpen(false)}
/>

Vanilla API

Use this when you want framework-agnostic control.

import { open } from '@stashgg/stash-pay/vanilla';
import '@stashgg/stash-pay/styles';

open({
  checkoutUrl,
  onSuccess: (e) => console.log('paid', e.orderId),
  onFailure: (e) => console.log('failed', e.message),
  onClose: () => console.log('closed')
});

Script-tag UMD (WebGL-friendly)

Use this in plain HTML or embedded game contexts (including Unity WebGL pages).

<script src="https://unpkg.com/@stashgg/stash-pay@2/dist/umd/stash-pay.umd.global.js"></script>
<script>
  window.StashPay.open({
    checkoutUrl: "https://test.stashpreview.com/",
    onSuccess: (e) => console.log('paid', e.orderId),
    onFailure: (e) => console.log('failed', e.message),
    onClose: () => console.log('closed')
  });
</script>

Available parameters

The SDK options are shared across React, vanilla, and UMD integrations (except where noted).

OptionTypeDefaultNotes
checkoutUrlstring—Required checkout URL from your backend.
isOpen (React only)boolean—Required in React component mode; controls visibility.
checkoutTheme'light' | 'dark'—Forwards theme to checkout page (different from host card theming).
position'bottom-sheet' | 'center-modal' | 'side-panel-right' | 'side-panel-left''bottom-sheet'Layout preset.
widthstring | number—Override preset width.
heightstring | number—Override preset height.
zIndexnumber2147483000Host layer z-index.
portalTarget / containerHTMLElementdocument.bodyMount target element.
showCloseButtonbooleantrueShow/hide close button.
showDragBarbooleantrue on bottom-sheet, else falseBottom-sheet drag indicator.
dismissOnBackdropClickbooleantrueClose on backdrop click.
dismissOnEscapebooleantrueClose on Esc key.
autoCloseOnSuccessbooleantrueFires callback before close.
autoCloseOnFailurebooleantrueAuto-close after failure event.
backdrop{ blur?, color?, opacity?, hidden? }—Backdrop styling/visibility overrides.
themeStashPayTheme—Per-instance CSS variable overrides.
animationDurationnumber300Animation duration in ms.
ariaLabelstring'Stash Pay checkout'Dialog accessibility label.
iframeStashPayIframeOptions—Iframe behavior and security options.
injectStylesbooleanUMD: true, otherwise falseRuntime style injection toggle.
cspNoncestring—Nonce for injected style tag.
onOpen / onClose / onReady / onError / onSuccess / onFailure / onProcessingfunction—Lifecycle and payment callbacks.

For the full and always up-to-date API surface, refer to the package docs on npm: @stashgg/stash-pay.

Open checkout from websites and WebGL shells

For web games and launcher-style web surfaces, keep checkout orchestration at the page shell level:

  1. Request checkout URL from your backend
  2. Open Stash Pay from React, vanilla API, or UMD bridge
  3. Handle callbacks for UX updates
  4. Confirm final purchase state on backend before granting entitlements

For WebGL, the most common pattern is the UMD entry point from the host page and event handoff between game runtime and page JavaScript.

Playground and implementation testing

Use the Stash Pay Playground to:

  • test checkout URL behavior quickly
  • validate config changes and visual options
  • inspect callback events in real time

Detailed references

How is this guide?

On this page

Install the SDKPresentation modesReact componentVanilla APIScript-tag UMD (WebGL-friendly)Available parametersOpen checkout from websites and WebGL shellsPlayground and implementation testingDetailed references