Steam Payments

Why INVO needs a payment method on file

On every other rail, the player pays INVO and INVO issues the currency out of money it is holding. On Steam it is the other way round: Steam pays you, and INVO issues the currency anyway. It does so immediately, so the player gets what they bought. INVO is then owed the money behind it.

So INVO settles with you afterwards. Charges are batched, not per transaction, and every one of them is itemised in your dashboard against the purchases that produced it.

You are passing through money you received on INVO's behalf. It is not a commission or a platform fee. Your own revenue share on what players spend is unchanged. A bank account costs materially less to settle than a card and is worth using if you can.

Setting it up

1. In Steamworks: make sure your app is on your partner account and in-game purchases (microtransactions) are enabled for it.
2. In Steamworks: create a publisher Web API key, a publisher-group key, not a personal user key. The group must include the app. A personal key will fail verification.
3. In the INVO dashboard: accept the billing authorisation and add a payment method.
4. In the INVO dashboard: under the title's Steam settings, enter the app id and the publisher Web API key. INVO calls Steam to confirm the key controls that app before saving it, so you find out immediately if the pair is wrong.
5. Ask INVO to enable the Steam rail for the title.

Until every step is done, purchases are refused before the player is charged, with STEAM_NOT_CONFIGURED or PARTNER_BILLING_NOT_SET_UP. That is deliberate: the alternative is taking a player's money for currency that cannot be issued.

How it works

Steam splits a micro-transaction into two phases. First the player authorizes the charge in the Steam client. Then the merchant captures it. INVO drives both phases and credits the player's branded currency the moment the charge is captured, the same credit-on-capture model as card purchases.

Three parties are involved: your game (client + backend), INVO, and Steam. Your game backend makes two server-to-server calls to INVO; your game client handles one Steam SDK callback in between. The handshake:

Step 1: Initialize the purchase (backend)

When the player picks a currency pack, your backend calls INVO. You pass the player's 64-bit steamid (your game client already has it from the Steamworks SDK and forwards it to your backend) and the pack_id the player chose. Never an amount: INVO owns the price.

POST https://invo.network/api/currency-purchases/steam/init-purchase
Headers:
  X-Game-Secret-Key: ivsdk_<your_sdk_key>
  Content-Type: application/json

Body:
{
  "player_email":       "player@example.com",
  "steamid":            "76561198000000000",
  "pack_id":            "steam_medium",
  "purchase_reference": "<uuid_v4>",
  "player_name":        "PlayerOne",
  "usersession":        "client",             // or "web"; see Browser checkout below
  "player_ip":          "203.0.113.7",        // REQUIRED when usersession is "web"
  "metadata":           { "my_player_id": "p_123" }   // echoed on the webhook
}

Response 200:
{
  "status":             "pending_authorization",
  "order_id":           "ord_a1b2c3...",
  "steam_transid":      "350000123456789",
  "steam_checkout_url": null,                 // set ONLY for usersession "web"
  "pack_id":            "steam_medium",
  "charged_usd":        "9.99",
  "currency_amount":    "69",
  "new_balance":        null
}

• player_email (required): identifies the INVO player whose branded-currency balance is credited. A player row is created on first purchase if it doesn't exist.
• steamid (required): the 64-bit Steam ID of the account paying. Steam shows the authorization overlay to this account. Must be numeric.
• pack_id (required): which INVO pack the player is buying. You do not send a price. INVO sets Steam pricing for every title on the network; fetch the packs from GET /steam/packs and pass the pack_id back. An unknown id returns 400 UNKNOWN_STEAM_PACK with the valid ids.
• purchase_reference (required): your idempotency key (UUID v4 recommended, max 255 chars). Replaying the same value returns the existing order (409, duplicate) instead of creating a second charge, so it is safe to retry on a network failure. Omitting it returns 400 MISSING_PURCHASE_REFERENCE; sending one longer than 255 chars returns 400 INVALID_PURCHASE_REFERENCE. The field client_request_id is accepted as an alias for backward compatibility.
• player_name (optional): display name; falls back to the local-part of the email if omitted on first purchase.
• usersession (optional, default client): how the player will authorize. client: Steam's in-game overlay; your client receives the Steamworks callback. web: Steam returns steam_checkout_url, its own hosted approval page, for platforms where the overlay does not render (some embedded browser builds). See Browser checkout.
• player_ip (required when usersession is web): the player's IP address as your server sees it, never your server's own. Steam runs fraud and geolocation checks against it. Omitting it returns 400 MISSING_PLAYER_IP.
• metadata (optional, JSON object ≤ 8 KB): echoed at data.metadata on the purchase.completed webhook. On the Steam rail INVO merges four context keys of its own into the echoed object (steam_wallet_currency, steam_country, steam_account_status, vat_rate_pct). Avoid those names in yours, and don't assume the object contains only your keys. This is the only correlation channel: purchase_reference is an idempotency key and is deliberately not in the webhook payload, so put your own player / order ids here if your webhook handler needs to attribute the credit.
• charged_usd (response): what Steam bills the player. The same for every player; it is the pack's price.
• currency_amount (response): the branded currency this player receives. This varies by country. See below.
• order_id (response): keep this. Your game client passes it back to your backend for Step 3.

As soon as init-purchase succeeds, Steam presents its purchase dialog to the player inside the Steam overlay. You do not trigger any UI yourself.

GET /steam/packs?steamid=76561198000000000
X-Game-Secret-Key: ivsdk_<your_sdk_key>     // server-side only; packs authenticates too

{
  "status": "ok",
  "country": "FR",
  "vat_rate_pct": "20.0",
  "packs": [
    { "pack_id": "steam_small",  "label": "Small",  "price_usd": "4.99",  "currency_amount": "29"  },
    { "pack_id": "steam_medium", "label": "Medium", "price_usd": "9.99",  "currency_amount": "58"  },
    { "pack_id": "steam_large",  "label": "Large",  "price_usd": "19.99", "currency_amount": "116" }
    // ...excerpt; the live catalogue has more packs; render what it returns
  ]
}

Step 2: The player authorizes (game client)

Steam delivers the player's decision to your game client through the Steamworks SDK callback MicroTxnAuthorizationResponse_t. The callback carries m_bAuthorized (1 if the player approved), m_unAppID, and m_ulOrderID. That last one is Steam's numeric order id, which the init response does not return, so don't plan to correlate on it: track your own pending purchase (the order_id you got from init) and finalize that. When the player approves, tell your backend to run Step 3. INVO never sees this callback; it is strictly between Steam and your game client.

Unity (C#, Steamworks.NET)

using Steamworks;
using UnityEngine;

public class InvoSteamPurchase : MonoBehaviour
{
    private Callback<MicroTxnAuthorizationResponse_t> _authCallback;
    private string _pendingOrderId;

    void Start()
    {
        // Register the Steam authorization callback once.
        _authCallback = Callback<MicroTxnAuthorizationResponse_t>.Create(OnSteamAuthorized);
    }

    // Called when the player taps "Buy" on a currency pack. The pack list
    // came from YOUR backend, which fetched GET /steam/packs for this player.
    public async void BuyCurrency(string packId)
    {
        ulong steamId = SteamUser.GetSteamID().m_SteamID;

        // Ask YOUR backend to start the purchase. Your backend calls INVO's
        // /steam/init-purchase with your X-Game-Secret-Key (never in the
        // client). You send a pack_id, never a price; INVO owns the price.
        var result = await MyGameBackend.StartSteamPurchase(packId, steamId);
        _pendingOrderId = result.OrderId;   // INVO's "ORD_..." id

        // Steam now shows the purchase overlay to the player automatically.
    }

    // Steam fires this when the player approves or declines.
    private void OnSteamAuthorized(MicroTxnAuthorizationResponse_t cb)
    {
        if (cb.m_bAuthorized == 1)
        {
            // Approved; ask your backend to finalize (it calls INVO).
            MyGameBackend.FinalizeSteamPurchase(_pendingOrderId);
        }
        else
        {
            // Declined or cancelled; nothing was charged.
        }
    }

    void OnDestroy() => _authCallback?.Dispose();
}

Unreal Engine (C++, Steamworks SDK)

#include "steam/steam_api.h"

class FInvoSteamPurchase
{
public:
    // Called when the player taps "Buy" on a currency pack.
    void BuyCurrency(const FString& PackId)
    {
        const uint64 SteamId = SteamUser()->GetSteamID().ConvertToUint64();

        // Ask YOUR backend to start the purchase. Your backend calls INVO's
        // /steam/init-purchase with your X-Game-Secret-Key (never in the client).
        MyGameBackend->StartSteamPurchase(PackId, SteamId,
            [this](const FString& OrderId)
            {
                PendingOrderId = OrderId;   // INVO's "ORD_..." id
                // Steam shows the purchase overlay to the player automatically.
            });
    }

private:
    FString PendingOrderId;

    // Steam fires this when the player approves or declines.
    STEAM_CALLBACK(FInvoSteamPurchase, OnSteamAuthorized,
                   MicroTxnAuthorizationResponse_t);
};

void FInvoSteamPurchase::OnSteamAuthorized(MicroTxnAuthorizationResponse_t* cb)
{
    if (cb->m_bAuthorized)
    {
        // Approved; ask your backend to finalize (it calls INVO).
        MyGameBackend->FinalizeSteamPurchase(PendingOrderId);
    }
    // else: declined or cancelled; nothing was charged.
}

The callback only reports the player's intent. It is not proof of payment. INVO independently re-verifies the authorization with Steam in Step 3 before any money moves or any currency is credited.

Browser checkout: when the overlay cannot render

The default flow assumes Steam's in-game overlay can appear. On some builds it cannot (embedded-browser shells are the common case), and a purchase started there would simply never complete. For those platforms, pass "usersession": "web" (with player_ip) on init-purchase. Steam then returns steam_checkout_url: Steam's own hosted approval page, which you open in the player's system browser. The player approves there instead of in the overlay; everything else (finalize, credit, webhook) is identical.

Step 3: Finalize the purchase (backend)

After your client reports an authorized callback, your backend calls INVO with the order_id from Step 1. INVO verifies the authorization with Steam server-side, captures the charge, and credits the player's branded currency in one atomic step.

POST https://invo.network/api/currency-purchases/steam/finalize-purchase
Headers:
  X-Game-Secret-Key: ivsdk_<your_sdk_key>
  Content-Type: application/json

Body:
{ "order_id": "ord_a1b2c3..." }

Response 200:
{
  "status":            "success",
  "transaction_id":    "txn_...",
  "order_id":          "ord_a1b2c3...",
  "new_balance":       "100",
  "already_processed": false,
  "credited":          true
}

finalize-purchase is idempotent. A retry, or a duplicate call, returns already_processed: true and never credits twice. If the player has not finished authorizing yet, it returns 409 with status: "not_authorized". Wait for the Steam callback and call again.

Responses & error handling

Refusals before any charge

These fire on init-purchase, deliberately before the player pays. The alternative is taking money for currency that cannot be issued. None of them are the player's fault, and only some are yours:

Even if your backend never gets to call finalize-purchase (a crash, a dropped connection), INVO's reconciliation poller independently detects the authorized Steam transaction and credits the player. A missed finalize call delays the credit; it never loses it.

Refunds

Sandbox testing

Good to know