Quickstart

Checkout links are unique URLs that allow players to make purchases. You pass a few parameters to Stash, Stash generates the link, and then you transition the player to the checkout flow. After you notify Stash that the player received their items, Stash charges the player.

Prerequisites

To complete this quickstart, you need:

• A Stash account (reach out to us if you need one)
• A game in Stash Studio

1. Create an API secret

You can generate secrets in Stash Studio, within the API Secrets section. You need a secret to make API calls.

2. Create a checkout link

Use the Checkout Links endpoint to generate a checkout link. You can copy the example below and add your API secret to create a test link. See the API Reference for more examples and supported languages.

curl --request POST \
     --url https://test-api.stash.gg/sdk/checkout_links/create \
     --header 'X-Stash-Api-Key: YOUR_API_SECRET' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "externalUser": {
    "id": "123"
  },
  "shopHandle": "docsdemos",
  "currency": "USD",
  "items": [
    {
      "id": "456",
      "pricePerItem": "5",
      "quantity": 1,
      "imageUrl": "https://test.stash.gg/_next/image?url=https%3A%2F%2Fstorage.googleapis.com%2Fpartner_assets%2F100b734e-3631-4afc-9721-dd6e5f82475e%2Fdrive-to-survive%2FOffroad%2520car%25202.png&w=640&q=75",
      "name": "Offroad car"
    }
  ]
}
'

🚧

In production, always call this endpoint from your backend and then pass the checkout link to the client. This ensures that your API key isn't exposed to the internet.

The API returns the checkout link (which you use in the next step), along with a unique id.

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

3. Create an endpoint that authorizes purchases

For each transaction, Stash verifies that the player has enough funds to cover the purchase. You then need to grant the player their items and notify Stash to charge the player. To enable this flow, you create an endpoint on your backend for authorizing purchases that Stash calls for every purchase.

📘

You need this endpoint in production scenarios but you can skip to the next step to try out a successful transaction. Stash manages purchase authorization in the example flow.

The API call passes a player ID, as well as some metadata about the items being purchased.

curl -X 'POST' \
  'https://custom.gamestudio.com/{custom_authorize_purchase_path}/{player_id} \
  -H '{x-custom-api-key}: abcdefc' \
  -H 'Content-Type: application/json' \
  -d '{
  "transactionId": "txId",
  "items": [{
    "id": "sword_123",
    "quantity": 1
  },
  {
    "id": "shield_1234",
    "quantity": 1
  }]
}'

Your endpoint needs to return a successful (200) response so that Stash can charge the player. Stash won't charge the player if any other response is made.

4. Transition to the checkout flow

Integrations and tech stacks vary so it's up to you how to transition players to the checkout flow. Regardless, use the URL from the last step to start the process.

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.

Next steps

The API Reference has more information on parameters and retrieving orders. You might also want to read about webhooks. Webhooks allow you to listen for events from Stash so you can perform logic on your end (e.g., updating player accounts, displaying notifications, etc.).

When you're ready to use checkout links in production, you might need to contact Stash to add your image domain to our allowlist.

Example repositories

There's a Checkout Link client example built with React, as well as a playground. The playground is still in active development.