# Merchant Lifecycle

This doc explains how Apogee Studios and operators (merchants) work together from onboarding through go-live and beyond. If you're a developer on an operator team and you already have your keys, you probably want [QUICKSTART.md](./QUICKSTART.md). If you want to understand the *shape* of the relationship, read this.

## Who's who

| Role | Who | What they do |
|---|---|---|
| **Apogee Studios** | Us — the game provider | Runs the games, issues keys, generates invoices |
| **Merchant** (a.k.a. operator) | You — casino / sportsbook / sweepstakes platform | Embeds Apogee games, runs the wallet, markets to players, handles player support |
| **Player** | Your users | Play the games on your site |

Players never talk to Apogee directly. They only interact with your brand.

## The merchant record

In Apogee's internal system, every operator is represented by a **merchant record** with:

- **Merchant ID** — stable, opaque, e.g. `mrc_8a3f2bc1`. Appears in every round's billing data.
- **Display name** — "Example Casino Group Ltd"
- **Contact email** — where Apogee sends onboarding emails, key rotation notices, invoices
- **Status** — `active` (can launch games) · `pending` (onboarding in progress) · `suspended` (live keys refuse, sandbox still works)
- **Allowed games** — either `["*"]` for the whole catalog, or a specific subset like `["skyward","thermal"]`. Defaults to `"*"`.
- **Wallet URL** — where Apogee calls your `/wallet/*` endpoints
- **Webhook URL** — where Apogee posts round events (optional)
- **Fee rate** — percentage of GGR Apogee charges you. Typically 12–18%, negotiated at contract signing
- **API keys** — one or more pairs, each with a scoped permission list

You don't manage any of this yourself. If something needs to change — a key rotated, a fee rate updated, a game allowlisted, a webhook URL changed — you email your partner manager and they update it in the Apogee admin panel.

## Onboarding — the happy path

**Day 0 · Contact.** You email `partners@apogeetech.net` with:
- Operator name and trading entity
- Target markets (country list)
- Expected volume (rough — "500 DAU in 6 months")
- Player currencies you support (e.g. EUR, KES, BTC)
- Regulatory status (license, certification body)

**Day 1–3 · KYB and contract.** Apogee verifies your license and entity, sends the commercial contract (revenue share, MSA). You sign.

**Day 3 · Technical setup.** Apogee creates the merchant record:
```
ID:          mrc_8a3f2bc1
Name:        Example Casino Group Ltd
Status:      active
Games:       ["*"]
Fee rate:    0.15  (15% of monthly GGR)
Keys:
  Sandbox:   pk_test_apogee_abc123…  /  sk_test_apogee_xyz789…
  Live:      pk_live_apogee_def456…  /  sk_live_apogee_uvw012…
```

You receive a welcome email with the keys, the merchant ID, and links to [INTEGRATION.md](./INTEGRATION.md), [QUICKSTART.md](./QUICKSTART.md), and [API.md](./API.md).

**Day 3–10 · Sandbox build.** Your engineering team integrates against `https://sandbox-api.apogeetech.net` using test keys. You can run as many rounds as you want — sandbox state is wiped monthly, live state is never touched.

**Day 10 · Go-live check.** Once your sandbox passes the [go-live checklist](./INTEGRATION.md#8-go-live-checklist), email your partner manager. Apogee flips the live keys on and you can point your production environment at `https://api.apogeetech.net`.

**Day 11+ · Production.** You launch to players. Apogee:
- Calls your wallet on every bet and payout
- Tags every round with your merchant ID
- Generates an invoice on the 1st of each month based on that month's GGR × your fee rate

## Key rotation

Keys should be rotated quarterly or after any security incident.

1. Email `security@apogeetech.net` with the merchant ID.
2. Apogee generates a new key pair on your merchant record; old keys stay active for **72 hours** so you can deploy the new keys without downtime.
3. You update your secrets manager and deploy.
4. After 72 hours Apogee revokes the old keys.

Emergency rotation (suspected secret leak): keys can be revoked within minutes. Call the hotline in your MSA.

## Adding an additional environment key

You may want a third key pair for a staging environment between sandbox and production. Ask for `env=staging` — Apogee can issue as many key pairs per merchant as you need.

## Suspending / resuming

Apogee can set a merchant to `suspended` at any time, which causes the live API to return `423 game_disabled` to every session request. Sandbox continues to work so you can keep developing. Reasons:

- Compliance / regulatory demand
- Unpaid invoice after 30 days overdue
- Security incident on either side
- You requested a pause (contract renegotiation, go-dark period)

Resume is instant — Apogee flips the status back to `active`.

## Billing

- **Metric:** Monthly GGR (Gross Gaming Revenue = total wagered − total returned), in the currency each round was played in. Apogee converts to your invoice currency at month-end using the closing rate of the 1st of the month.
- **Fee:** Percentage of GGR, agreed at contract signing. Visible on every invoice.
- **Cycle:** Invoices issued on the 1st of each month for the previous calendar month.
- **Payment terms:** NET 14 unless otherwise specified in your MSA.
- **Disputes:** Email `billing@apogeetech.net` within 14 days of invoice. Apogee has per-round audit logs — any discrepancy can be traced back to the specific round and specific wallet call.
- **Tax:** Apogee invoices are gross; local withholding and indirect tax are your responsibility unless explicitly handled in the MSA.

## Data ownership

- **Player data** — you own it. Apogee never stores PII. The `playerId` you pass is opaque to us; we use it as a key, nothing else. `playerName` is optional and cached only for the duration of the session for display in chat.
- **Round data** — joint. Apogee retains round metadata (crash point, merchant ID, wagered, returned) for audit and billing. You retain the authoritative transaction record in your wallet.
- **Provably-fair seeds** — Apogee publishes server seed hashes in real-time and reveals seeds after the round. Full transparency, always.

## Compliance notes

- Apogee does not hold player funds. Your wallet is the ledger of record.
- Responsible gambling limits (deposit, loss, session) must be enforced **in your wallet**, not by the game.
- Geo restrictions (blocking disallowed jurisdictions) are your responsibility; Apogee will honor any `country` you pass to the session request but will not enforce blocks unless you ask for it.
- Apogee games have been designed with fairness reviewed by third-party auditors — certification packages available on request.

## Changing your setup

Anything about your merchant record can be changed with an email. Common changes:

| Want | Contact | Notes |
|---|---|---|
| New API key | security@apogeetech.net | 24h turnaround |
| Rotate existing key | security@apogeetech.net | Old key stays active for 72h |
| Update wallet URL | partners@apogeetech.net | Same day |
| Update webhook URL | partners@apogeetech.net | Same day |
| Change fee rate | partners@apogeetech.net | Requires addendum to MSA |
| Add a game to your catalog | partners@apogeetech.net | Same day (live games); beta games require opt-in |
| Enable a new currency | partners@apogeetech.net | Same day (config flip on our side) |
| Suspend temporarily | ops@apogeetech.net | Instant |
| Resume | ops@apogeetech.net | Instant |

## What you don't need to do

- **You do not host Apogee code.** There's nothing to deploy on your side except the iframe embed and your four wallet endpoints.
- **You do not access the Apogee admin panel.** That's for Apogee staff. Your visibility into Apogee's data comes through the API (`/v1/rounds`) and webhook events.
- **You do not manage game updates.** When Apogee ships a new version of Skyward, your iframe automatically serves the new version on the next launch. No action required.
- **You do not need to report round data to us.** Every round is tagged with your merchant ID automatically because we recognize the key on the session request.

## FAQ

**Q: Can I run Apogee games without Apogee's backend?**
No. The games are hosted by Apogee. You embed them via iframe.

**Q: Can I white-label?**
Yes, with an addendum. White-label involves adding your brand to the game chrome and removing Apogee branding. Discuss at contract signing.

**Q: Can I see my GGR in real time?**
Not directly. Apogee sends round-level webhooks if you configure a webhook URL, which gives you a real-time feed you can aggregate yourself. Monthly invoices are the authoritative billing number.

**Q: How are disputes between my wallet and Apogee's round log resolved?**
Apogee stores a signed audit log of every wallet call, including your response. If your records disagree, we can replay the exact request and show both sides of the conversation. In 99% of cases the discrepancy comes from a missed rollback on the operator side.

**Q: What happens if Apogee's API is down?**
Your wallet is the source of truth; no money is lost. Players see a "temporarily unavailable" screen until Apogee recovers. You should monitor Apogee status at `https://status.apogeetech.net` (once launched) and subscribe to incident updates.

---

Questions not answered here: **partners@apogeetech.net**