Integrating Stash Pay

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

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.

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 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"
}

Displaying the checkout

You can display the checkout either in a browser or inside the game. Choose the option that best fits 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 to present the checkout using the 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, so you can grant items to the player 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 polling the endpoint to check whether 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.