shop-setup
/shop-setup
Pomaga zbudować i wdrożyć sklep w kodzie lub osadzić Xsolla w istniejącym sklepie.
- Autor
- xsolla ↗
- Repozytorium
- xsolla-ai-kit ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 6
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Pomaga zbudować i wdrożyć sklep w kodzie lub osadzić Xsolla w istniejącym sklepie.
Wyzwalacze z opisu
Oryginalny opis (EN)
A shop the user codes, reviews, and deploys, or Xsolla embedded in a shop the user already built. Use for "build me a shop" when the user or the agent will write the code, or "embed Xsolla in my store". A local repo makes this more likely; a shop in it, more still; Xsolla already there means this skill. If the user will not write and deploy, open nocode-shop-setup.
Jak działa
- What is Headless Shop
- System Interaction (logical, not code)
- Integration Phases
- Decision Points for the Agent
- Anti-Patterns
Podgląd SKILL.md
---
name: shop-setup
description: >-
A shop the user codes, reviews, and deploys, or Xsolla embedded in a shop the
user already built. Use for "build me a shop" when the user or the agent will
write the code, or "embed Xsolla in my store". A local repo makes this more
likely; a shop in it, more still; Xsolla already there means this skill. If
the user will not write and deploy, open nocode-shop-setup.
metadata:
owner: y-klochikhin
domain: orchestrator
---
# Xsolla Headless Shop — Architecture Overview
If the user does not want to write, review, and deploy the shop code, stop and open `nocode-shop-setup`.
If the user has not said which they want, show **Shop building paths** in `AGENTS.md`
and ask.
## What is Headless Shop
A custom game store assembled from individual Xsolla products and integrated
into the partner's own site with the help of AI. The partner writes the
frontend; Xsolla provides backend services and SDKs.
**Four components:**
| Component | Role |
|-----------|------|
| **Login** | Player identity — authentication, JWT, social login, game ID binding |
| **Store API** | Commerce backend — catalog, cart, orders, promos, inventory, virtual currency |
| **Headless Checkout SDK** ⭐ | Embedded payment UI on the partner's site — **recommended for Headless Store** |
| **Pay Station** | Xsolla-hosted payment page — fallback when embedded UI is not needed |
> **Headless Checkout SDK** (`github.com/xsolla/pay-station-sdk`) is the
> **recommended payment layer for this integration type.** It renders the full
> payment UI directly on the partner's site without redirecting the player
> elsewhere — the natural fit when AI is already building the entire storefront.
> Pay Station redirect is a valid fallback but not the default choice here.
---
## System Interaction (logical, not code)
```
Partner's site
│
├── Store API ──────────────────── catalog, cart, orders, promos, inventory
│ │
│ └── Login (JWT) ────────── authenticated cart, user balance, personal limits
│
└── Headless Checkout SDK ──────── embedded payment UI on partner's site
│
└── Webhook ────────────── partner's backend ← fulfillment trigger
```
**Data flow for a purchase:**
1. Player browses catalog → Store API (no auth required)
2. Player adds to cart → Store API (guest or JWT)
3. Player logs in → Login issues JWT → cart switches to Bearer mode
4. Checkout: Store API creates payment token → Headless Checkout SDK (or Pay Station) handles payment
5. Payment confirmed → **Xsolla sends webhook to partner's backend** → partner grants item in game
---
## Integration Phases
The agent builds bottom-up: data first, then identity, then payment.
When an orchestrated step needs the publisher's local merchant and project
settings, reuse `merchant-setup`'s project-local `XSOLLA_MERCHANT_ID`,
`XSOLLA_PROJECT_ID`, and `XSOLLA_PROJECT_API_KEY` configuration. Read `.env`
as text without exposing values, and keep credentials out of generated
storefront code. Follow each API's own authentication contract.
### Phase 0 — Prerequisites (Publisher Account, no frontend)
**Goal:** Store project with catalog exists before any UI.
- Create Store project → get `projectId`
- Create catalog entities: virtual items, virtual currency, bundles, game keys, groups, prices, limits
- Link Login project to Store project
- Record: `merchantId`, `projectId`, `loginProjectId`, `cartId`
**Nothing to build on the frontend yet. Without this, all API calls return empty or errors.**
---
### Phase 1 — Catalog (Store API, read-only)
**Goal:** player sees items without logging in.
- Fetch catalog via Store API v2 by `projectId` and `locale`
- No `Authorization` header for public storefront
- Display prices, currencies, item limits; filter by group
**Validate:** catalog loads without JWT; locale changes item names; no errors.
---
### Phase 2 — Cart (Store API)
**Goal:** player accumulates items before checkout.
- One `cartId` per store
- Guest cart: all requests with header `x-unauthorized-id` (stable UUID in `localStorage`)
- Operations: get, add/update/remove item, clear, fill (bulk)
**Validate:** add item → reload page → cart persists; clear works.
---
### Phase 3 — Login (player identity)
**Goal:** player can log in; store knows who they are.
- Integrate Login project (`loginProjectId`) → `login-setup`
- Options: Login widget, OAuth2 redirect, custom game User ID via partner backend
- On success: store JWT (cookie or memory); on logout: clear JWT
- **Style the Login UI to match the shop** → `login-styling` (don't ship the stock widget look)
**What changes in Store after login:**
- Cart: switch from `x-unauthorized-id` to `Authorization: Bearer JWT`
- **Merge:** carry guest cart line items into the authenticated cart
- Refetch catalog and cart — personal limits, country pricing, eligibility now apply
**Validate:** login → cart preserved; logout → guest mode; re-login → account cart restored.
---
### Phase 4 — Personal Store features (requires JWT)
**Goal:** account-level commerce mechanics.
Implement after Phase 3, only what the product needs:
- Virtual currency balance (buy with VC)
- Inventory / unclaimed rewards
- Promo codes: verify / redeem / remove
- Reward chains, free items
All requests: Store API + `Bearer JWT`.
---
### Phase 5 — Payment (Headless Checkout SDK or Pay Station)
**Goal:** player completes real-money purchase.
#### Step 1 — Get payment token
The token is always obtained via a backend HTTP call — **never generated on the frontend.** Three methods exist; choose based on context:
| # | Method | Who calls | When to use | Docs |
|---|--------|-----------|-------------|------|
| **1** | `POST https://store.xsolla.com/api/v2/project/{id}/payment/cart/{cartId}` | Browser → Store API directly | **Default for Headless Store / AI build** — no partner backend needed. Full Store lifecycle: cart validated → order created → token returned. | - |
| **2** | `POST https://store.xsolla.com/api/v3/project/{id}/admin/payment/token` | Partner's backend → Store API (admin auth, S2S) | Production setup where checkout must go through partner's server. Same internal Store logic as method 1, different call architecture. | https://developers.xsolla.com/api/catalog/payment-server-side/admin-create-payment-token |
| **3** | `POST https://api.xsolla.com/merchant/v2/merchants/{id}/token` | Partner's backend → Merchant API | No Store catalog needed; simple amount + description; maximum `token_data` control. Use when Store API is not part of the integration. | https://developers.xsolla.com/payment-ui-and-flow/payment-ui/how-to-get-payment-token/ |
Methods 1 and 2 both return `{ token, order_id }` and include full Store order lifecycle (SKU validation, promo redemption, inventory reservation). Method 3 returns `{ token }` only — no Store order, no SKU validation.
**Default for this integration: Method 1** (browser calls Store API, no backend setup required).
#### Step 2 — Open payment UI
- **Headless Checkout SDK ⭐ (recommended):** pass token to the SDK → payment UI renders embedded on partner's site, player never leaves
- **Pay Station (fallback):** pass token to `openPayStationWidget()` or redirect URL → player pays on Xsolla-hosted page
**Validate:** payment token received; payment UI opens; test payment completes in sandbox.
#### Payment UI language (`settings.language`)
Supported codes:
[Pay Station localization](https://developers.xsolla.com/payment-ui-and-flow/payment-ui/localization/index.md)
(default when omitted by Xsolla: `en`). Pass the code in the token payload as
`settings.language` (Methods 1–3).
**Headless Checkout — always set the shop language on the token.** Do not rely on
IP/geo detection: Headless has no in-UI locale picker like Pay Station, so a wrong
token language leaves the payment UI out of sync with the storefront.
| Shop setup | What to put in `settings.language` |
|------------|------------------------------------|
| Single language | That language on every token |
| Locale switcher / multi-language | Current shop locale on each token create |
| Shop locale **not** in the Xsolla list above | `en` |
Match the same code in `headlessCheckout.init({ language })`.
**Pay Station — optional.** You may set `settings.language` or omit it. Pay Station
detects locale on its own and lets the player change language in the hosted UI.
> Japanese IP note (Xsolla rule): a Japanese client IP forces Japanese in the
> payment UI regardless of `settings.language`.
---
### Phase 6 — Webhook (partner's backend, fulfillment)
**Goal:** grant purchased item to the player in the game.
After a successful payment — whether through Headless Checkout SDK or Pay Station — **Xsolla sends a webhook to the partner's backend**. The partner must:
- Expose an HTTPS endpoint registered in Publisher Account
- Verify the signature over the **raw** body: `lowercase(sha1(rawBody + secret))`, compared in constant time — plain SHA-1 with the secret **appended**, **not** HMAC-SHA1 → `webhooks-impl`
- Handle the fulfillment event for the token method in use: `order_paid` (Methods 1–2 — items in `items[]`, player in `user.external_id`) or `payment` (Method 3 — items usually in `custom_parameters`, player in `user.id`); when both arrive (separate delivery), grant on `order_paid` only
- Grant the item/currency/key in the partner's game system, idempotently by transaction id
- Respond `2xx` (`200`/`201`/`204`) to acknowledge receipt; `400` + `INVALID_SIGNATURE` on a mismatch
**This step is required for real-money purchases.** Without it, payment succeeds on Xsolla's side but the player receives nothing in the game.
**Validate:** trigger a test payment → webhook received → item granted in game system.
---
### Phase 7 — Production / go-live → `production`
**Goal:** accept real money; leave sandbox.
- Sign Licensing Agreement (+ tax interview) in PA — see `production`
- Flip env/config (`XSOLLA_SANDBOX` / token `sandbox` / SDK `sandbox: false`); keep a
toggle for quick environment switching
- Deploy public HTTPS shop + webhook URL
- **Developer** runs live tests (agent cannot): min-amount card, Finance tx, fulfillment,
PayPal / Google Pay / Apple Pay, canceled payment → failed
**Validate:** developer sign-off on the `production` checklist (utils OK without
`00020004`, live card + goods granted, wallets smoked, failed path works).
---
## Decision Points for the Agent
**Optional in-catalog quests (headless shop):** if the publisher asks for an
optional quest section inside the existing catalog/product layout (not a
navigation tab), follow `quest-setup` and its
[`references/web-shop-module.md`](../quest-setup/references/web-shop-module.md).
Keep the full implementation recipe in `quest-setup`.
**Which payment UI to use:**
```
Headless Store / AI-assembled storefront?
└── DEFAULT → Headless Checkout SDK (embedded, player stays on partner's site)
Partner explicitly wants Xsolla-hosted payment page?
└── Pay Station (redirect)
```
**Payment UI language:**
```
Headless Checkout?
└── ALWAYS set settings.language = shop locale (or en if unsupported)
├── one shop language → that code every time
└── locale picker → pass current shop locale into each token
Pay Station?
└── optional — may set settings.language or omit (PS detects + user can change)
```
**Which token method to use:**
```
Does the partner have a backend server for checkout?
├── NO → Method 1 (default): browser calls POST /v2/project/{id}/payment/cart/{cartId}
├── YES → Method 2: server calls POST /v3/project/{id}/admin/payment/token (S2S, admin auth)
└── No Store catalog at all → Method 3: POST /merchant/v2/merchants/{id}/token (Merchant API)
```
**What to build next (if starting from scratch):**
```
Phase 0 done? → no: set up catalog in Publisher Account first
Phase 1 done? → no: implement catalog read
Phase 2 done? → no: implement guest cart
Phase 3 done? → no: integrate Login
Phase 4 needed? → check product requirements
Phase 5 done? → no: implement payment token + payment UI
Phase 6 done? → no: implement webhook handler on partner backend
Phase 7 done? → no: go live — `production` (contract, flip sandbox, deploy, live test)
```
---
## Anti-Patterns
1. **Don't skip Phase 0** — no catalog in PA = empty store regardless of frontend quality.
2. **Don't require login to browse** — catalog and guest cart work without JWT.
3. **Don't open Pay Station / Headless Checkout before cart is validated** — phases must go in order.
4. **Don't generate payment token on the frontend** — only receive it via HTTP call and pass to SDK/widget.
5. **Don't skip webhook handler** — payment success without webhook = player paid, received nothing.
6. **Don't use Merchant API token for free cart or virtual currency purchases** — wrong endpoint.
7. **Don't claim production is done from sandbox alone** — live card/wallet tests are
developer-only; see Phase 7 / `production`.
8. **Don't omit `settings.language` for Headless Checkout** — IP-based language will
desync the payment UI from the shop; always pass the shop locale (fallback `en`).
Wersje
W bazie nie ma innych skilli o nazwie shop-setup.
Migawka bazy z 13.11.2026 · wersja paczki 3021504481c1 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100nocode-shop-setup
Buduje sklep internetowy dla gry w Shop Builder Xsolla bez kodu i wdrożeń, instaluje CLI Xsolla, a logowanie wykonuje użytkownik. - 87shop-plan
Dobiera ścieżkę budowy sklepu Xsolla: bez interfejsu lub Shop Builder, a przy Shop Builderze także rodzaj strony, i zapisuje decyzję. - 96init-vercel-shop
Tworzy nowy sklep internetowy z szablonu vercel/shop w Next.js przez narzędzie create-next-app. - 100update-shop
Aktualizuje sklep Vercel Shop do nowszego szablonu, sprawdza rozjazd z szablonem i planuje wdrożenie zmian. - 86build-store
Buduje kompletny sklep internetowy z lokalnym podglądem i symulowaną płatnością, zaczynając od gotowego projektu referencyjnego. - 100setup-shop
Konfiguruje etsy-pod-agent jednorazowo: plik config.toml, połączenie z Etsy i drukarnią oraz szablony mockupów.