DocumentationBuild a checkout flowQuickstart

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:

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.

Create a checkout link
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"
    }
  ]
}
'
ℹ️

You can also create checkout links from within your game using our Unity SDK (iOS only). These checkout links take players to a pre-authenticated web checkout. The payload can be customized to include loyalty program information, and any custom attributes you want to include.

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

API response
{
  "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.

Purchase authorization example
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 use Stash Studio to customize the checkout experience, or add webhooks to listen for events from Stash so you can perform logic on your end (e.g., update player accounts, display 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.