Gift codes and creator codes

What you will build

GameCoin has two kinds of codes. They look alike for a player, who types a short word, but they do very different jobs.

Both live in the dashboard under Codes (in French for now), with one tab for each: Cadeaux (gifts) and Créateurs (creators). Like everything else, codes belong to an environment: a code created in test does not exist in live.

Gift codes

Use them for a contest, a convention, a partner or a streamer giveaway. Each code gives the same reward: some free coins, some items, or both.

Create a batch

In the Cadeaux tab, choose Nouveau lot and fill in:

GameCoin generates the codes with ten random characters from an alphabet that has no look-alikes (no 0 and O, no 1, I and L). With a prefix a code looks like PGW-K7M2Q-XH4NP. The dashes and the case do not matter when a player types it.

You can then open the batch to see every code, its state (active, used up, expired, disabled) and how often it was used, export the codes as CSV to print or send them, or disable a code or the whole batch. Disabling is final: the coins already given stay with the players, and you make a new batch to hand out codes again.

Let a player redeem a code

The player types the code in your game, and your game calls one route.

From your backend (secret key), when you know who the player is:

curl -X POST "https://gamecoin.apilow.com/api/v1/players/ext%3Auser-42/codes/redeem" \
  -H "Authorization: Bearer $GAMECOIN_SECRET_KEY" \
  -H "Idempotency-Key: redeem-user-42-pgw" \
  -H "Content-Type: application/json" \
  -d '{"code": "pgw k7m2q xh4np"}'

From a game without a backend (publishable key and player token), with POST /client/me/codes/redeem: it is the same body and the same answer. See Codes API for the details, the errors and a browser example.

The answer lists what was given: the coins with the new balance, and the items.

{
  "grants": [{ "currency": "gems", "amount": 100, "balance": { "currency": "gems", "paid": 0, "bonus": 100, "total": 100 } }],
  "items": [{ "sku": "potion", "quantity": 2 }],
  "skipped": []
}

The rules that protect you

• Free coins only. A code credits the bonus bucket, which cannot be refunded in euros. The ledger shows the entry with the type gift_code.
• Once per player, and a limited number of uses. The count is exact even when a hundred players type the same code at the same moment: a single-use code goes to one player only.
• Not transferable. A code credits the player who types it. GameCoin has no way to pass coins from one player to another.
• One answer for every refusal. An unknown, expired, used-up, disabled or already used code all give 400 VALIDATION_FAILED with fieldErrors.code = ["CODE_INVALID"]. This stops anyone from finding real codes by trying. Show one message: « This code is not valid ».
• Limited attempts. A player can try 10 codes per 15 minutes, right or wrong, and an IP address 30 (client API).
• Safe to retry. The call needs an Idempotency-Key. After a network error, send the same request with the same key: nothing is credited twice.

If a player already owns the most they can of a durable item, that item is skipped (the answer lists it in skipped) and the rest is still given. When the code has nothing left to give them, the call answers 409 LIMIT_REACHED and the code is not used up.

Creator codes

A creator code links a purchase to a content creator: a streamer, a YouTuber, a community. The creator shares the code; a buyer types it at checkout and gets extra free coins; you see the sales and the commission that the creator earned.

Create a code

In the Créateurs tab, choose Nouveau code créateur:

You can change a code later (rates, name, packs) or disable it and enable it again. A change applies to the next purchases: an order keeps the bonus and the commission it had when the player started it.

Use it at checkout

Pass the code the buyer typed as creatorCode when you create the order, with the server API or the client API:

curl -X POST "https://gamecoin.apilow.com/api/v1/players/ext%3Auser-42/checkouts" \
  -H "Authorization: Bearer $GAMECOIN_SECRET_KEY" \
  -H "Idempotency-Key: checkout-gems-500-user-42" \
  -H "Content-Type: application/json" \
  -d '{"packSku": "gems-500", "creatorCode": "leaplay"}'

The order answers with the code, and never with the rates:

{
  "order": {
    "id": "665f1c2e8a3b4d5e6f7081b4",
    "status": "pending",
    "pack": { "sku": "gems-500", "name": "Bag of gems" },
    "amountCents": 499,
    "creatorCode": { "code": "LEAPLAY", "creatorName": "Léa Play" }
  },
  "checkoutUrl": "https://gamecoin.apilow.com/pay/665f1c2e8a3b4d5e6f7081b4?t=…"
}

(Only the useful fields are shown.) A code that cannot be used — unknown, disabled, not valid for this pack, or the creator's own player — is refused with 400 VALIDATION_FAILED and fieldErrors.creatorCode = ["CODE_INVALID"], the same answer in every case. The order is not created: tell the player the code is not valid and let them try again or buy without it. Order objects without a code have creatorCode: null. The code also appears in the order.* webhooks, because they carry the same order object.

What the buyer gets, what the creator earns

Both are computed when the order is delivered, from the pack frozen in the order, and both are rounded down.

The buyer's receipt shows the bonus on its own line, with the code. The coins arrive in the same ledger entry as the pack: 500 paid and 100 free.

Refund and chargeback cancel everything. When the order is refunded, or the player disputes the payment, the coins are taken back as usual, the bonus included, and the commission is cancelled: the creator's sheet counts the order as canceled and the commission due drops. Nothing is counted for an order that was never delivered.

Follow the sales

Open a creator in the dashboard to see, for a period you choose (delivery dates):

• the number of orders, the sales including and excluding VAT, the commission due, and the bonus coins given to buyers;
• the orders that were canceled since, with the commission that was cancelled;
• the list of sales, and an export as CSV of the sales of the period (for your accounting, or to show a creator what they earned).

Test it

In the test environment, create a batch, redeem a code with a test player, then create a creator code and buy a pack with it: the payment is simulated. Check the wallet (bonus goes up), the ledger entry (gift_code), and the creator's sheet. See Testing.