Overview
Note: This document is intended to be used as a supplement to the base in-game MTX purchasing document. The APIs described here are extensions to that API.
To create a recurring subscription for a Steam user, you first need to establish a billing agreement with the user, which describes the payment terms. These terms include the recurring price, and at what frequency that price is billed to the user. The user must agree to these terms before the recurring subscription can begin. Payment process is then handled by Steam, which can send results back to the game's own server.
Establishing a Billing Agreement
Similar to selling a microtransaction item, to create a billing agreement, your backend server will need to call the WebAPI
ISteamMicroTxn/InitTxn. The call to InitTxn will then require some additional parameters to fully define it. If the transaction is accepted by Steam, the user will be notified to authorize the agreement and the API will return a unique 64-bit billing agreementID in the response. If an error is returned then the problem will need to be corrected and a new request submitted. Once approved, you should use the
ISteamMicroTxn/FinalizeTxn WebAPI to complete the agreement.
The additional parameters needed for InitTxn are:
- billingtype[0] - Valid options are: "Steam" or "Game". Using "Steam" is the preferred method
- period[0] - Period for recurring billing. Valid options are: "Day", "Week", "Month", "Year"
- frequency[0] - Frequency (in number of days) for recurring billing. Supported values: 1 - 255
- recurringamt[0] - Amount to be billed for future recurring billing transactions.
A user may only have one active billing agreement per game. You may create a new billing agreement for a user at any time, but all previous billing agreements will be disabled upon completing a
ISteamMicroTxn/FinalizeTxn call. Each billing agreement will be given a unique 64-bit ID that you can use to reference it, but only the most recent agreement will be allowed to process payment.
Users can elect to cancel an agreement at any time from within their Steam account settings. Notification of cancellations will be done through the
ISteamMicroTxn/GetReport Web API.
If your billing agreement is set to the "Game" type, then your backend server will need to the WebAPI
ISteamMicroTxn/ProcessAgreement to charge the user on each recurring event. This is only useful if you have a system where the user may be charged less than the initial or recurring amount, as the call to ProcessAgreement will take an amount value to charge the user.
Receiving Status
To receive payment status for a billing agreement, your game server should call the WebAPI
ISteamMicroTxn/GetReport. GetReport will show all transactions associated with your game (appID), including those produced by a billing agreement. Additionally, since users can cancel and renew subscriptions from within their Steam account, the game can receive notification of those actions through this API. Your game server should call GetReport frequently, at least every couple of seconds, so that it can always be up-to-date.
Additional Web APIs for recurring payments are:
