Unaffiliated

Home Documentation & Help
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.

Add time to the payment schedule of an agreement with billing type "steam".

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

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

GetReport

GET https://partner.steam-api.com/ISteamMicroTxn/GetReport/v3/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32App ID of game to get reports for.
typestringReport type (One of: "GAMESALES", "STEAMSTORE", "SETTLEMENT")
timestringStart time of the report. (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)
maxresultsuint32Maximum number of results to return in report. (Up to 1000)

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.

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.

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 - 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
      • time - 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 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> <count>2</count> <orders> <order> <orderid>938473</orderid> <transid>374839</transid> <steamid>48392048</steamid> <status>PartialRefund</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>Refunded</itemstatus> </item> <item> <itemid>12345</itemid> <qty>1</qty> <amount>199</amount> <vat>38</vat> <itemstatus>Succeeded</itemstatus> </item> </items> </order> <order> <orderid>938474</orderid> <transid>374840</transid> <steamid>48392063</steamid> <status>Succeeded</status> <currency>USD</currency> <time>2010-01-01T00:23:52Z</time> <items> <item> <itemid>12345</itemid> <qty>1</qty> <amount>199</amount> <vat>0</vat> <itemstatus>Succeeded</itemstatus> </item> </items> </order> </orders> </params> </response>

GetUserAgreementInfo

GET https://partner.steam-api.com/ISteamMicroTxn/GetUserAgreementInfo/v1/
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!

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 or canceled.
          • 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.
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 either Active or Trusted. Trusted accounts have a have a known, good purchase history within Steam. Use this flag to relax your own fraud checking as appropriate.
    • 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.
currencystringISO 4217 currency code.
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]uint32Quantity of this item.
amount[0]int32Total cost (in cents) of item(s).
description[0]stringDescription of item.
category[0]stringOptional category grouping for item.
associated_bundle[0]uint32Optional bundleid of associated bundle.
billingtype[0]stringOptional recurring billing type.
startdate[0]stringOptional start date for recurring billing.
enddate[0]stringOptional end date for recurring billing.
period[0]stringOptional period for recurring billing.
frequency[0]uint32Optional frequency for recurring billing.
recurringamt[0]stringOptional recurring billing amount.
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.
bundle_category[0]stringOptional category grouping for bundle.

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.

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.
    • 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/v2/
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.

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>938473</orderid> <transid>374839</transid> </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>