Integrating Stash Pay

Stash Pay is a direct-to-consumer payment system for games and apps.

This guide shows how to integrate it with the minimum setup, whether for a browser based or in-app purchases.

The video below walks you through the process.

Create a checkout link

Send a POST request to the /sdk/server/checkout_links/generate_quick_pay_url endpoint from your backend to start a Stash Pay purchase.

Include your API key in the request header as X-Stash-Api-Key: YOUR_API_KEY.

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 is successful, you will receive a unique 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"
}

Displaying the checkout

You can display the checkout in a browser or in-app. Choose the option that works best for your integration.

Browser Purchase

To present the checkout, open the URL on the user's device using your preferred method (e.g., browser window).

window.open(stash_pay_url, '_blank');

Example in Unity using Application.OpenURL.

public class CheckoutHandler : MonoBehaviour
{
    public void OpenCheckoutURL(string stash_pay_url)
    {
        Application.OpenURL(stash_pay_url);
    }
}

In-App purchase

Stash Pay can also be used as a direct replacement for traditional in-app purchases. Refer to the Unity iOS & Android Integration guide for options on presenting the checkout within using Stash SDK.

Processing Purchase Events

Once a purchase is complete, your system must process the event to grant items to the player. Stash supports two approaches for receiving purchase events. Always handle and verify purchase events server-side, never on the client.

Webhooks (Recommended)

Webhooks are automated notifications that Stash sends to your backend when a purchase is completed. This webhook-based messaging system ensures reliable communication between Stash and your game server, allowing you to grant items to players only after payment is confirmed.

When a purchase event is triggered, Stash sends an HTTP POST request with a JSON payload to the webhook URL you've configured in Stash Studio.

Example webhook message payload

{
  "type": "PURCHASE_SUCCEEDED",
  "purchaseSucceeded": {
    "timeMillis": 1753993257000,
    "orderId": "8ZVBabLrnCMm9zPdu9QpfCWzNaA",
    "currency": "usd",
    "userId": "user_id",
    "items": [
      {
        "id": "item_id",
        "quantity": 1,
        "price": "199"
      }
    ],
    "tax": "0",
    "total": "199",
    "regionCode": "US",
    "source": "StashPay"
  }
}

For complete webhook implementation details, see our webhook documentation:

• Webhooks Overview - Learn about webhooks and how to configure them in Stash Studio
• Webhook Listener - Create a webhook listener and verify webhook signatures
• Webhook List - View all available webhook event types and payload structures

Fetch Purchase Status

You can also retrieve purchase status manually by querying the payment endpoint. This approach requires you to poll the endpoint to check if a purchase has been completed.

Send a GET request to retrieve payment information:

GET https://test-api.stash.gg/sdk/server/payment/<payment_id>

For complete endpoint documentation, see Get Payment Event API Reference.

This method is useful for scenarios where you need to check purchase status on-demand or when webhooks are not available, but webhooks are recommended for real-time processing.