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.

Authorization

hmac

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

application/json

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.

TypeScript Definitions

Use the request body type in TypeScript.

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.

playerId*string

The user making the purchase

transactionId*string

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"

currency*string

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

decimalPlaces*integer

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

registrations*array<>

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 - 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')

loyalty?

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

Response Body

`application/json`

curl -X POST "https://example.com/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"    }  ]}

Register payment intent

Authorization

Request Body

Response Body

200application/json

defaultapplication/json

`application/json`

`application/json`