Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

shop-setup

/shop-setup

Pomaga zbudować i wdrożyć sklep w kodzie lub osadzić Xsolla w istniejącym sklepie.

Repozytorium
xsolla-ai-kit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
6
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

build me a shopembed Xsolla in my store
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

  1. What is Headless Shop
  2. System Interaction (logical, not code)
  3. Integration Phases
  4. Decision Points for the Agent
  5. Anti-Patterns
Sekcje z nagłówków SKILL.md, w oryginale · 288 linii, 1 889 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.