These are structured web pages that you can redirect the user to.
ItemCart can be used to send a cart containing one or more items to be purchased via Steam. You'll need to build and maintain the cart within your own game or UI, then send the contents of that cart to Steam for purchase and activation of those items.
Your store should direct the client browser to POST directly to
using a web form. From there, depending on the browser, the user will experience slightly different purchase flows:
Stand-alone web browser (Chrome, Internet Explorer, etc):
- If wallet currency does not match, immediate redirect to return url with result code indicating mismatch (this provides an opportunity to modify the local currency of the store and resume checkout).
- Shopping cart with individual line item costs in user currency, total cost in user currency, and "Purchase" / "Cancel" buttons.
- If Cancel is selected, transaction will be cancelled with 'user declined' status.
- If Purchase is selected, transaction will be automatically finalized.
- User will be redirected to the appropriate return URL.
Steam Overlay / Big Picture web browser:
- Same as Standard Web Browser with no initial sign-in step; user cannot change account
In-game web browser with Steamworks API authentication cookie:
- If wallet currency does not match, immediate redirect to return url with result code indicating mismatch
- Web page displays notice to use the Steam Overlay to authorize the purchase
- Steam Overlay will activate automatically with a purchase/cancel dialog box
- Overlay closes, flow continues as Standard Web Browser after user selects Purchase or Cancel
<form action="https://store.steampowered.com/itemcart/checkout" method="post">
<input type="hidden" name="appid" value="234560">
<input type="hidden" name="cart" value="1001,1006*2">
<input type="hidden" name="total" value="USD499">
<input type="hidden" name="sandbox" value="0">
<input type="hidden" name="return" value="http://mystore.com/checkout.php?fromsteam=1&cartid=BA13522FE31&result=[RESULT]&orderid=[ORDERID]&steamid=[STEAMID]&name=[USERNAME]&cc=[CURRENCY]&auth=[AUTH]">
<input type="hidden" name="auth" value="9a38954f503bf38a16024a9ae9328e8fa780f5be">
<input type="hidden" name="lang" value="en">
<input type="image" src="checkout.png" alt="Checkout">
- appid - is your App ID number.
- cart - is item definition index numbers separated by commas, with optional xN or *N quantity suffix. Order does not matter. Duplicates are treated as additional quantity.
- total - is the expected total cost of the cart. Checkout will fail if this does not match. Format is upper-case currency type (USD, EUR, GBP, etc) followed by numeric total.
- sandbox - is 1 or 0. Note that sandbox=1 will fail whenever sandbox testing is not specifically enabled for your app in Steamworks.
- return - is a URL that the user will be sent to when checkout is complete and ready to be Finalized. Optional substitution fields described below.
- auth - is the HMAC-SHA1 authentication code computed from the five preceding values in order, separated by newlines, using your Itemcart Secret Key. See sample PHP at end of document. Your secret key is visible from the Economy tab of your app's Steamworks configuration page.
- lang - is an optional ICU language code ('en' for English) that sets the default language on the checkout page. This optional field is not authenticated.
The following strings will be substituted in the return url:
- [RESULT] - result code ( 0 = success, 1 = user declined, 2 = currency mismatch, 3 or above is a internal failure code ).
- [ORDERID] - 64-bit unsigned decimal integer representing Steam "orderid"; can be used with ISteamMicroTxn/QueryTxn api to verify transaction details - blank if user cancelled. Matches report generated by ISteamMicroTxn/GetReport
- [STEAMID] - 64-bit unsigned decimal integer representing user's Steam ID. Blank if user declined to log in.
- [USERNAME] - the user's chosen display name, encoded appropriately for a URL parameter. Blank if user declined to log in. CAUTION: sanitize for display - beware users named
- [CURRENCY] - currency code for user's wallet (USD, EUR, etc) - blank if user declined to log in.
- [AUTH] - the HMAC-SHA1 of the entire server-relative URL (eg, starting with "/checkout.php") computed as if [AUTH] were an empty string and everything else were already substituted. The HMAC key is your Itemcart secret key.
Sample PHP to generate "auth" value:
define( 'SECRET_ITEMCART_KEY', '11111111111111111111111111111111' );
$appid = '234560';
$cartstring = '1001,1006*2';
$totalstring = 'USD499';
$sandbox = '0'; // or '1'
$returnurl = 'http://mystore.com/checkout.php?fromsteam=1&cartid=BA13522FE31&result=[RESULT]&orderid=[ORDERID]&steamid=[STEAMID]&name=[USERNAME]&cc=[CURRENCY]&auth=[AUTH]';
$auth = hash_hmac( "sha1", "$appid\n$cartstring\n$totalstring\n$sandbox\n$returnurl", SECRET_ITEMCART_KEY );
Sample PHP to validate return URL:
hash_hmac( "sha1", str_replace( $_GET['AUTH'], "", $_SERVER["REQUEST_URI"] ), SECRET_ITEMCART_KEY ) === $_GET['AUTH']
The authentication code in the sample HTML form is computed as if the Itemcart secret key is all ones (32 characters long). Given the other field values (appid, cart, total, sandbox, return, lang) you should be able to replicate the 'auth' value; if your generated 'auth' value does not match, your code likely has errors which will prevent checkout from working.
BuyItem is a simple structured web page that allows a user to buy an in-game item using a simple Steam purchase UI.
Construct a URI for your item as follows, and direct the player to it:
- appid: The ID of the application associated with the item.
- itemdefid: The ItemDef ID to present for purchase. This item must have a price (or price_category) and must not be store_hidden. See the Item Schema.
- quantity: Optional. Multiple instances of an item may be bought; if left off, a default of 1 is assumed.
This simplified page can only be used to sell instances of a single ItemDef (including a sellable bundle). For a full-featured shopping cart, see ItemCart.
See the Inventory Schema documentation for details on specifying items for sale, including pricing and bundles.