Steamworks Documentation
ISteamMicroTxn Interface
This is the interface used to support Microtransactions (In-Game Purchases).

See the Microtransactions Implementation Guide for more details.
NOTE: Use ISteamMicroTxnSandbox while testing!

For more info on how to use the Steamworks Web API please see the Web API Overview.

AdjustAgreement

POST https://partner.steam-api.com/ISteamMicroTxn/AdjustAgreement/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
steamiduint64Steam ID of the client that is adjusting the agreement.
agreementiduint64Unique 64-bit Steam billing agreement ID.
appiduint32App ID of the game the agreement is for.
nextprocessdatestringDate that next recurring payment should be initiated. Format is YYYYMMDD.
Date can only be adjusted forward indicating you want to add time to the subscription. If the date exceeds the end date of the subscription, the end date will be extended.
oldnextprocessdatestringOptional paramter that is the last known next recurring payment date that should be checked against. Format is YYYYMMDD.
If this parameter is provided, the API will verify that the current next recurring date has not changed before attempting to adjust the agreement next process changes to the agreement.

Add time to the payment schedule of an agreement with billing type "steam". The agreementid can be retrieved using GetUserAgreementInfo.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • agreementid - Unique 64-bit Steam billing agreement ID.
      • nextprocessdate - The date that the next recurring payment will be initiated. Format is YYYYMMDD.
    • error - Optional, only returned if result is Failure.

CancelAgreement

POST https://partner.steam-api.com/ISteamMicroTxn/CancelAgreement/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
steamiduint64Steam ID of the client that is canceling the agreement.
agreementiduint64Unique 64-bit Steam billing agreement ID.
appiduint32App ID of the game the agreement is for.

Cancels a recurring billing agreement (subscription). The agreementid can be retrieved using GetUserAgreementInfo.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • agreementid - Unique 64-bit Steam billing agreement ID.
    • error - Optional, only returned if result is Failure.

FinalizeTxn

POST https://partner.steam-api.com/ISteamMicroTxn/FinalizeTxn/v2/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
orderiduint64Unique 64-bit ID for order
appiduint32App ID for game.

Completes a purchase that was started by the InitTxn API.

This command will capture funds for a transaction and should only be called after the user has authorized the transaction and you have received notification that the authorization was successful. Notification of authorization comes either through the Steam client (your game registers to receive notification) or through the user being redirected back to your web site (return URL specified when you redirect a user's web session to Steam). The usersession value specified in InitTxn determines the notification mechanism.

A successful response to this command means payment has been completed and you can safely grant items to the user. In the event of a timeout or some other communication error, use either the QueryTxn or GetReport APIs to get status on the transaction.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:
  • Version 2 - Changed to string formatted 64 bit numbers.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • orderid - Unique 64-bit ID for order.
      • transid - Unique 64-bit Steam transaction ID.
    • error - Optional, only returned if result is Failure.

Example Response:
<response> <result>OK</result> <params> <orderid>938473</orderid> <transid>374839</transid> </params> </response>

GetReport

GET https://partner.steam-api.com/ISteamMicroTxn/GetReport/v5/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32App ID of game to get reports for.
typestringReport type (One of: "GAMESALES", "STEAMSTORESALES", "SETTLEMENT", "CHARGEBACK")
timestringStart time of the report. (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)
maxresultsuint32Maximum number of results to return in report. (Default is 1000 if no value is set) Note that the number of results returned might be less than maxresults, even when they are more results

Steam offers transaction reports that can be downloaded for reconciliation purposes. These reports show detailed information about each transaction that affects the settlement of funds into your accounts.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

NOTE: This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version. Change history:
  • Version 2 - Changed result to returns arrays.
  • Version 3 - Changed to string formatted 64 bit numbers.
  • Version 4 - Added storepurchasereference section to return sales information for DLCs sold on the store that reference in-game microtransaction items.
  • Version 5 - Added new status values to for transactions to reflect suspected fraud or friendly fraud.

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • timecreated - Time of transaction (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)
      • orderid - Unique 64-bit ID for order. (This will be 0 for recurring subscriptions initiated from the Steam store, use transid instead.)
      • transid - Unique 64-bit Steam transaction ID.
      • steamid - The Steam ID of user that the order/transaction belongs to.
      • status - Status of the order. See: Appendix A: Status Values
      • currency - ISO 4217 currency code.
      • time - Time of the most recent update to the transaction. (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)
      • country - ISO 3166-1-alpha-2 country code.
      • usstate - US State. Empty for non-US countries.
    • items
      • itemid - Game ID number of item.
      • qty - Quantity of this item.
      • amount - Total cost to user minus VAT (in cents). (199 = 1.99)
      • vat - Total VAT or tax (in cents). (19 = .19)
      • itemstatus - Status of items within the order.
      • storepurchasereference - Optional, only returned if the purchase was via a DLC on the store that is connected to an in-game microtransaction item id.
        • packageid - The DLC package that was purchased on the store.
        • bundleid - The bundle id associated with the DLC package, if applicable.
        • referenceid - The steam generated line item referenceid associated with the package.
        • amount - The price paid by the user.
        • vat - VAT taxes if applicable for the purchase.
        • currency - The currency that was used to make the purchase.
    • error - Optional, only returned if result is Failure.

Example Response:
{ "response": { "result": "OK", "params": { "count": 4, "orders": [ { "orderid": "1233", "transid": "1234567890123456788", "steamid": "76561197972751825", "status": "PartialRefund", "currency": "USD", "time": "2024-01-23T18:30:00Z", "country": "US", "usstate": "WA", "timecreated": "2024-01-23T18:15:00Z", "items": [ { "itemid": 100, "qty": 1, "amount": 99, "vat": 9, "itemstatus": "Refunded" }, { "itemid": 101, "qty": 1, "amount": 1299, "vat": 116, "itemstatus": "Succeeded" } ] }, { "orderid": "1234", "transid": "1234567890123456789", "steamid": "76561197972751825", "status": "Failed", "currency": "USD", "time": "2024-01-23T18:40:30Z", "country": "US", "usstate": "WA", "timecreated": "2024-01-23T18:39:00Z", "items": [ { "itemid": 100, "qty": 1, "amount": 99, "vat": 9, "itemstatus": "Failed" } ] }, { "orderid": "1235", "transid": "1234567890123456790", "steamid": "76561197972751825", "status": "Succeeded", "currency": "USD", "time": "2024-01-23T18:40:40Z", "country": "US", "usstate": "WA", "timecreated": "2024-01-23T18:39:30Z", "items": [ { "itemid": 101, "qty": 1, "amount": 1299, "vat": 116, "itemstatus": "Succeeded" } ] }, { "orderid": "1236", "transid": "1234567890123456791", "steamid": "76561197972751825", "status": "Chargedback", "currency": "USD", "time": "2024-01-23T19:55:00Z", "country": "US", "usstate": "WA", "timecreated": "2024-01-23T18:40:00Z", "items": [ { "itemid": 102, "qty": 1, "amount": 999, "vat": 89, "itemstatus": "Chargedback" } ] } ] } } }

GetUserAgreementInfo

GET https://partner.steam-api.com/ISteamMicroTxn/GetUserAgreementInfo/v2/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
steamiduint64Steam ID of the client.
appiduint32App ID of the game the agreement is for.

Get detailed information of all recurring billing agreements (subscriptions) for a user.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Version 2 - The status value can be "processing" in the case where Steam has not yet charged the user for the agreement. Previously the status value would be "active"

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • agreements
        • agreement
          • agreementid - Unique 64-bit Steam billing agreement ID.
          • itemid - Game ID number of item
          • status - Active, canceled, or processing.
          • period - Period of agreement.
          • frequency - Interval of period.
          • startdate - Date that recurring payment processing starts. Format is YYYYMMDD.
          • enddate - Date that recurring payment processing ends. Format is YYYYMMDD.
          • recurringamt - Amount to bill (in cents) at each recurring interval.
          • currency - ISO 4217 currency code of prices.
          • timecreated - Date that agreement was created in YYYYMMDD format.
          • lastpayment - Date of last successful payment in YYYYMMDD format.
          • lastamount - Amount of last successful payment in cents.
          • nextpayment - Date of next scheduled payment in YYYYMMDD format.
          • outstanding - Current outstanding balance in cents.
          • failedattempts - Number of failed billing attempts on outstanding balance.
    • error - Optional, only returned if result is Failure.

GetUserInfo

GET https://partner.steam-api.com/ISteamMicroTxn/GetUserInfo/v2/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32AppID of the game the user will make a purchase in.
steamiduint64Steam ID of user making purchase.
ipaddressstringIP address of user in string format (xxx.xxx.xxx.xxx). Only required if usersession in InitTxn was set to web.

Retrieves details for a user's purchasing info.

These details are based upon the user's Steam wallet.
For new accounts or accounts that do not yet have a Steam wallet, the information returned will be based off of the user's IP address. The IP will be taken from the user's Steam client session if they are logged in, otherwise from the ipaddress API parameter. If the user does not have a wallet, is not logged in through the Steam client, and you have not supplied an IP address, this call will return an error indicating the user is not logged in.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:
  • Version 2 - Changed to string formatted 64 bit numbers.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • state - US State. Empty for non-US countries.
      • country - ISO 3166-1-alpha-2 country code.
      • currency - ISO 4217 currency code of prices.
      • status - Status of the account. Can be:
        • Locked from purchasing - cannot make purchases
        • Active - the default account state
        • Trusted - an active account with a purchase older than 90 days without a chargeback

    • error - Optional, only returned if result is Failure.

Example Response:
<response> <result>OK</result> <params> <state>WA</state> <country>US</country> <currency>USD</currency> </params> </response>

InitTxn

POST https://partner.steam-api.com/ISteamMicroTxn/InitTxn/v3/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
orderiduint64Unique 64-bit ID for order
steamiduint64Steam ID of user making purchase.
appiduint32App ID of game this transaction is for.
itemcountuint32Number of items in cart.
languagestringISO 639-1 language code of the item descriptions. Only works with the 28 fully supported Steam languages. See supported languages
currencystringISO 4217 currency code. See Supported Currencies for proper format of each currency.
usersessionstringSession where user will authorize the transaction. Valid options are "client" or "web". If this parameter is not supplied, the interface will be assumed to be through a currently logged in Steam client session.
ipaddressstringIP address of user in string format (xxx.xxx.xxx.xxx). Only required if [param]usersession[/param] is set to web.
itemid[0]uint323rd party ID for item.
qty[0]int16Quantity of this item.
amount[0]int64Total cost (in cents) of item(s) to be charged at this time. See Supported Currencies for proper format of each amount. Note that the amount you pass needs to be in the format that matches the "currency" code you pass.
description[0]stringDescription of item. Maximum length of 128 characters.
category[0]stringOptional 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. Maximum length of 64 characters
associated_bundle[0]uint32Optional bundleid of associated bundle.
billingtype[0]stringOptional recurring billing type. Valid options are: "Steam" or "Game"
  • Steam: Steam automatically re-bills
  • Game: Partner needs to call ProcessAgreement API to bill
startdate[0]stringOptional start date for recurring billing (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z).
enddate[0]stringOptional end date for recurring billing (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z).
period[0]stringOptional period for recurring billing. Valid options are: "Day", "Week", "Month", "Year"
frequency[0]uint32Optional frequency (in number of days) for recurring billing. Supported values: 1 - 255
recurringamt[0]int64Optional amount to be billed for future recurring billing transactions.
bundlecountuint32Number of bundles in cart.
bundleid[0]uint323rd party ID of the bundle. This shares the same ID space as 3rd party items.
bundle_qty[0]uint32Quantity of this bundle.
bundle_desc[0]stringDescription of bundle. Maximum length of 128 characters.
bundle_category[0]stringOptional text description of a bundle 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. Maximum length of 64 characters.

Creates a new purchase. Send the order information along with the Steam ID to seed the transaction on Steam.

This command allows you to create a shopping cart of one or more items for a user. The cost and descriptions of these items will be displayed to the user for their approval. The purchase interface can be configured for either the Steam client or a web browser depending on if you are running a purchase in-game or from a web page.

Currency/Amount formatting

Note that certain currencies must be charged in specific increments. For example, Ukrainian Hryvnia (UAH) must be charged in increments of 100. So if you attempt to price an item at 1050 UAH, InitTxn will fail with error result k_EMicroTxnResultInvalidParam. For a full list of pricing requirements, see Supported Currencies

If you do not wish to price each transaction in the local user's currency, Steam can convert any purchase to the local user's wallet currency automatically based on current exchange rate. For example, if you pass currency as "USD" and amount as "999", a user in Russia will be charged in Rubles at the current exchange rate for $9.99, which would be about 614.90 pуб as of this writing. Please note, however, that the transaction confirmation dialog displayed to customers will show the pricing and currency that you have specified; the conversion takes place as the transaction is finalized. In the previous example, customers in Russia would see a USD $9.99 price in the confirmation dialog but would be charged 614.90 pуб when the transaction is finalized. We recommend that you provide custom pricing for each currency in which you expect your customers to transact regularly.

Note that the amount you pass needs to be in the format that matches the currency code you pass.

A successful response to this command means the transaction has been created. If the purchase interface is the Steam client, the user will automatically be presented with a dialog requesting authorization for the purchase. For a web interface, redirect the user to the steam URL returned in the response. In the event of a timeout or some other communication error, abandon the transaction and create a new one.

When a "client" user session is indicated via [param]usersession[/param] the user will be required to approve the transaction from within the game overlay on the client. Web sessions will require the user to be logged into Steam via a browser where the transaction will be presented and an approval option displayed.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:
  • Version 2 - Changed to string formatted 64 bit numbers.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:
  • Version 3 - Enforced quantity amounts to be a 16 bit number.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • orderid - Unique 64-bit ID for order.
      • transid - Unique 64-bit Steam transaction ID.
      • steamurl - Optional URL returned when the usersession input is set to web. This URL can be used to redirect the user's web session to Steam so that the user can approve the transaction.
      • agreements - Optional list of agreements when the billing type is recurring.
    • error - Optional, only returned if result is Failure.

Example Response:
<response> <result>OK</result> <params> <orderid>938473</orderid> <transid>374839</transid> </params> </response> <response> <result>Failure</result> <params> <orderid>938474</orderid> </params> <error> <errorcode>1001</errorcode> <errordesc>Action not allowed</errordesc> </error> </response>

ProcessAgreement

POST https://partner.steam-api.com/ISteamMicroTxn/ProcessAgreement/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
orderiduint64Unique 64-bit ID for order. If the recurring subscription was initiated from the Steam store, then this field will be 0.
steamiduint64Steam ID of the client.
agreementiduint64Unique 64-bit Steam billing agreement ID.
appiduint32App ID of the game the agreement is for.
amountint32Total cost (in cents).

This value corresponds to an initial one-time amount to be immediately charged to a user.
currencystringISO 4217 currency code of prices

Initiate a recurring payment (subscription) for the user.

A successful response means that Steam will initiate a billing cycle for the user. It does not mean that the actual billing cycle was completed successfully. Use the GetReport or GetUserAgreementInfo APIs to check actual billing status.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • orderid - Unique 64-bit ID for order.
      • transid - Unique 64-bit Steam transaction ID.
      • agreementid - Unique 64-bit Steam billing agreement ID.
    • error - Optional, only returned if result is Failure.

QueryTxn

GET https://partner.steam-api.com/ISteamMicroTxn/QueryTxn/v3/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32App ID of game this transaction is for.
orderiduint64Unique 64-bit ID for order.
transiduint64Unique 64-bit Steam transaction ID.

Query the status of an order that was previously created with InitTxn.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:
  • Version 2 - Changed to string formatted 64 bit numbers.
  • Version 3 - Added new status values to for transactions to reflect suspected fraud or friendly fraud.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • orderid - Unique 64-bit ID for order.
      • transid - Unique 64-bit Steam transaction ID.
      • steamid - The Steam ID of user that the order/transaction belongs to.
      • status - Status of the order. See: Appendix A: Status Values
      • currency - ISO 4217 currency code.
      • time - Time of transaction (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)
      • country - ISO 3166-1-alpha-2 country code.
      • usstate - US State. Empty for non-US countries.

      • items
        • itemid - Game ID number of item.
        • qty - Quantity of this item.
        • amount - Total cost to user minus VAT (in cents). (199 = 1.99)
        • vat - Total VAT or tax (in cents). (19 = .19)
        • itemstatus - Status of items within the order.
    • error - Optional, only returned if result is Failure.

Example Response:
<response> <result>OK</result> <params> <orderid>938474</orderid> <transid>374839</transid> <steamid>48392063</steamid> <status>Succeeded</status> <currency>GBP</currency> <time>2010-01-01T00:23:45Z</time> <items> <item> <itemid>12345</itemid> <qty>1</qty> <amount>199</amount> <vat>38</vat> <itemstatus>Succeeded</itemstatus> </item> <item> <itemid>12345</itemid> <qty>1</qty> <amount>199</amount> <vat>38</vat> <itemstatus>Succeeded</itemstatus> </item> </items> </params> </response>

RefundTxn

POST https://partner.steam-api.com/ISteamMicroTxn/RefundTxn/v2/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
orderiduint64Unique 64-bit ID for order to refund.
appiduint32App ID of the game.

Tells Steam to refund a user for a purchase. Refunds can only be made for the full value of the original order.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:
  • Version 2 - Changed to string formatted 64 bit numbers.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • result - Result of the operation. (OK or Failure)
    • params
      • orderid - Unique 64-bit ID for order.
      • transid - Unique 64-bit Steam transaction ID.
    • error - Optional, only returned if result is Failure.

Example Response:
<response> <result>OK</result> <params> <orderid>938474</orderid> <transid>374839</transid> </params> </response>