Skip to main content

Linked game accounts and credit acceptance

Some players already have a game account at one of our providers, created outside PlayGo (for example on the legacy platform), sometimes with credits on it. PlayGo can link such an account instead of creating a new one. Players can do it themselves ("Add existing" on a game), or an admin can link one for them.

A verified linked assignment uses normal redemption without first-redemption admin approval (ADR 0027, 2026-10-06). The system accepts pre-existing credits at full value; post-link PlayGo funding follows the normal cash/freeplay policy. Fresh balance verification and verified zero after the provider debit remain required. Existing open reviews are historical obligations and must be finished or cancelled before normal activity resumes.

SlotsFam rollout status (2026-09-26)

player_link is disabled by default. SlotsFam has persisted overrides enabling it for all eight configured games: Gameroom, Mafia, Cash Machine, MilkyWay, Game Vault, Juwa, Juwa 2, and Orion Stars. Penguin has no link override. Check the live admin provider capability list before relying on this snapshot.

Lifecycle at a glance​

link (player or admin) read-only provider checks; opening balance recorded, nothing booked
│
linked account normal load admission; no new first-redemption review
│ accepted old credits plus ordinary cash/freeplay quote rules
▼
Redeem fresh verified balance → debit full whole-credit balance
│ → verified-zero read → quoted payout and forfeit settlement
▼
normal cycles the payout policy applies; old-credit allowance has ended

Linking​

WhoEndpointRoleNotes
PlayerPOST /api/v1/games/{game_id}/add-existingplayerIdempotency-Key required
AdminPOST /api/v1/admin/players/{user_id}/provider-accounts/linkadminReason required; reference optional
  • The form is backend-owned. Game.add_existing_form gives the identifier label and whether a password is required, optional or not_accepted. Terminal providers such as MilkyWay require the account's password, because their account lookup is authenticated with it.
  • Linking never changes anything at the provider. PlayGo reserves the account, then verifies it with read-only calls: an agent-scoped lookup where the provider has one, plus an exact integer balance read. A supplied password is stored encrypted and is never emailed.
  • Verification accepts the linked assignment. No first-redemption admin approval is required (ADR 0027, 2026-10-06).
  • Only one live link per external account. A second player trying to link the same account gets account_already_linked. A failed or timed-out verification leaves nothing occupied, and the player can retry with a new key.

Common reasons returned in the reason field:

ReasonMeaning
link_unavailableThe provider's player_link capability is disabled or unsupported
provider_account_existsThe player already has an account for this provider
provisioning_in_progressPlayGo is still creating an account for this provider
account_already_linkedThat external account is linked to someone
verification_failedThe provider says the account doesn't exist or isn't ours
credential_requiredThe provider needs the account password (missing or wrong)
verification_unavailable (503)The provider couldn't be reached; nothing changed

Automatic acceptance of existing credits​

Linked accounts use normal load admission, including freeplay and combined loads.

A refused load preflight returns allowed: false, its typed reason and the server-owned refusal_reason. For insufficient free play or an invalid credit increment when bonus/free-play balances are present, the explanation names the real available amounts, the paid-cash condition for using deposit bonus, the current free-play policy and the game's credit step. Clients display that explanation unchanged; a wallet total is not a promise that every bucket can fund the requested load. The first redemption accepts old credits at full value without admin review, using a fresh verified balance and verified zero after debit. With post-link loads, accepted old value is bounded by the opening balance; the remaining credits follow normal cash/freeplay policy. Post-link freeplay follows the normal winnings rule and minimum; it is never paid at 100%. The immutable cashout quote records the system decision and accepted old value, and Story labels the system acceptance. Unknown debits reconcile with the same provider order. A completed redemption or confirmed-zero cycle ends the old-credit allowance. Unlinking/relinking the same provider ref or stable player ID retains that identity's funding, withdrawal and zero history, even across players or aliases. Relink opening credits never reset the old-credit allowance. Ineligible imported mixed balances receive the same explicit, token-confirmed zero-payout Clear Balance flow as freeplay.

Finishing historical first redemption reviews​

No new first redemption review is created. Existing open reviews continue to block loads and redemptions until admins finish them, and players may cancel pending reviews. The following admin workflow applies only to those historical rows.

GET /api/v1/admin/first-unload-reviews?state=pending lists the queue. GET /api/v1/admin/first-unload-reviews/{id} shows the evidence:

  • the opening balance at link time, who linked it, and how it was verified
  • every load in the cycle, with its cash / cash-out balance / freeplay sources
  • the snapshot balance and its cash value, which is the maximum payout
  • the full event history

Maker-checker: the admin who requested the review, or who linked the account on the player's behalf, cannot approve it (409 maker_checker_conflict). Another admin must approve.

Refresh: POST .../refresh reads the current provider balance and replaces a pending snapshot without debiting or paying out. It increments the snapshot version, so the admin must review the new cash value and confirm the decision again. Balances with sub-cent residue, or fractional balances on providers without an exact-debit capability, remain blocked for manual reconciliation.

Approve: POST .../approve (admin) with:

snapshot_version, expected_balance_credits, expected_balance_credit_hundredths
what you reviewed; the latter is exact
approved_payout_cents 0 .. reviewed_value (whole cents; no other cap)
assignment_confirmed: true you confirmed the account belongs to this player
reason audit evidence

What happens:

  1. The review is claimed for at most 5 minutes, and PlayGo re-reads the provider balance.
  2. If the balance changed since you reviewed it, nothing is debited. You get rereview_required with the refreshed snapshot, so review again. A failed read returns 503 fresh_balance_unavailable and nothing is debited.
  3. Otherwise PlayGo debits the full fresh balance at the provider.
  4. PlayGo then re-reads the balance, which must be exactly zero (verified zero). Only then does it book anything:
    • Historical freeplay principal is consumed and forfeited, never returned to Freeplay.
    • The rest of the approved amount becomes Withdrawable Cash. Its provenance lot is provider_reviewed_unload, never provider_cashout.
    • Everything above the approved amount goes to the forfeit account (ledger kind provider_reviewed_unload_settle).
  5. If the balance was already zero, the review settles with no transfer.

approve=0 is valid: the full balance is debited and forfeited.

Reject: POST .../reject with a reason. Nothing is called at the provider, the cycle stays dirty, and the player can request again later.

When the outcome is uncertain​

SituationStateWhat happens next
Debit timed out or ambiguousreconcile_requiredThe reconciler proves the debit through the provider transfer lookup. It never auto-refunds or auto-credits
Debit OK, but the zero read failed or was non-zeroreconcile_requiredThe reconciler repeats the verified-zero read. Nothing is credited until a read returns exactly zero
Provider definitively refused the debitback to pendingNothing moved. Review again

A balance of zero on its own never proves our debit happened. Without a confirmed debit, the reconciler only settles through the provider's transfer lookup. If the provider has no usable transfer lookup, the review stays in reconcile_required until an operator resolves it.

Operator resolution: POST /api/v1/admin/first-unload-reviews/{id}/resolve (super-admin only, Idempotency-Key). It is a recovery override, so it needs stronger privilege than approving. Regular admins see actions.resolve_* disabled with a reason, and the endpoint returns 403 for them. It never calls a mutating provider API. The body is resolution, provider_evidence_reference (required, e.g. the provider-panel transaction id) and reason. It is only allowed while the review is reconcile_required and the transfer is unresolved; the detail's actions.resolve_* show when.

ResolutionWhenEffect
debit_confirmedProvider evidence shows the debit happened and a fresh read verifies zero nowFirst takes a contemporaneous verified-zero read. If it is unavailable or non-zero, nothing is persisted: you get a definite 503 zero_balance_unverified, and you retry later with a new key. With a verified zero, the attestation (including zero_observed_at), its audit event and the idempotency result commit in one transaction, and the response is 200.

Settlement is then attempted in the same call, best-effort:

  • Normally the 200 review is settled.
  • If settlement itself fails (for example an amount-policy or database error), the 200 review is still reconcile_required with debit_confirmed = true and nothing credited. The reconciler settles it later, only after another verified-zero read, and only once the failed attempt's 5-minute settlement lease has expired. The transfer-state check guarantees it settles exactly once.

Replaying the key returns the latest state. An attestation never exists without zero proof, and the reconciler never settles a review from a zero balance alone | | debit_not_applied | Provider evidence shows no debit, and the debit was never confirmed | The transfer becomes rejected and the review goes back to pending. No PlayGo money moves, and approving again re-reads the balance |

Residual risks, accepted and documented:

  • No transfer lookup. On a provider without a usable transfer lookup, a super-admin could attest a debit that never happened at a moment when the player had already played the balance to exactly zero. The required provider evidence reference and the audit trail are the control.
  • Two colluding admins. Maker-checker stops one admin from both linking an account for a player and approving its first redemption, but two colluding admins are not covered.

There is no forced-credit path. The residual risk is an operator confirming a debit that didn't happen while the player played the balance to zero. The required evidence reference and the audit events (actor, reason, reference) are the control for that.

Crash recovery: the sweeper also repairs review/transfer drift every minute:

  • a rejected transfer puts the review back to pending
  • an unknown or failed transfer puts a settling review into reconcile_required
  • a reviewed transfer never started after 5 minutes is resumed
  • a transfer stuck in provider_requesting becomes unknown, for reconciliation to decide; it is never assumed to have failed

Unlinking​

POST /api/v1/admin/provider-accounts/{id}/unlink (admin, reason required, Idempotency-Key).

  • Refused with 409 account_has_open_work while a transfer, a first redemption review, or account provisioning is open.
  • Deletes no history. Transfers, ledger, provenance, reviews and link events all stay. The account becomes unlinked, its credentials are deactivated, and the provider's games are removed from the player's library.
  • Nothing is changed at the provider. The response reports the last known and fresh balances, plus the PlayGo-loaded principal (loaded_principal_on_provider) that the player leaves on the provider account. Read it before confirming.
  • Afterwards:
    • The player can add the provider again, either a new PlayGo account or another link.
    • The same external account can be linked again, by anyone.
    • GET /api/v1/admin/players/{user_id}/provider-accounts still shows the unlinked row.
  • Library side effect: if the removed games were the player's only games, the default game set is re-seeded on their next visit.

Linking is gated per provider by the player_link capability. It is disabled by default for every provider and every deployment. It is also forced off whenever live provider mutations are disabled.

How to enable a provider (after the checks below pass)​

PATCH /api/v1/admin/providers/{provider_code}/capabilities/player_link
{ "expected_status": "disabled", "next_status": "enabled", "reason": "<smoke evidence ref>" }

This is an admin call. It is recorded in provider_capability_status_transitions and restored at every boot, so it is durable. Disabling uses the same call in reverse, and linked accounts stay linked.

Enable a provider only when all of these hold on the same tenant and agent store as the deployment. For SlotsFam that means the Fam agent credentials; evidence from Whale/Penguin does not count.

Fam status (2026-09-26):

  • Active provider_probe_accounts stable-read canaries, not the runtime stable_test_username defaults, are the valid lookup fixtures. The read-only import smoke passed for all eight configured providers: gameroom, mafia, cashmachine, milkyway, gamevault, juwa, juwa2, and orionstars. Every Fam lookup rejected the matching Penguin canary from the other store. Player-site link attempts with Penguin Mafia and Game Vault canaries also failed before a game account was connected.
  • MilkyWay rejected an incorrect player password. Orion Stars returned the same account for correct and incorrect passwords but rejected a nonexistent and a Penguin-store account. Its proof is agent-scoped account existence, not password validation or human ownership.
  • On 2026-09-26, the production admin link endpoint attached each of the eight Fam stable-read QA canaries to the SlotsFam QA user, observed active status and zero opening credits, then unlinked each one. Admin history showed no active QA links afterward. This exercises the same backend link service as the player action, but is not eight separate browser/UI tests or eight linked first redemption cycles.
  • The Mafia same-store player link, dirty first cycle, 1-credit load and first redemption admin approval completed on Fam. The account reached verified zero and the wallet received an audited $1 credit. This is not a linked redemption cycle for the other seven providers.
  • The largest Fam agentserver player list observed earlier was 176 players, under the 2,000-player lookup limit; growth can change this.
  • prod_provider_smoke.py --ssh-host fam --provider all-configured --verify-existing checks positive lookups. Add --foreign-canary code=username for cross-store rejection. The smoke logs into Agentserver separately, which may rotate its single vendor session; schedule it carefully. Runtime app traffic reauthenticates, but the probe is not an in-process health check.

Do not enable another provider until its remaining live QA is recorded. The operator accepted the same-store takeover risk of immediate ID-only self-link use on 2026-09-26. This is a product risk decision, not evidence that an ID lookup proves human ownership; revisit it if fraud or mistaken linking occurs.

  1. Read. VerifyExistingPlayer finds a known Fam test account and returns its exact integer balance, and a lookup of a non-existent / other-agent account is rejected.
  2. Link. Add existing verifies and links it without creating a first-redemption review. Opening credits and provider identity history appear correctly.
  3. Redeem. Normal redemption, fresh balance verification, debit, verified-zero read and settlement complete, with system acceptance of old credits and normal post-link cash/freeplay policy checked against the ledger, lot and forfeit.
  4. No launch blocker applies (below), or a policy for it has been decided.

Launch and ownership risks​

  • Passwordless launch: slotopool. LaunchGame builds an authenticated launch URL from the player id alone (slotopool/provider.go). Whoever links an id can play it, even if it isn't theirs. The operator accepts this risk for ID-only linking, but Slotopool is not configured and has no verified import adapter.
  • Agent-side password reset: gamevault / juwa family. The player POST /games/{id}/reset-password resets the password through the agent, with no old password, and shows the player the new one. On an ID-only linked account this permits immediate takeover of another player in the same store. The operator explicitly accepts this risk; the UI and runbook must not imply verified ownership.
  • Agent-scoped lookup is not human ownership. Cross-store rejection proves agent scope, not that the website user owns an account within that store. Agentserver cannot reset a player password, but a false link can still target someone else's funds. Historical redemption reviews were payout controls, not ownership proof. Current linked-credit acceptance follows ADR 0027 without a new first-review gate.
  • Identifier occupancy. Migration 75 adds a unique (provider_code, provider_player_id) index for linking/active/disabled accounts. Terminal verification now requires a stable gameId, and Blue Dragon rejects mismatched canonical account responses. The entered account identifier/username is still used as a terminal ref; an unknown vendor case-normalization rule needs an explicit negative test before enabling that provider. The index must be deployed on both tenants before enabling additional providers.
  • Reservation lease. A linking reservation holds the raw identifier for up to 5 minutes (the claim lease) before verification finishes or the sweeper frees it. During that window a verification-failing attempt blocks other players from that identifier. This is accepted as bounded.
  • Terminal (milkyway, kraken, orionstars) launches with the account's own stored password. Kraken and Orion Stars also reset with it; MilkyWay resets with an agent-signed changePasswd that needs no old password, so a forgotten or rejected password can still be reset. A linked account without a usable stored credential is rejected explicitly (credential_required) and never falls back to the stable test password.

Provider readiness (current evidence)​

The table separates read-only import lookup from a completed link/redemption. A generic health canary pass is not import evidence. Check provider_capability_status_transitions and the live admin provider list for current flags before release.

ProviderSlotsFam link statusEvidence and gaps
mafiaenabledFam and Penguin canaries pass lookup; cross-store rejection passes; Fam link, 1-credit dirty first redemption, admin approval and verified zero passed. Owner identity for a player-entered ID remains a policy risk.
gameroom, cashmachineenabledFam canaries pass lookup and reject Penguin-store canaries; no Fam linked-account redemption proof.
gamevaultenabledFam lookup and player-site negative link reject the Penguin canary. Agent-side reset allows takeover of another player in the same store; operator accepted that risk. Linked-account redemption evidence remains missing. The Game Vault "Midnight Party" promo can block small redemptions.
juwa, juwa2enabledBoth Fam canaries pass lookup, reject Penguin-store canaries, and completed a zero-balance link/unlink through the production admin endpoint. Browser self-link and linked redemption remain unverified. Agent-side reset permits same-store takeover under the accepted ID-only policy.
milkywayenabledCorrect-password queryInfo passed and a controlled wrong-password request rejected on Fam; its Penguin canary is rejected from Fam. A Fam linked-account redemption remains unverified.
orionstarsenabledFam queryInfo found its own canary and rejected a nonexistent and Penguin-store account, but returned the same game ID with a wrong password. A zero-balance production admin link/unlink passed. Import uses agent_signed_balance_read, not credential_verified; the operator accepts immediate ID-only use. Browser self-link and linked redemption remain unverified.
mrallinone, noble, cashfrenzynot configuredPenguin canaries pass lookup. Noble had one transient vendor 410 during grouped smoke and passed on an isolated retry. No Fam configuration or same-store linked-account cycle.
kraken, megaspinnot configuredPenguin correct-password lookup passed; no Fam configuration or linked redemption.
bluedragonnot configuredPenguin getUserInfo returns matching agent, canonical account and stable idx; no linked-account redemption proof.
winstar, luckystars, goldendragon, vpower, pandamasternot configuredNo evidence.
vblink, ultrapanda, dragonfury, ultrathunder, goldentreasure, glamourspin, egame, riverpay, vegasx, yolonot configuredConfigured on Penguin but no VerifyExistingPlayer implementation; import cannot be enabled. Normal create/load smoke does not change this.
slotopoolnot configuredPasswordless launch risk; test-only provider.

The active SlotsFam catalog is set by its deployment config; internal/app/restrict_game_catalog_test.go tests the code-level catalog restriction.

Caveats that apply once a provider is enabled:

  • agentserver lookup limit. Verification searches at most 20 pages × 100 players. An agent with more than about 2,000 players can return Unknown (503 verification_unavailable) for accounts past that point.
  • Scope of the proof. Verification proves the account is under our agent, as the vendor scopes it; it does not prove the player owns it. That is why approval requires assignment_confirmed.
  • Real balances are untested. All evidence balances are 0 or 1 on test accounts. Under ADR 0015 provider balances are whole credits: a fractional vendor balance is floored and the sub-credit dust stays in the game account. Code that still rejects or carries fractions predates that decision (phase P2).

Player library add time​

Every game response includes nullable added_at, taken from the player's existing user_games.created_at. Pin changes and add replays preserve it. An unadded game or a catalog view without a player library row returns null. The catalog remains in catalog order; clients can use the most recent add time for Quick access without mistaking pin or catalog order for library history.

Unreadable account repair​

account_unreadable records that our store cannot read one account while agent authentication and an independent other-account read are healthy. It diagnoses no password change, deletion, freezing or reassignment. Automatic reads stop and Load/Redeem/Move/Launch refuse with HTTP409/code account_unreadable, retaining stored balances and observation times. The Inbox exposes username/account ID, the approved operator panel, Re-check and Relink.

Read /admin/provider-accounts/{id}/repair-options for the actual configured verifier and password requirement. POST recheck with reason deliberately verifies the current identity/balance, using roster-first proof when available. It never rewrites a changed ID. POST relink with reason, username, provider_player_id and required password verifies the exact candidate before an audited CAS on the same account. Neither operation grants money or changes ownership/lifecycle. Both require active staff, CSRF and an actor-scoped held Idempotency-Key; exact stored body replays. HTTP409 command_in_progress retains the held attempt; conflict is a definite CAS/occupancy/key refusal.

AgentServer uses playerList then getScore and has no password reset operation. Terminal uses signed queryInfo with a player credential, requires the current password for Relink, and uses the username as its native reference. Numeric ID alone cannot repair Terminal. Its existing reset requires the old password and must not be offered as an identity repair.

Terminal credential rejection​

For Terminal, authenticated queryInfo native201 means credentials_rejected under ADR0033, with exact not_found fixture precedence. It stops automatic reads and provides the backend's game/brand reconnect message. Player account and game read models offer actions.reconnect only for an owned active account with this issue and the actual configured credential verifier.

POST /api/v1/provider-accounts/{id}/reconnect with {password} verifies the current password against the same ref/username/ID and saves it sealed atomically. Staff POST /api/v1/admin/provider-accounts/{id}/set-password with {password,reason} means the current password already set in the provider panel. Staff POST /api/v1/admin/provider-accounts/{id}/reset-password with {current_password,reason} calls the actual reset and cannot bypass that current credential. AgentServer offers neither credential repair nor reset.

All are held idempotent commands with CSRF and active ownership/admin gates. Reset unknown leaves the saved password and issue untouched and issues no success notification. Confirmed reset saves before a one-time copyable response; replay omits the password and the in-app notification contains no password. Secrets are absent from audit details, tracing, read models, effects and stored command result JSON; secret-bearing request identity is encrypted.

Open-in-browser signup free play​

src=inapp_open marks the Messenger link that opens the site in Safari or Chrome. The browser records it as entry_source: "inapp_open" on the existing POST /api/v1/acquisition/landing-touches, with the existing anonymous_subject. Only a server-received touch before account creation and within 24 hours of verified registration can qualify. The email challenge carries the subject into verification, including cross-device code/magic-link verification.

The published verified-signup rule in Settings → Bonuses → Reward rules supplies the Messenger offer amount. The same rule holds the separate standard signup amount. A qualifying Messenger visit takes precedence. Existing accounts and returning logins receive no grant; at most one qualifying account per subject and verified normalized email can receive it. Balance changes, immutable grant receipts, reward events and the Welcome free play +$X notification commit in the same registration transaction. Free play uses the normal cash-threshold, game-load source tracking and winnings cash-out rules.

Public GET /api/v1/support/contact-links returns the currently available Messenger amount in inapp_signup_freeplay_cents. It needs no authentication or session and responds with Cache-Control: public, max-age=30, s-maxage=30. The in-app screen shows Get $X free play only above zero. This read contains no eligibility decision or account data; signup checks the published rule and guard receipts again.

Uncertain automatic account creation​

An unknown creation queues a read-only reconciliation job, including historical unknown records discovered at startup. It looks up the original generated name; it never calls create again while the outcome is uncertain. Attempts run after one minute, then wait five, fifteen and sixty minutes between follow-ups.

A proven existing account is linked transactionally. A complete agent-scoped lookup that proves absence marks setup failed and allows an explicit setup retry. A partial roster or provider failure does neither. After four unresolved attempts, one Platform situation appears with facts.provisioning: the provisioning_id, job_id, attempts and optional configured panel_url. The player and provider IDs remain in the situation subject. The job stays stopped until the account is verified through the owning workflow.

Public winners feeds​

GET /api/v1/recent-winners serves only genuine roulette spin prizes. Game withdrawals and payment cash-outs never appear in the roulette list.

GET /api/v1/recent-cashout-winners serves the global Home winners card. It reads completed payment cash-outs with actual net amount at least the configured winner floor and lifetime completed payouts exceeding completed deposit principal at that completion time. Game-to-wallet returns need quote-backed paid profit strictly above the configured floor; returned load/accepted principal is subtracted through the existing PostgreSQL profit function. It excludes tester accounts, inactive players, pending or rejected transfers, deposits and spin prizes. Amounts are whole USD cents derived in PostgreSQL from the completed payment or immutable cash-out audit; free-play credits consumed at settlement are not counted as paid cash.

Rows contain only a masked username, source kind, actual cents, game/payment-method display label, relative display time and a backend-owned highlight flag. Source identifiers, receiving accounts and exact timestamps are not public. The existing rolling window and feed-size settings bound the newest-first list to at most four rows. BIG WIN requires game paid profit or payment net amount strictly above the configured threshold; a qualifying payment at equality is not highlighted. Lifetime profitability totals include all completed history up to the receipt, not just the display window; later deposits do not change its qualification. This read never moves money. The player's personal history remains in the wallet/history views.

Created game passwords and staff backfill​

Creation generates a provider-compatible password once, seals its intent before native IO, and supplies it through the adapter. An authoritative returned password for the matching native identity takes precedence over our input. Legacy AgentServer cannot prove a password through its roster or balance reads; an echo, missing material or mismatched identity stays Needs panel reset. Native-capable newly-created accounts use the existing fenced reset owner when no confirmed password is available. Unknown resets keep their original command, sealed candidate and hold; never repeat them under another key.

GET /api/v1/admin/provider-accounts/missing-passwords is the read-only staff inventory (admin role; bounded cursor paging). Settings → Game links → Passwords lists every active account without an active saved login, with the provider's native/current-password/panel/original-reset procedure. Manage account opens Player → Game → Manage. Confirm and save through its existing audited native or panel owner; the task then disappears. The list never resets accounts, changes balances or adopts money automatically. Account-ready emails contain only provider and username metadata; passwords use the existing reveal/copy UI.

Creation, adoption, vault and reset owner tests cover accepted password bytes, provenance, exact replay and unchanged wallet facts. Native adapters use sanitized golden replay fixtures in internal/providers/providergolden. Authorized Penguin sanity checks use synthetic accounts; unknown results remain unresolved. See ADR 0054.