Payments

What it is

Your game has its own currency, gems, gold, credits, whatever you call it. indie.fun is the checkout that sells it: your server opens a purchase, the player pays in whichever currency you said you would take, and the money arrives in your wallet. indie.fun never holds it.

indie.fun is the payment processor and nothing more. It does not know what a coin is, what it buys, or how many a player holds. It knows the price of the one purchase it is settling, because it has to build a transfer for that amount and write down what was paid. Everything else is yours: the currency, the catalogue, the balance and the crediting.

A checkout

One purchase, at one price, for one player. Opened by your server, paid by the player, and settled on-chain.

Your payout wallet

The Solana address payments land in. Set once on your game’s Payments tab, and stamped onto each purchase when it is opened.

A receipt

Our record that a purchase was really paid. What your server reads before it credits anybody.

Coins are per-game. A coin bought in your game spends only in your game. If you want a currency players already hold when they arrive, that is Ruby, which is a different thing and settled entirely by indie.fun.

Open your game’s Payments tab and paste the Solana address that should receive payments. Until it is set, opening a checkout fails, because there would be nowhere for the money to go.

The wallet lives on your game rather than on a purchase, deliberately. A destination your server could name per request is a destination a compromised server can redirect, and you would never see it happen.

From your server, name the player, what they are buying, the price and what you will take for it. You get back a URL. Send the player there.

import { Indie } from 'indie-sdk/server';

const indie = new Indie({ appId: process.env.INDIE_APP_ID, appSecret: process.env.INDIE_APP_SECRET });

const { ok, url, error } = await indie.createCheckout(player.id, {
  item: '5,500 Coins',        // what the player sees at checkout
  priceCents: 499,            // $4.99
  coins: 5500,                // carried on the receipt, for you to read back
  reference: `shop-${cartId}`, // your id for this purchase
  accept: [
    { currency: 'usdc' },     // converted from the price at a live rate
    { currency: 'sol' },
    { currency: 'token', mint: MY_MINT, amount: '4000', label: '$GEM' },
  ],                          // omit accept entirely and it is USDC only
});

if (!ok) return fail(error);
redirect(url);

This needs your App Secret, so it only ever runs on your server. A browser that could open a checkout is a browser that could open one at any price it liked.

if (window.parent !== window) {
  const orderId = url.split('/').pop();
  window.parent.postMessage({ type: 'indiefun:open-checkout', orderId }, '*');
} else {
  location.href = url;   // played anywhere else
}

item

What the player is buying, in your words. Up to 80 characters. Shown at checkout and written on the receipt.

priceCents

What to charge, in US cents, from 25 to 50000. This is the revenue figure.

coins

Optional, and never interpreted by indie.fun. It is carried on the receipt so you can read back what you promised without keeping a table of your own.

reference

Optional, your own id for the purchase, unique per game, up to 128 characters. See above: it is the idempotency key.

accept

Optional. The ways this purchase may be paid, and omitting it means USDC only. Each entry is usdc, sol, or token with a mint. See below.

After paying, the player returns to your game. Ask us whether the purchase was really paid, rather than taking their word for it, then credit the coins.

const order = await indie.getCoinOrder(orderId);

if (order?.status === 'paid') {
  await creditOnce(order.id, order.buyerId, order.coins);
}

Credit against order.id, and make it credit once. The same purchase reaches you more than once by design: here, and again in the sweep below. The id is what makes the second time do nothing.

A player can pay and then close the tab, so the return trip in step 3 is not guaranteed to happen. Poll for paid purchases and credit anything the return trip missed. Keep the last paidAt you saw and pass it back as since to walk forward.

const orders = await indie.listCoinOrders({ since: lastPaidAt, after: lastId });

for (const order of orders) {
  await creditOnce(order.id, order.buyerId, order.coins);
  lastPaidAt = order.paidAt;   // the cursor for next time
  lastId = order.id;           // and the tie-breaker, see below
}

A request that fails resolves to an empty list rather than throwing. That is the safe direction for a poller: your cursor does not advance, so the next sweep asks for the same window again and no purchase is skipped.

Keep after alongside since. Two purchases can be paid in the same millisecond, and a cursor made only of a timestamp cannot tell them apart: if a page ends between them, the second is never returned again. The order id breaks the tie. Sending only since still works, and still has that gap.

Get told, instead of asking

The sweep above is how you learn the truth, and it stays that way. A webhook is how you learn it quickly: set a URL on your game and we POST to it the moment an order is paid, so coins land while the player is still looking at the shop rather than on your next poll.

PUT /api/me/creations/<gameId>/webhook   { "url": "https://your.game/indie-hook" }
→ { "url": "…", "secret": "whsec_…" }      // shown once

import { createHmac, timingSafeEqual } from 'crypto';

app.post('/indie-hook', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = createHmac('sha256', process.env.INDIE_WEBHOOK_SECRET)
    .update(req.body)          // the exact bytes, not the parsed object
    .digest('hex');
  const given = req.get('x-indie-signature') || '';
  if (expected.length !== given.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(given))) {
    return res.sendStatus(400);
  }

  const { orderId } = JSON.parse(req.body);
  const order = await indie.getCoinOrder(orderId);   // the truth, not the body
  if (order?.status === 'paid') await creditOnce(order.id, order.buyerId, order.coins);
  res.sendStatus(204);
});

Sign over the raw bytes, not a re-serialised object: JSON.stringify of a parsed body is not always the same string, and a signature over the wrong bytes fails for reasons that look like a bug in us. The URL must be https, since the signature is what makes a delivery believable and a plaintext one can be lifted and replayed.

Server methods

There is deliberately no way to open a checkout from the browser. All three of these cost the App Secret, which never belongs in a page. The raw HTTP endpoints behind them are on the API Reference.

Check it worked

If opening a checkout fails, the error says which of the three usual causes it is: no payout wallet set on the Payments tab, a userId that is not a real indie.fun account, or a price outside 25 to 50000 cents.

If a payment went through but nothing was credited, the purchase is not lost: listCoinOrders returns it, which is exactly what the sweep in step 4 is for. The Payments tab lists every paid purchase under the revenue, so that is where you confirm the money arrived and find the order id; crediting the player is still the sweep’s, because that page only reads. Check Authentication is working first: crediting needs a player id, and every purchase is opened against one.