DocumentationBuild a checkout flowQuickstart

Quickstart

Create a checkout link server-side using the Stash API. This generates a unique URL and ID for the session. Send the URL to the game client to open in a browser or with the Stash Popup component.

Generating Checkout

Generate a checkout link by calling /generate_quick_pay_url endpoint from your game server, supply the user data and id of the item from your catalog to purchase:

curl --request POST \
     --url https://test-api.stash.gg/sdk/server/checkout_links/generate_quick_pay_url \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-stash-api-key: YOUR_STASH_API_KEY' \
     --data '
{
  "user": {
    "id": "USER_ID",
    "validated_email": "USER_EMAIL"
  },
  "shop_handle": "YOUR_SHOP_HANDLE",
  "item_id": "ITEM_ID"
}
'

If the request was sucessful you will recieve back a unique URL and checkout ID. Checkout ID is helpful for fetching back the order data and payment state using dedicated API endpoints.

{
  "url": "https://test.stash.gg/yourshop/order/.....9ecfff31c720",
  "id": "2e902916-484b-4bb8-843e-9ecfff31c720"
}

Displaying Checkout

Once you have successfully generated the checkout URL, it’s time to present it to the user from the game client. There are several methods to achieve this.

Stash Popup

ℹ️

Stash Popup is currently available only on iOS. Availability on Android depends on the D2C court rulings. On Android, a browser fallback is automatically used.

Stash Popup is a Unity plugin that provides a customizable card-style popup specifically designed for Stash Pay links, allowing players to complete their purchases without interrupting or leaving the game. Popup also give you the ability to listen to the payment callbacks in the game client.

  1. Download & Import the Stash.Popup package into your Unity project.
  2. The plugin will be automatically included in your build & provides a singleton StashPayCard class that handles all interactions with the popup card.
  3. Call StashPayCard.Instance.OpenURL and supply the generated checkout URL.
using StashPopup;
 
public class YourClass : MonoBehaviour
{  
    void OpenPaymentCard()
    {
        // Open the Stash Pay URL coming from the backend in the card.
        // Card offers two callbacks - on dismiss and on successful payment.
        StashPayCard.Instance.OpenURL("STASH_PAY_URL", OnStashPayDismissed, OnStashPaySuccess);
    }
    
    void OnStashPayDismissed()
    {
        Debug.Log("Card was dismissed.");
        // Do nothing.
    }
    
    void OnStashPaySuccess()
    {
        Debug.Log("Payment was successful.");
        // Verify purchase using Stash API & grant purchase to the user.
    }
}

Browser

Using a browser is a straightforward integration method. You just need to open the URL in the system’s default browser, allowing the user to complete the purchase externally. This approach doesn’t require any additional packages but may impact the user experience. It also serves as the default fallback option for the Stash Popup.

In Unity we can trigger system default browser simply by calling:

Application.OpenURL(STASH_PAY_URL);

Handling Purchases

Purchases are handled by listening to webhook events coming from Stash on your game server. Refer to the webhook guide for integrating purchase notifications for both Stash Pay and Stash Webshops.

Testing

You can test the checkout flow using the URL you created in step two. Use these payment details to test a successful payment:

  • Card number: 4242 4242 4242 4242
  • Expiration: 12/30 (or any future date)
  • CVC: 123 (or any three digits)
  • ZIP: 12345 (or any five digits)

You can optionally pass an email address to receive a receipt.