Подключение казино к играм S7Connecting a casino to S7 games

1Как устроена сессияHow a session works

Границу ответственности проще всего увидеть по шагам.The division of labour is easiest to see step by step.

1.  Игрок нажимает «Играть» у вас на сайте.
2.  Вы выпускаете сессионный токен и открываете нашу ссылку в <iframe>.
3.  Мы зовём POST /auth на вашем кошельке с этим токеном.
       Вы отвечаете, кто это и сколько у него денег —
       именно отсюда мы узнаём валюту.
4.  Идёт игра. Каждая ставка — POST /bet, каждая выплата — POST /win.
       Ставку, которую нужно вернуть, отменяет POST /rollback.
5.  Игрок уходит. /win и /rollback обязаны работать и после этого.

1.  The player presses Play on your site.
2.  You mint a session token and open our link in an <iframe>.
3.  We call POST /auth on your wallet with that token.
       You answer with the player and their balance —
       this is where we learn the currency.
4.  The game runs. Every stake is POST /bet, every payout POST /win.
       A stake that has to be given back is POST /rollback.
5.  The player leaves. /win and /rollback still have to work.

Шаги 3–5 держите вы. Всё остальное — мы.You host steps 3–5. We host everything else.

2Ссылка на игруThe launch link

Её вы собираете у себя и открываете в iframe.You build it on your side and open it in an iframe.

https://play.afr.stellar-kiosk.com/game/{customer}/{module}/{game}/?<params>

2.1ПараметрыParameters

https://play.afr.stellar-kiosk.com/game/{customer}/crash/default/
  ?token=abc123&language=en&openType=real
  &devicetypeid=1&exitURL=https://casino.example/lobby

2.2Три вещи, которые стоит знатьThree things worth knowing

Регистр и разделители не важны. auth_token, authToken и AUTH-TOKEN — для нас один и тот же параметр. Если ваша платформа уже отдаёт другое написание — присылайте как есть: скорее всего мы его уже принимаем, а если нет, добавить его — это правка конфигурации у нас, а не у вас. Case and separators do not matter. auth_token, authToken and AUTH-TOKEN are the same parameter to us. If your platform already emits a different spelling, send it: we probably accept it already, and if not, accepting it is a configuration change on our side, not a change on yours.

Незнакомые параметры мы не выбрасываем. Они возвращаются в диагностике, так что если вы что-то прислали, а мы будто не заметили — видно ровно то, что пришло. Anything we do not recognise is kept, not dropped. It comes back in the diagnostics, so if you send us something and we appear to ignore it, you can see exactly what arrived.

Откройте ссылку в браузере до того, как напишете код кошелька. Мы отдадим страницу, которая перечисляет каждый присланный параметр, во что мы его сопоставили, и что ваш кошелёк ответил про токен. Это самый быстрый способ найти ссылку, собранную не на того кастомера. Open the launch link in a browser before writing any wallet code. We serve a page listing every parameter you sent, what we matched it to, and what your wallet said about the token. It is the fastest way to find a link built against the wrong customer.

2.3Кнопки выхода и кассыThe exit and cashier controls

Ничего из того, что вы строите сейчас, менять не придётся: правила уже зафиксированы.Nothing you build now has to change when they appear, because the rules are already fixed:

1. Нет адреса — нет кнопки. Не серая, не неработающая — контрола не существует. Не слать exitURL и нарисовать свой выход вокруг iframe — поддерживаемая конфигурация, а не обходной путь, и она останется верной и потом.No url, no button. Not a greyed-out one, not one that does nothing — the control does not exist. Leaving exitURL off and drawing your own exit around the iframe is a supported configuration, not a workaround, and it stays correct afterwards.
2. Адрес может прийти из ссылки или из настроек. Если игроки всегда возвращаются в одно лобби, назовите адрес один раз — мы его сохраним. Игра разницы не видит.A url may come from the link or from your settings. If players always return to the same lobby, tell us the address once and we hold it. The game cannot tell the two apart.
3. Переход заменяет всю страницу, а не фрейм. Лобби, отрисованное внутри прямоугольника игры, в её рамке и с её полосами прокрутки, — не то, что мы стали бы выпускать.The control replaces the whole page, never the frame. A lobby rendered inside the game's rectangle, still wrapped in the game's frame and scrollbars, is not something we would ship.

Проходят только обычные http(s)-адреса. Это единственные два параметра ссылки запуска, по которым что-либо переходит, поэтому значение вида javascript: или data: отбрасывается, а не передаётся дальше. Если вы прислали такое и игра ведёт себя так, будто вы не прислали ничего, — причина в этом. У правила 3 есть одно требование к вашей стороне — см. 3. Only ordinary http(s) values survive. These two are the only parameters on a launch link that anything navigates to, so a javascript: or data: value is discarded rather than passed on. If you send one and the game behaves as though you sent nothing, that is why. Rule 3 has one requirement on your side — see 3.

3Встраивание iframeEmbedding the iframe

Игра — обычная страница на нашем домене. От вас нужны размер и разрешение на звук.The game is an ordinary page on our domain. What it needs from you is a size and permission to make sound.

<iframe
    src="https://play.afr.stellar-kiosk.com/game/{customer}/crash/default/?token=abc123&openType=real"
    allow="autoplay; fullscreen"
    title="Crash"
    style="border:0; width:100%; height:100%; display:block">
</iframe>

• Размер задаёте вы. Игра тянется на весь фрейм; своей высоты у неё нет. Дайте контейнеру реальную высоту — height:100% внутри блока нулевой высоты даёт пустой прямоугольник.
• allow="autoplay" — без него в игре не будет звука до первого касания. fullscreen нужен, если даёте кнопку на весь экран.
• Не ставьте sandbox, если не уверены в наборе флагов: игре нужны скрипты, свой origin и хранилище. Урезанный sandbox ломает её молча. Если вы всё же ставите sandbox и хотите, чтобы работали внутриигровые выход и касса из 2.3, нужен ещё allow-top-navigation-by-user-activation — без него браузер не даст игре заменить страницу, и откажет молча.
• Новая сессия — новый элемент. Не переиспользуйте один iframe, меняя src: создавайте элемент заново, чтобы перезапуск был настоящей перезагрузкой, а не страницей, сохранившей прежнее состояние.

• The size is yours to set. The game fills the frame and has no height of its own. Give the container a real height — height:100% inside a zero-height block is an empty rectangle.
• allow="autoplay" — without it there is no sound until the first tap. fullscreen is needed if you offer a full-screen button.
• Do not set sandbox unless you are sure of the flags: the game needs scripts, its own origin and storage. A trimmed sandbox breaks it silently. If you do sandbox the frame and you want the in-game exit or cashier of 2.3 to work, it also needs allow-top-navigation-by-user-activation — without it the browser refuses to let the game replace the page, and refuses silently.
• A new session is a new element. Do not reuse one iframe by changing src; create the element again, so reopening is a real reload rather than a page that kept its state.

4Эндпоинт кошелькаThe wallet endpoint

Пять методов. Вы даёте один базовый URL, пути мы дописываем сами.Five endpoints. You give us one base URL; we append the paths.

POST {base}/auth          проверить токен → кто игрок + баланс
POST {base}/getBalance    прочитать баланс, ничего не двигает
POST {base}/bet           списать ставку
POST {base}/win           начислить выплату
POST {base}/rollback      вернуть ставку

POST {base}/auth          verify a token → who the player is + balance
POST {base}/getBalance    read the balance, moves nothing
POST {base}/bet           debit a stake
POST {base}/win           credit a payout
POST {base}/rollback      give a stake back

• Content-Type: application/json в обе стороны.
• Всегда отвечайте HTTP 200, в том числе на отказ. Вердикт — это поле code в теле. Кошелёк, который говорит «недостаточно средств» четырёхсотым, неотличим от прокси, который говорит «плохой запрос», а нам эти два случая нужно различать: от них зависит, повторять операцию или нет.
• Отвечайте быстро. Игра сдаётся по собственному вызову через 5 секунд и сообщает игроку, что ставка не прошла; мы ждём 6, прежде чем счесть запрос потерянным и повторить. То есть 5 с — ваш SLA, а 6 с — только наше терпение: кошелёк, который регулярно отвечает между ними, показывает игрокам ошибки на ставках, которые потом придётся возвращать (см. 12). Цель — меньше секунды.

• Content-Type: application/json, both ways.
• Always answer HTTP 200, including for a refusal. The verdict is the code in the body. A wallet that says "insufficient funds" with a 400 is indistinguishable from a proxy saying "bad request", and we have to tell those apart to decide whether to retry.
• Answer quickly. The game gives up on its own call after 5 seconds and tells the player the bet failed; we wait 6 before treating the request as lost and retrying it. So 5 s is your service level and 6 s is only our patience — a wallet that regularly answers in between shows players errors on bets that then have to be given back (see 12). Under one second is the target.

5ПодписьSignature

Каждый запрос несёт дайджест собственного тела, в заголовке с именем ровно Auth.Every request carries a digest of its own body, in a header named exactly Auth.

Auth: sha256(<сырые байты тела> + <общий ключ>)     hex, нижний регистр

Auth: sha256(<raw request body bytes> + <shared key>)     hex, lower case

Ни префикса, ни разделителя: ключ дописывается прямо к байтам тела, а значением идёт hex дайджеста в нижнем регистре. Проверить свою реализацию — одна строка: No prefix and no separator: the key is appended directly to the body bytes, and the value is the lower-case hex of the digest. Checking your implementation is one line:

printf '%s' "$body$shared_key" | shasum -a 256

Общий ключ обменивается при интеграции и по проводу не ходит.The shared key is exchanged at integration and never travels on the wire.

6Запросы и ответыRequests and responses

В каждом запросе есть partnerId и token. Остальное зависит от операции. Every request carries partnerId and token. The rest depends on the operation.

6.1Что присылаем мыWhat we send

// POST /auth  и  POST /getBalance
{
  "partnerId":  "198",
  "operatorId": "brand-7",  // только если бренд был в ссылке
  "token":      "abc123",
  "currency":   "USD"       // только getBalance; в auth его нет
}

// POST /bet
{
  "partnerId":     "198",
  "token":         "abc123",
  "transactionId": "bet:alice:1187:0",   // наш; уникален навсегда
  "amount":        2.5,
  "currency":      "USD",
  "gameId":        "555",                // ВАШ каталожный id
  "roundId":       "crash:USD:1187"
}

// POST /win — то же плюс ставка, которую выплачивает
{
  "partnerId":        "198",
  "token":            "abc123",          // МОЖЕТ БЫТЬ ПРОСРОЧЕН — см. 8
  "transactionId":    "take:alice:1187:0",
  "betTransactionId": "bet:alice:1187:0",
  "amount":           7,
  "currency":         "USD",
  "gameId":           "555",
  "roundId":          "crash:USD:1187"
}

// POST /rollback — вернуть ставку
{
  "partnerId":        "198",
  "token":            "abc123",          // МОЖЕТ БЫТЬ ПРОСРОЧЕН — см. 8
  "transactionId":    "cancel:alice:1187:0",
  "betTransactionId": "bet:alice:1187:0",
  "amount":           2.5,
  "currency":         "USD",
  "roundId":          "crash:USD:1187",
  "reason":           "cancel"           // cancel | void | rollback
}

// POST /auth  and  POST /getBalance
{
  "partnerId":  "198",
  "operatorId": "brand-7",  // only when the link named a brand
  "token":      "abc123",
  "currency":   "USD"       // getBalance only; absent on auth
}

// POST /bet
{
  "partnerId":     "198",
  "token":         "abc123",
  "transactionId": "bet:alice:1187:0",   // ours; unique forever
  "amount":        2.5,
  "currency":      "USD",
  "gameId":        "555",                // YOUR catalogue id
  "roundId":       "crash:USD:1187"
}

// POST /win — the same, plus the bet it pays out
{
  "partnerId":        "198",
  "token":            "abc123",          // MAY BE EXPIRED — see 8
  "transactionId":    "take:alice:1187:0",
  "betTransactionId": "bet:alice:1187:0",
  "amount":           7,
  "currency":         "USD",
  "gameId":           "555",
  "roundId":          "crash:USD:1187"
}

// POST /rollback — give a stake back
{
  "partnerId":        "198",
  "token":            "abc123",          // MAY BE EXPIRED — see 8
  "transactionId":    "cancel:alice:1187:0",
  "betTransactionId": "bet:alice:1187:0",
  "amount":           2.5,
  "currency":         "USD",
  "roundId":          "crash:USD:1187",
  "reason":           "cancel"           // cancel | void | rollback
}

roundId собран из игры, валюты и номера раунда: каждая игра нумерует свои раунды сама, поэтому голый номер уникален только внутри одной игры — составной id не даёт пятому раунду двух разных игр слиться в ваших отчётах. roundId is composed of the game, the currency and the round number. Each game numbers its own rounds, so the bare number is unique only within one game — a composed id keeps round 5 of two different games apart in your reports.

Поля roundFinished больше нет. Раньше оно было в этих телах и всегда приходило false, потому что ни одна игра не могла заполнить его честно: у раунда нет закрывающего сообщения, проигранная ставка не шлёт ничего (см. 8), а /win закрывает ровно ту ставку, которую называет. There is no roundFinished. It used to be in these bodies and was always false, because nothing in the games could set it truthfully: a round has no closing message, a losing bet sends nothing at all (see 8), and a /win settles exactly the bet it names.

6.2Что отвечаете выWhat you answer

{
  "code":          0,
  "balance":       997.50,     // ПОСЛЕ операции
  "currency":      "USD",
  "transactionId": "bet:alice:1187:0",   // эхо нашего
  "message":       "",         // свободный текст, для человека в логах

  // только /auth:
  "playerId":      "p-1001",
  "username":      "alice"
}

{
  "code":          0,
  "balance":       997.50,     // AFTER the operation
  "currency":      "USD",
  "transactionId": "bet:alice:1187:0",   // echo ours
  "message":       "",         // free text, for humans reading logs

  // /auth only:
  "playerId":      "p-1001",
  "username":      "alice"
}

balance — баланс после операции, в той валюте, о которой спрашивали. На отказе присылайте баланс как есть, если он у вас под рукой: вам это ничего не стоит, а нам экономит вызов. balance is the balance after the operation, in the currency you were asked about. On a refusal send the unchanged balance if you have it: it costs you nothing and saves us a call.

7КодыCodes

Одна таблица на все методы. Что мы сделаем с кодом, зависит от того, в какую сторону шли деньги: отказ по списанию не двигает ничего и окончателен, а начисление — это деньги игрока, и попросить их ещё раз за нас уже некому. One table for every endpoint. What we do with a code depends on which way the money was going: refusing a debit moves nothing and is final, while a credit is money that belongs to the player, and nothing upstream of us will ask for it a second time.

Незнакомый код и тело вообще без кода читаются ровно как 1. A code we do not know, and a body with no code at all, is read exactly like 1.

8ПравилаThe rules

9ДеньгиMoney

Суммы — JSON-числа в мажорных единицах: 2.5 для 250 минорных единиц двухзначной валюты. JSON-число не хранит хвостовых нулей, поэтому 2.50 приходит как 2.5, а 10.00 — как 10. Разбирайте их как десятичные — не как float и не как строку заданного вида. Amounts are JSON numbers in major units: 2.5 for 250 minor units of a two-decimal currency. A JSON number keeps no trailing zeros, so 2.50 arrives as 2.5 and 10.00 as 10. Parse them as decimals — not as floats, and not as text of a fixed shape.

У себя мы держим деньги целым числом минорных единиц и конвертируем один раз — здесь, на краю провода. Конвертация, которая потеряла бы долю минорной единицы, падает, а не округляет: мы не станем молча срезать часть выплаты и предпочтём, чтобы интеграция громко сломалась на тестах. We hold money as an integer count of minor units and convert once, here at the wire edge. A conversion that would lose a fraction of a minor unit fails rather than rounding — we will not silently shave value off a payout, and we would rather an integration break loudly during testing.

12Таймауты и повторыTiming and retries

13Лимиты и лестница ставокLimits and the stake ladder

Лимиты обеспечиваем мы, по числам, которые выбираете вы. По каждой валюте и каждой игре у нас лежат: Limits are ours to enforce, from values you choose. Per currency and per game we hold:

• лестница ставок — суммы, которые может выбрать игрок. Она же задаёт минимальную и максимальную ставку: всё, что вне её, отклоняется ещё до вашего кошелька;
• максимальный выигрыш на ставку — максимум, который может вернуть одна ставка. Именно на ставку, а не на раунд, и применяется он ограничением РАУНДА, а не урезанием выплаты — см. примечание ниже.

• a stake ladder — the amounts a player can pick. It is also the minimum and the maximum stake: anything outside it is refused before it reaches your wallet;
• a maximum win per bet — the most a single bet can return. Per bet, not per round, and applied by capping the ROUND rather than by trimming a payout — see the note below.

Пришлите нужные числа по каждой валюте — мы их выставим; поменять потом это конфигурация у нас, а не релиз. Отказать в ставке вы, разумеется, можете и сами — кодом 5. Send us the numbers you want, per currency, and we set them; changing them later is configuration on our side, not a release. You may of course refuse a stake yourself with code 5.

10Чек-листChecklist

Интеграция готова, когда выполняется всё перечисленное.Your integration is done when all of these hold.

1. /auth с валидным токеном возвращает игрока, валюту и баланс./auth with a valid token returns the player, the currency and a balance.
2. /bet уменьшает баланс ровно на сумму./bet decreases the balance by exactly the amount.
3. /win увеличивает его ровно на сумму./win increases it by exactly the amount.
4. Один и тот же transactionId дважды не двигает деньги дважды, и второй ответ — 110.The same transactionId twice does not move money twice, and the second answer is 110.
5. /rollback восстанавливает баланс, а его повтор отвечает 110./rollback restores the balance, and a repeat of it answers 110.
6. /win и /rollback работают на просроченном токене./win and /rollback work with an expired token.
7. /rollback неизвестного betTransactionId отвечает 7./rollback of an unknown betTransactionId answers 7.
8. Ставка больше баланса отвечает 3, и баланс не меняется.A bet larger than the balance answers 3, and the balance is unchanged.
9. /win с нулевой суммой принят.A zero-amount /win is accepted.
10. 2.5 на проводе — это 250 минорных единиц в вашем реестре, в обе стороны.2.5 on the wire is 250 minor units in your ledger, both ways.
11. /bet с идентификатором, который вы уже откатили, не двигает денег и отвечает 110.A /bet whose id you have already rolled back moves nothing and answers 110.
12. Запрос с неверным дайджестом в Auth отвергается.A request with a wrong Auth digest is refused.

Четвёртый и шестой — те, что падают в проде. Проверить их дёшево, а обнаружить дорого. Numbers 4 and 6 are the ones that fail in production. They are cheap to test and expensive to discover.

11Что прислать намWhat to send us

Если что-то из этого потом поменяется — всё это конфигурация на нашей стороне. Ни один пункт не требует деплоя. If any of it changes later, all of it is configuration on our side. None of it is a deploy.