Stash Documentation
Integration GuidesAPI ReferencePartner with usChangelog

Confirm payment completion

Step 2A: Confirms and completes a pending purchase that was previously registered. IMPORTANT: Expects HTTP error status (3xx, 4xx, 5xx) codes for failed purchases.

POST
/api/v1/purchase/confirm

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 confirm and complete a pending purchase that was previously registered.

playerIdstring

The user confirming the purchase

transactionIdstring

Transaction identifier to confirm

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; applies to tax, total, and line-item minor units. Value comes from public CLDR supplemental data for this currency code. Always sent, including the literal 0 for zero-decimal currencies (e.g. JPY, KRW).

Formatint64
taxinteger

Tax as integer minor units per CLDR for this ISO 4217 currency (e.g. 99 for $0.99 in USD; can be 0)

Formatint64
totalinteger

Total including tax, as integer minor units per CLDR for this ISO 4217 currency (e.g. 1098 for $10.98 in USD)

Formatint64
timeMillisstring

Timestamp when the purchase was completed (milliseconds since Unix epoch)

Formatint64
paymentMethodType?- PAYMENT_METHOD_TYPE_UNSPECIFIED: Default unknown payment method - PAYMENT_METHOD_TYPE_CARD: Standard credit/debit card payment - PAYMENT_METHOD_TYPE_APPLE_PAY: Apple Pay wallet payment - PAYMENT_METHOD_TYPE_GOOGLE_PAY: Google Pay wallet payment - PAYMENT_METHOD_TYPE_PAYPAL: PayPal payment - PAYMENT_METHOD_TYPE_KLARNA: Klarna buy-now-pay-later payment

Payment method used for this purchase (e.g., card, Apple Pay, Google Pay)

Default"PAYMENT_METHOD_TYPE_UNSPECIFIED"
Value in"PAYMENT_METHOD_TYPE_UNSPECIFIED" | "PAYMENT_METHOD_TYPE_CARD" | "PAYMENT_METHOD_TYPE_APPLE_PAY" | "PAYMENT_METHOD_TYPE_GOOGLE_PAY" | "PAYMENT_METHOD_TYPE_PAYPAL" | "PAYMENT_METHOD_TYPE_KLARNA"
itemsarray<Purchased Item>

List of items in this 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 - PURCHASE_SOURCE_BUY_NOW: Purchase initiated from webshop, skipping the Cart and going directly to Checkout

Source of the purchase for analytics

Default"PURCHASE_SOURCE_UNSPECIFIED"
Value in"PURCHASE_SOURCE_UNSPECIFIED" | "PURCHASE_SOURCE_CART" | "PURCHASE_SOURCE_DIRECT" | "PURCHASE_SOURCE_BUY_NOW"
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')

userEmail?string

Customer email for the purchase

emailMarketingOptIn?boolean

Optional flag indicating if customer opted in to email marketing

bonusItems?array<Bonus Item>

Optional list of bonus items to be granted with the purchase

Response Body

curl -X POST "https://loading/api/v1/purchase/confirm" \  -H "Content-Type: application/json" \  -d '{    "playerId": "string",    "transactionId": "string",    "currency": "string",    "decimalPlaces": 0,    "tax": 0,    "total": 0,    "timeMillis": "string",    "items": [      {        "guid": "string",        "productId": "string",        "quantity": 0,        "cents": 0      }    ]  }'
{
  "results": [
    {
      "guid": "string",
      "productId": "string"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string",
      "property1": null,
      "property2": null
    }
  ]
}

How is this guide?

Cancel pending payment POST

Step 2B: Cancels a pending purchase that was previously registered. IMPORTANT: Always expects HTTP 200 OK response with inline error codes in the body.

Register payment intent POST

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.