Offers and purchases

An offer is something a player can buy to fund the servers. A purchase is one player buying it.

The Encore key

Every Encore has an encore_key — ek-01j9… — and it is the only thing your game needs to ship.

It is not a credential. It is in every copy of the game, and treat it that way: what it unlocks is reading the servers' public funding and starting a purchase, and anybody who owns the game may do both. It names no account, no project and no studio. The player is proven separately, by Steam, on every purchase.

Encore → your Encore → Integration → Encore key

Offers

Encore → your Encore → Offers → New offer → name, price and credit → Create offer

Why the credit is capped

Steam pays you the price less its share, and you owe Plany the credit. A credit above the net would leave you owing more than you received on every sale, so it is refused:

Crediting less than the most is allowed, and is how a studio covers its own costs or support. The gap is yours.

Changing and removing an offer

• UpdateOffer (plany encore offers update) takes display_name, description, price, credit and active. Price and credit are checked together.
• A price change applies to purchases begun afterwards. An order already open with Steam settles at the price and credit it was opened at.
• DeleteOffer (plany encore offers delete) removes an offer nobody has bought. One with purchases is deactivated instead, because a purchase has to keep naming what was bought. Its id cannot be reused afterwards.

A game lists only active offers, and lists them even before the Encore is verified — with purchasable: false — so you can build and test the store before anybody can buy.

A purchase, step by step

1. The game asks Steam for a ticket

   ISteamUser::GetAuthTicketForWebApi("plany-encore"). The identity must be exactly plany-encore; a ticket minted for anything else is refused.

2. The game calls BeginPurchase

   With the Encore key, the offer id, the ticket and a fresh request id. Plany has Steam confirm the player with your key — so a ticket for another game proves nothing here — records the purchase, reserves its credit against your outstanding limit, and only then opens the order with Steam.

3. The Steam overlay appears

   Opened by Steam's servers, not by the game. The player approves or declines, and Steam delivers MicroTxnAuthorizationResponse_t to the game.

4. The game calls CompletePurchase

   With what the overlay said. Plany asks Steam where the order stands, settles an approved one, and credits the project only once Steam reports it settled.

The price, the credit and the project are never taken from any request. A game cannot say what the player paid; it can only say which offer they chose.

A crashed game still credits

CompletePurchase is safe to call more than once, and safe not to call at all. Plany asks Steam about any order that has not moved for two minutes and settles it on its own, so a game that crashes between the player approving and calling CompletePurchase still funds the servers — usually within a couple of minutes.

A decline reported by the game is never believed on its own: Plany confirms it with Steam before cancelling. An order nobody ever answers is cancelled after an hour and its reservation released.

States

A sandbox purchase passes through the same states and credits nothing. It carries sandbox: true.

Making a retry safe: request_id

Send a fresh random id — a UUID — with every purchase attempt, and reuse it only when retrying that same attempt:

• A second call with the same id, for the same Encore and the same player, returns the purchase the first call opened. No second order.
• The same id from a different player is refused with ALREADY_EXISTS (HTTP 409). A game client chooses the id, and handing one player another's open order would disclose it.
• A retry of an attempt whose order never opened gets the refusal again rather than the purchase, so a game does not wait for an overlay that is never coming.
• At most 128 characters.

The player pressing the button again is a new attempt and a new id. The SDKs do all of this for you.

Refusals

Every refusal of a purchase happens before the player is charged. A named refusal carries its reason twice — as a google.rpc.ErrorInfo reason (domain encore.plany.cloud) and, for the 400s, as a google.rpc.PreconditionFailure violation type — so a client in any language can switch on it.

And the unnamed ones:

None of the named refusals improves by retrying in the next few seconds.

Refunds and chargebacks

Steam refunds happen on Steam's side, sometimes days later. Plany reads each link's Steam order report every six hours:

• A refunded or charged-back order that was credited has its credit taken back out of the project — in proportion when Steam itemises a partial refund, and in full otherwise — and becomes STATE_REVERSED. The project's ledger shows a refund, or a reversal for a chargeback.
• An order reversed before it was credited becomes STATE_FAILED and credits nothing.
• The project's balance can go negative. The credit may already have paid for hosting that genuinely ran. A negative balance keeps the servers asleep until it is topped up past zero.
• What you owe Plany on the link falls by the amount taken back.

Orders your game sold some other way, through its own backend, appear in the same Steam report and are ignored.

Reading purchases

Encore → your Encore → Funding → Purchases

Newest first. Each carries the offer, Steam's order_id, the player's SteamID64 in player_id, the price and credit, the state and its message, and the times it was credited or reversed.

roles/account.owner, roles/account.admin, roles/account.billing and roles/account.viewer can all read purchases. Creating and changing offers is owner and administrator.