Integrating Stash Pay

This guide explains how to integrate Stash Pay using the basic setup: creating checkout links, showing the checkout to players, and processing purchase events.

The video below provides a quick walkthrough of the integration flow.

Create a checkout link

To create a checkout session, send a POST request from your backend to the /sdk/server/checkout_links/generate_quick_pay_url endpoint. Please check out the full API reference to see all the payload options.

Checkout link request

Here's a sample payload for creating a checkout link:

{
  "item": {
    "id": "",
    "pricePerItem": "",
    "quantity": 1,
    "imageUrl": "",
    "name": "",
    "description": ""
  },
  "user": {
    "id": "",
    "validatedEmail": "",
    "profileImageUrl": "",
    "displayName": "",
    "regionCode": "",
    "platform": "UNDEFINED"
  },
  "transactionId": "",
  "regionCode": "",
  "currency": ""
}

Checkout link response

If your request succeeds, you will receive a checkout URL that you can present to the user using any of the methods described below.

{
  "url": "https://store.example.com/order/abc123",
  "id": "abc123",
  "regionCode": "US"
}

Authentication

Authenticate calls to generate_quick_pay_url by signing the request body with your ingress secret and including the signature in the x-stash-hmac-signature header. Your ingress secret is distinct from the egress key used to verify Stash's outbound requests. Both are in Studio → Project Settings → API Keys as base64-encoded values; base64-decode before use as the HMAC key.

x-stash-hmac-signature: v1;<appId>;<unixMillisTimestamp>;<base64-hmac>

The signature covers "<unixMillisTimestamp>." + <body>, where <body> is the exact JSON bytes you POST. Sign what you transmit — Stash verifies against the bytes received. Requests where <unixMillisTimestamp> is more than 5 minutes from the server clock are rejected.

For Node.js, Python, and Go implementation code, see API Keys → HMAC Signing.

Displaying the checkout

The simplest option is to open the checkout URL directly in a browser on the user's device. For in-app presentation with native drawers, modals, and callbacks, follow the platform-specific integration guide for your stack.

Processing Purchase

Once a player completes checkout, your system must process the event to grant items. Stash supports three patterns depending on your game's requirements, always server-side, never on the client.

The three differ mainly in when they fire relative to the charge, and only one of them lets your server reject a purchase:

Testing your integration

To test your Stash Pay integration, use test card numbers in the Stash test environment. These cards allow you to complete transactions safely, as no real charges are created, making repeated testing risk-free.

Testing Tools

Link Generator: Use the Link Generator in Stash Studio to quickly generate and test checkout links without writing code. The Link Generator allows you to: