Stash Documentation
Integration GuidesAPI ReferencePartner with usChangelog

Register payment intent

Step 1: Registers a purchase intent with the game backend. The game backend is expected to reserve inventory for the purchase. IMPORTANT: Always expects HTTP 200 OK response with inline error codes in the body.

POST
/api/v1/purchase/register

Authorization

x-stash-hmac-signature<token>

Versioned HMAC-SHA256 signature for server-to-server communication between game backends and Stash services. Recommended over the deprecated legacyHmac scheme for the best security. Header format: v1;{shopId};{unixMillisTimestamp};{base64Signature} (semicolon-delimited). {base64Signature} is the base64-encoded HMAC-SHA256 of the string {unixMillisTimestamp}.{requestBody} signed with your Egress API key, where {requestBody} is the compact request JSON. The timestamp must be within 5 minutes of Stash server time. Your shopId is your immutable shop identifier; it and your Egress API key are available in Stash Studio under Project Settings > API Secrets.

In: header

Request Body

Request to register a purchase intent with the game backend, at which point the game backend is expected to reserve the inventory for the purchase.

playerIdstring

The user making the purchase

transactionIdstring

Unique transaction identifier for this purchase session

checkoutLinkId?string

Optional checkout link identifier if purchase was made through a checkout link

shopId?string

The originating Stash shop identifier (mirrors the shopId sent in webhooks)

environment?server.egress.shop.v1.PaymentEnvironment

Payment environment for the request

Default"PAYMENT_ENVIRONMENT_UNSPECIFIED"
Value in"PAYMENT_ENVIRONMENT_UNSPECIFIED" | "PAYMENT_ENVIRONMENT_TEST" | "PAYMENT_ENVIRONMENT_PRODUCTION"
currencystring

Currency code (ISO-4217 code, e.g., 'USD', 'EUR')

decimalPlacesinteger

CLDR fraction-digit count for this ISO 4217 currency, from public CLDR supplemental data for this currency code. Always sent, including the literal 0 for zero-decimal currencies (e.g. JPY, KRW).

Formatint64
registrationsarray<Purchase Registration>

List of items to register for purchase

platform?- PURCHASE_PLATFORM_UNSPECIFIED: Default unknown platform

Platform making the purchase

Default"PURCHASE_PLATFORM_UNSPECIFIED"
Value in"PURCHASE_PLATFORM_UNSPECIFIED" | "PURCHASE_PLATFORM_IOS" | "PURCHASE_PLATFORM_ANDROID" | "PURCHASE_PLATFORM_WEBSTORE"
browser?string

Browser information for web purchases (e.g., 'Chrome/91.0', 'Firefox/89.0', 'Safari/14.1', 'any')

deviceId?string

Device identifier for tracking and fraud prevention (can be generated client-side)

source?- PURCHASE_SOURCE_UNSPECIFIED: Default unknown source - PURCHASE_SOURCE_CART: Purchase initiated from cart in webstore - PURCHASE_SOURCE_DIRECT: Purchase initiated from direct StashPay checkout link

Source of the purchase for analytics

Default"PURCHASE_SOURCE_UNSPECIFIED"
Value in"PURCHASE_SOURCE_UNSPECIFIED" | "PURCHASE_SOURCE_CART" | "PURCHASE_SOURCE_DIRECT"
ipAddress?string

Customer IP address for fraud prevention and compliance

region?string

Region/country code using ISO-3166-1 alpha-2 code (e.g., 'US', 'CA', 'GB')

Response Body

curl -X POST "https://loading/api/v1/purchase/register" \  -H "Content-Type: application/json" \  -d '{    "playerId": "string",    "transactionId": "string",    "currency": "string",    "decimalPlaces": 0,    "registrations": [      {        "guid": "string",        "productId": "string",        "cents": 0,        "quantity": 0      }    ]  }'
{
  "statuses": [
    {
      "guid": "string",
      "productId": "string",
      "status": "PURCHASE_REGISTRATION_STATUS_UNSPECIFIED",
      "message": "string"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string",
      "property1": null,
      "property2": null
    }
  ]
}

How is this guide?