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

loyalty?Player Loyalty State

The player's loyalty program standing that applied to this purchase. Present only for shops with an active loyalty campaign.

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?