Microtransactions Implementation Guide (Steamworks Documentation) (2024)

Overview

The goal of the Steam in-game payment system is to provide an easy way for developers to sell arbitrary goods to users such that the user never has to leave the game experience. It's completely up to the merchant what they want to sell. It can be in-game items like weapons or ammunition, game currency like coins or gold, or even attire for your player character. You can have as many or as few items as you like in your game and you can sell them one at a time or as bundled groups. Steam places no restrictions on what you sell or how you sell it nor does it preclude the use of whatever other mechanisms your game has for selling items. Its purpose is to bring a common payment experience that user's are familiar with from the Steam platform into your game and allow them to easily spend their Steam wallet value on your products. Using this type of integration, your game will have immediate access to new Steam users and payment methods as soon as they become available.

With this system, the purchase is completely under your control. A successful response to a purchase request will result in the user reliably getting charged and you getting positive and immediate notification of the event. Once a purchase is approved, it's up to you to grant and manage the items. If an item is time based for example, your system dictates how long that item is good for.

In addition to in-game purchasing, the system will provide additional functionality that your accounting and support systems can use:

1. You can receive notification if customers fail to pay.
   
2. You can issue refunds and query transaction status through the web service.
   
3. You will have access to detailed reports on our steamstats partner site showing live sales of items and games.

Best Practices for In-Game Purchases

If you are working to bring your title with in-game purchases to Steam, we've got a few suggestions, best practices, and resources to help you get started. Whether you have a Free to Play game, or a game that is purchased upfront, there are common elements with any game that has in-game purchases that are useful to consider when working toward your launch on Steam.

Please see the Microtransactions (In-Game Purchases) documentation for suggestions for in-game economies and best practices.

How the Payment System Works

The payment system is a combination of whatever purchase process you have in-game, the Steam billing web service, and a customer approval process.

The purchase process occurs in the following sequence. Your user always starts and completes their order in your game.

1. When a user wishes to buy something in-game, your game sends a purchase request to your purchasing server. The purchasing server can be any service entity that your game system has for handling purchase requests. It could be a web server or your authentication system. The server will need to communicate with the Steam billing servers over HTTP. Your purchasing server can also request the user's country, language, and currency from the Steam billing servers. You can use this data to adjust your pricing as needed.
   
2. Your purchasing server then initiates a payment transaction on behalf of the client to the Steam web service. The request is a secure HTTP POST. The contents of this request include the user's metadata and a description and cost of each item that the user wishes to purchase.
   
3. Upon receiving this request, Steam will automatically activate the Steam overlay and present a dialog to the user listing all of the items, their cost and a button to confirm or authorize the transaction. If the user does not have enough funds in their Steam account, the overlay will guide the user through a funding process. The Steam overlay handles collecting all of the user's billing information. Upon completion, the user will receive a notification that the purchase was either authorized or denied. Your game should register to receive a callback for this notification and forward the result to your purchasing server.
   
4. Your purchasing server receives the notification and posts a FinalizeTransaction call to Steam to complete the operation. A successful response will result in the user being charged and you can then grant the item to the user.

Alternatively, for games whose purchasing options are typically serviced through a web page or if you wish to offer Steam as a payment method directly on your web site, you can optionally do a browser-based integration. For this solution the purchase process occurs in the following sequence:

1. User wishes to buy something in-game or on your web site. If in-game, you would launch a browser to your web page.
   
2. Your purchasing server initiates a web transaction on behalf of the user in the form of a secure HTTP POST. If successful, it will return a unique Steam URL that you can then redirect the user's browser session to and they can authorize the transaction. When you redirect, you will also specify a return URL where the user will be sent back to after they complete authorization.
   
3. When the user is directed back to your site, your purchasing server requests status about the transaction and if it's been successfully authorized, you can capture funds with a FinalizeTransaction call to Steam.

Setting up a connection

Pre-Conditions

First create a WebAPI publisher key. Instructions can be found on the Authentication using Web API Keys documentation page. This key is passed with all web server requests and is used to authenticate server requests. This should be sent as a key=<your key here> parameter with the requests.

Store the order

Store each order for later reference in your system. Use a unique 64-bit Order ID to reference the transactions within Steam.

Submitting requests

All requests should be sent using HTTP 1.1 GET or POST using a TLS secure connection. The Content-Type should be "application/x-www-form-urlencoded" and the POST parameters should be in the body of the request in standard form urlencoding format. Text should be transmitted as UTF-8.

Requests will go through the base URI:
https://partner.steam-api.com/ISteamMicroTxn/*

Some commands return a pass or fail result. For cases where a fail result is returned, an additional error code and description will be appended. These keys will not be present for a pass response.

Responses will be returned in JSON format by default. You may optionally specify XML format by adding the "format=xml" parameter to the request.
Note: You must implement a flexible JSON or XML solution that allows parameter keys to be posted and returned in arbitrary order.

Testing

Steam offers a developer sandbox to test your integration. The sandbox supports all requests available through the regular API but no actual funds will be withdrawn from the tester's Steam wallet.

The sandbox is accessed through a different base URI:
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Integration Steps

In-Game Purchasing

This is for games that have an integrated store and the user experience will stay in-game.

• Step 1
  Your game needs to ship with the Steamworks API. This means including a header file, linking in a lib file, and shipping a DLL with your product. Refer to Steamworks API Overview for more details. The Steamworks API must be successfully initialized before continuing!
  
• Step 2
  The user elects to purchase one or more items within your game. Once an item (or items) has been identified, your game needs to collect some metadata about the user:
  
  • Steam ID - This 64-bit number uniquely identifies the user within the Steam system.
    
  • Country code - The ISO 3166 country code of the user indicates where the user is purchasing from. Use this to determine what price to apply for the purchase.
    
  • Currency code - The ISO 4217 currency code that the user will be charged in.
    
  • Client game language code - The ISO 639-1 language code that the Steam client game is currently running.
    
  
  The Steam ID and language can be obtained from the Steamworks API calls:
  
  • ISteamUser::GetSteamID
    
  • ISteamApps::GetCurrentGameLanguage
    
  
  To get the country and currency type for the user, use the ISteamMicroTxn/GetUserInfo web API request passing it the user's Steam ID.

  This user metadata should be bundled and sent with your regular purchasing data to your purchasing server.

• Step 3
  Your purchasing server initiates a purchase request through the Steam web service on behalf of the Steam client. Use the ISteamMicroTxn/InitTxn described later in this document. You will need to send the following data with the request:
  
  • Order ID - A unique 64-bit number that you assign for this purchase. This number is your key to the transaction. It is used to reference the transaction within the Steam system.
    
  • Steam ID - The user ID received from the Steam client in step 3.
    
  • App ID - The unique identifier of your Steam game.
    
  • Language - The ISO 639-1 language code that your item(s) are listed in.
    
  • Currency - The ISO 4217 currency code that your price(s) are listed in. If this does not match the users's currency code provided in step 2 then an automatic currency conversion will be applied at the current market rate. Steam will present the converted price to the user, in their local currency for approval. For the best customer experience it is recommended that you provide specific pricing in each currency you expect your customers to use.
    
  • A list of one or more items that the user wishes to purchase. With each item you specify the following data:
    
    • Item ID - Your own 32-bit identifier for the item.
      
    • Quantity - Number of items of this type in the transaction.
      
    • Amount - The amount (in hundredths) that you wish to charge the user for this item. Some currencies must be priced in full values, see Supported Currencies for more information. If the Quantity value for this item is greater than one, this value is the total that will get charged (Amount = Quantity x item_cost).
      
    • Item Description - A text description for the item. This will be displayed to the user when they are prompted to authorize the transaction. You can choose to localize this description based upon the Steam client's indicated language code.
      
    • Item Category - An optional text description of a category that this item should be grouped with. This value is used for grouping sales data in backend Steam reporting and is never displayed to the user.
      
  
  If the transaction is accepted by Steam, the Steam client will automatically be notified to authorize the purchase. If an error is returned then the problem will need to be corrected and a new purchase transaction submitted.
  
• Step 4
  A successful ISteamMicroTxn/InitTxn attempt will result in the user receiving a notification via the Steam in-game overlay that the transaction needs to be authorized. Details of the transaction are displayed using the item descriptions supplied by your purchase request. The user can then authorize the transaction. If the user does not have sufficient funds in their account, Steam will automatically guide them through a funding process. At the end, your game will receive notification that the transaction has either been authorized or denied.

  Your game will need to register a ISteamUser::MicroTxnAuthorizationResponse_t callback handler to receive notification of the approval (or denial) event. This callback result contains the AppID, OrderID, and authorization state of the transaction. Your game can send this result to your purchasing server so it can know to finalize the transaction. Refer to the Callbacks documentation for more details.

• Step 5
  Your purchasing server uses the ISteamMicroTxn/FinalizeTxn API command to complete the transaction with the following parameters:
  
  • Order ID - The order ID you created to initiate the transaction.
    
  • App ID - The unique identifier of your Steam game.
    
  
  A successful response means that the purchase has been accepted and the items should be granted. An error response indicates that the purchase did not complete properly and an appropriate error message is given.
  
• Step 6
  Your purchasing server will need to regularly call the ISteamMicroTxn/GetReport API to receive notifaction about changes in the settlement status of transactions. You should be calling this API at least once daily to reconcile settlement updates, but it isn't unreasonable to call this API as often as every minute to ensure that your servers stay current with transaction updates.

  At your discretion, you are able to refund customer transactions using the ISteamMicroTxn/RefundTxn API. However, there are other ways that transactions can be reversed that likely require your attention. When a transaction enters a reversed state (e.g., Refunded, PartialRefund, Chargedback, RefundedSuspsectedFraud, or RefundedFriendlyFraud - see: Appendix A: Status Values) then your backend should attempt to claw-back items associated with the reversed transaction if at all possible. Please review our documentaion on Anticpating Fraud and ensure that you've taken steps to prevent the most common types of fraud.

Web-based Purchasing

If your game store is a web page or you just want to add Steam as a payment method to your existing store checkout, you can use the following steps for integration:

• Step 1
  Get the user's Steam ID.
  
  • If the user is currently in-game, use the Steamworks API to return the Steam ID: ISteamUser::GetSteamID.
    
  • If the user is at your website you can use the Steamworks OpenID API to securely retrieve the user's Steam ID. Details for OpenID can be found on the Steamworks Web Browser based authentication with OpenID documentation page.
    
  
  Note: We recommend that you link the user's game account with their Steam ID so that the user only has to do this secondary login one time.
  
• Step 2
  Get the country and currency type for the user by calling the ISteamMicroTxn/GetUserInfo web API request passing it the user's Steam ID. This data can be used to display your store with appropriate pricing and currency values for the user.

  Note: GetUserInfo has an optional IP address parameter that you can use to hint to Steam where the user is originating from. Send the public IP address of the user for all web-based purchases or any time the user is not actively logged in through the Steam client and playing your game.

• Step 3
  Your purchasing server initiates a purchase request through the Steam web service using the ISteamMicroTxn/InitTxn. Two additional pieces of data will need to be supplied beyond what is needed for regular in-game purchasing:
  
  • usersession - This should be set to "web" indicating the user will be authenticating the transaction through a browser.
    
  • ipaddress - The public IP address of the user.
    
  
  When usersession is set to WEB, the InitTxn request will return an additional steamurl parameter. This is a unique URL that you can redirect the user's web session to and identifies the transaction created by this API call.
• Step 4
  Your purchasing server redirects the user's web session to the Steam URL returned in the InitTxn API call. Along with the redirect, append your own URL which will be where the user is returned to after the transaction is authorized (or declined). Use a fully specified URL (e.g. http://www.steamgames.com) in the form of
  returnurl=your_URL_here
  When a user is redirected to the Steam URL, they will need to log into Steam before authenticating. If the user is selecting Steam as a payment method on your web site this would be expected behavior from the user's point of view. If however, the user was already logged into Steam and playing your game, it would be desirable to skip this second login requirement. This can be accomplished by using the built-in web browser capability of the game overlay. When the game overlay browser is used for authorization, the user will be logged in automatically. To launch the browser use the Steamworks API call
  ISteamFriends::ActivateGameOverlayToWebPage

  Full details on using the game overlay can be found here.

• Step 5
  When the user returns to your site, issue an ISteamMicroTxn/QueryTxn API call to get the results. If the order status is "Approved" then capture funds with the ISteamMicroTxn/FinalizeTxn API call. Abandon the transaction if any other status returns.

  Note: If the user closes their browser or something happens that otherwise prevents their return to your site, abandon the transaction and do not issue a FinalizeTxn call. Even if the user approved the transaction and somehow did not get redirected back, abandon it and start again.

• Step 6
  Your purchasing server will need to regularly call the ISteamMicroTxn/GetReport API to receive notifaction about changes in the settlement status of transactions. You should be calling this API at least once daily to reconcile settlement updates, but it isn't unreasonable to call this API as often as every minute to ensure that your servers stay current with transaction updates.

  At your discretion, you are able to refund customer transactions using the ISteamMicroTxn/RefundTxn API. However, there are other ways that transactions can be reversed that likely require your attention. When a transaction enters a reversed state (e.g., Refunded, PartialRefund, Chargedback, RefundedSuspsectedFraud, or RefundedFriendlyFraud - see: Appendix A: Status Values) then your backend should attempt to claw-back items associated with the reversed transaction if at all possible. Please review our documentaion on Anticpating Fraud and ensure that you've taken steps to prevent the most common types of fraud.

Appendix A: Status Values

These are the possible status values returned by the ISteamMicroTxn Web API. The response key that carries these values is usually called status.

• Init - Order has been created but not authorized by user.
  
• Approved - Order has been approved by user.
  
• Succeeded - Order has been successfully processed.
  
• Failed - Order has failed or been denied.
  
• Refunded - Order has been refunded and product should be revoked by the game. A refund may be initiated by the customer.
  
• PartialRefund - One or more items in the cart have been refunded. Check itemstatus field of each item for details.
  
• Chargedback - Order is fraudulent or disputed and product should be revoked by the game.
  
• RefundedSuspectedFraud - Order was refunded by Valve because it was suspected to be fraud. Product should be revoked by the game.
  
• RefundedFriendlyFraud - Order was refunded by Valve because it was determined to be friendly fraud. Product should be revoked by the game.

Appendix B: Error Codes

These are the possible error codes returned by the ISteamMicroTxn Web API. The response key that carries these values is usually errorcode.

• 1 - Success
  
• 2 - The operation failed
  
• 3 - Invalid parameter
  
• 4 - Internal error
  
• 5 - User has not approved transaction
  
• 6 - Transaction has already been committed
  
• 7 - User is not logged in
  
• 8 - Currency does not match user's Steam Account currency
  
• 9 - Account does not exist or is temporarily unavailable
  
• 10 - Transaction has been denied by user
  
• 11 - Transaction has been denied because user is in a restricted country
  
• 12 - Transaction has been denied because billing agreement is not active
  
• 13 - Billing agreement cannot be processed because it is not type GAME
  
• 14 - Billing agreement is on hold due to billing dispute or chargeback
  
• 15 - Billing agreement cannot be processed because it is not type STEAM
  
• 16 - User already has a billing agreement for this game
  
• 100 - Insufficient funds
  
• 101 - Time limit for finalization has been exceeded
  
• 102 - Account is disabled
  
• 103 - Account is not allowed to purchase
  
• 104 - Transaction denied due to fraud detection
  
• 105 - No cached payment method
  
• 106 - Transaction would exceed the spending limit of the billing agreement
  
• 107 - User has a pending transaction that must be completed before beginning a new transaction

More Questions?

Ask questions on the In-Game Purchasing Integration discussion board.