headless-checkout-integration
Skill9 starsChanged 5 months agoMITView on GitHub
Integrates Xsolla Headless Checkout — a fully customizable, client-controlled payment UI built on the @xsolla/pay-station-sdk JavaScript SDK, where payment data stays isolated in secure iframes and payments run through Xsolla without the standard Pay Station.
- Reads credentials
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/xsolla-ai-kit.mdcCursor rule
- catalog-designSkill
- description-to-shopSkill
- game-web-portalSkill
- headless-checkout-integrationSkill
- login-setupSkill
- login-stylingSkill
- merchant-setupSkill
- nocode-shop-setupSkill
- productionSkill
- quest-setupSkill
- shop-builder-assemblySkill
- shopbuilder-translateSkill
- shop-setupSkill
- webhooks-implSkill
- xla-pagesSkill
- catalog-designSkill
- description-to-shopSkill
- game-web-portalSkill
- login-setupSkill
- login-stylingSkill
- merchant-setupSkill
- nocode-shop-setupSkill
- productionSkill
- quest-setupSkill
- shop-builder-assemblySkill
- shopbuilder-translateSkill
- shop-setupSkill
- webhooks-implSkill
- xla-pagesSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
Run merchant-setup first. The developer must have:
- Very specific: line 41
If credentials are missing, stop and complete merchant-setup first.
- Very specific: line 46
Every payment method — card, PayPal, QR, mobile, wallets — runs through the same shape: call form.init({ paymentMethodId, returnUrl }), …
- Distinctive: line 64
Do not attempt everything at once.
- Distinctive: line 77
Phase 3 — Additional methods, one type at a time: Add the handlers for redirect systems,
- Very specific: line 84
Phase 4 — Google Pay: Add the wallet button via the shared dispatcher (special_button), then ask the user to verify and give feedback …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
What this skill does
Integrates Headless Checkout into a custom checkout UI via @xsolla/pay-station-sdk,
running in sandbox. This is a big integration, so it is built one payment method at a
time (see Phases) until every method works. This file is a map and a sequence — the actual
how-to lives in references/; load only the reference the current phase needs.
Frontend only. It does not cover the production token backend (server-to-server) nor
webhook fulfillment — see webhooks-impl for granting items after order_paid.
When to use
The developer wants to accept a payment with their own checkout UI (not the hosted Pay Station) and is working in sandbox — standing up the integration from scratch, adding a method selector, adding a payment method (card, PayPal/APM, QR, mobile), adding the Google Pay / Apple Pay wallet buttons, or wiring payment country into the method list.
Prerequisites
Run merchant-setup first. The developer must have:
XSOLLA_MERCHANT_ID=<your merchant ID>
XSOLLA_PROJECT_ID=<your project ID>
XSOLLA_PROJECT_API_KEY=<your API key> # server-side / agent-side only — NEVER ship to the browserIf credentials are missing, stop and complete merchant-setup first. The only secret that
ever reaches the browser is the short-lived payment token — never the API key.
The one mental model: form.init() + one onNextAction dispatcher
Every payment method — card, PayPal, QR, mobile, wallets — runs through the same shape: call
form.init({ paymentMethodId, returnUrl }), render the server-driven fields, the user
submits, and the SDK drives a small state machine by emitting NextActions to your
onNextAction handler. React to whatever action arrives — never assume a fixed sequence, and
never switch on the payment method id. All flows converge on a final status view.
One dispatcher, keyed on nextAction.type, handles everything. Where each action is documented:
| NextAction(s) | Owned by reference |
show_fields, show_errors, 3DS, check_status | credit-card-form |
redirect | redirect-flow |
check_status, status_updated | payment-status |
special_button (wallets) | google-pay / apple-pay |
show_qr_code, show_mobile_payment_screen, show_cash_payment_instruction | payment-methods |
Phases — build incrementally, one method at a time
Do not attempt everything at once. Finish and test each phase in sandbox before the next.
Phase 1 — Credit card, end to end. Install + init({ sandbox: true }), mint a sandbox token
(no backend), build the card form from form.fields, handle the onNextAction chain, show the
status, and drive a real sandbox payment including 3DS + the return page.
→ initialization, credit-card-form, redirect-flow (3DS-via-redirect), payment-status.
Done when the three sandbox test cards pass (see credit-card-form → Testing).
Phase 2 — Payment method selection. Let the user pick a method instead of hardcoding the
card PID; hand the chosen paymentMethodId to form.init(). Choose a layout pattern (start with
a simple list; icons mandatory; wallets as branded buttons) and design back/retry navigation.
→ payment-methods-list. Done when selecting a method routes into its form.
Phase 3 — Additional methods, one type at a time. Add the handlers for redirect systems,
mobile, QR, cash. But sandbox runs only redirect PS for real — mobile/QR/cash collapse to
the generic sandbox flow (form → notice → success), so their real UIs are production-only.
Sandbox-test on PayPal (+ Venmo); code the rest to spec.
→ payment-methods (per-method NextAction; sandbox limits; PayPal/Venmo recipe), redirect-flow.
Done when PayPal (+ Venmo) reach a terminal status in sandbox and the other handlers are coded.
Phase 4 — Google Pay. Add the wallet button via the shared dispatcher (special_button),
then ask the user to verify and give feedback before continuing.
→ google-pay. Done when a sandbox Google Pay payment completes and the user confirms.
Phase 5 — Apple Pay. Same wallet pattern, then
ask the user to verify and give feedback.
→ apple-pay. Done when a sandbox Apple Pay payment completes and the user confirms.
Phase 6 — Saved methods. Let the user save a method while paying, show saved methods as the
first step on return visits (with "pay another way" fallback), pay with one (still
NextAction-driven — may need CVV / 3DS), and delete them.
→ saved-methods. Done when the sandbox round trip passes: save → see it → pay with it → delete.
Phase 7 — Payment country. Token country + store selector; pass ISO into methods /
form.init only after an explicit (or persisted) pick.
→ payment-country. Done when US vs JP lists differ after a pick and the choice
survives reload (IP auto-detect: developer checks on a real host).
End state: every payment method integrated and working in sandbox, with saving/reuse and
country-aware methods. Production / go-live is Phase 7 of shop-setup → skill
production (contract, flip sandbox, deploy, developer live tests).
Styling & UX — match the store, don't ship the demo look
Headless Checkout is an unstyled component library. The SDK examples use deliberately bare styles — never treat them as the target design. From Phase 1 onward, style the checkout to match the host store's own look (its colors, typography, radius, spacing, buttons) so it reads as part of the store, not a bolted-on widget. Do this from the start — restyling a finished flow is far more work than building it styled.
Apply real payment-UX best practices, not a naive one-input-per-field stack. This list is illustrative, not exhaustive — aim for a fast, low-friction, trustworthy checkout:
- Compact card entry. Present the card as one or two tight rows, not a tall accordion of full-width fields. Expiry (4 digits) and CVV (3) are tiny — put them side by side on one row with the card number; don't give each a full-width block.
- Auto-advance focus to the next field as one fills (number → expiry → CVV), and surface validation inline next to the field, not as a distant banner.
- Respect brand tokens, keep it responsive / mobile-first, use accessible labels, and show clear loading / disabled states while the SDK works.
The card inputs are cross-origin secure iframes — outer CSS cannot reach inside them, so
their styling goes through setSecureComponentStyles(css) before setToken(). Wrapper hosts
(psdk-card-number, psdk-text, …) are styled with normal CSS for layout/sizing. Both layers
and the mechanism live in credit-card-form → Secure Field Styling.
Testing is mandatory (every phase)
A payment integration is verified only by a completed sandbox transaction ending on a status
screen — not by "the form renders." Each phase ends with an observed transaction; the concrete
test recipe lives in the phase's reference (card test matrix + headless-driving tips in
credit-card-form; PayPal sandbox login in payment-methods; wallet notes in google-pay /
apple-pay). Report the terminal screen you actually observed. Driving it headlessly
(Playwright/Puppeteer)? Read references/testing.md first — the
cross-cutting gotchas (secure-field fill() vs keystrokes, submit-button host click, driver
artifact vs real bug) that otherwise eat hours.
References
Load only what the current phase needs.
references/documentation.md— navigation map: which official doc / GitHub example to load per task, full component table, SDK reference (README)references/demo-install.md—headless-checkout-demo(full React + Vite): the most complete example and fastest to access once installed (local file reads, no doc fetches), but requires cloning the repo locally and linking it to the agentreferences/initialization.md— install SDK,init({ sandbox: true })+setToken(), getting a sandbox payment token with no backendreferences/payment-methods-list.md—psdk-payment-methodsvs custom API,selectionChange, handoff toform.init(); layout patterns (list / accordion / tabs), method icons, wallet-button placement, back navigationreferences/payment-country.md— token country /X-User-Ip, store selector, when to pass ISO into methods /form.initreferences/credit-card-form.md— server-driven fields, field→component mapping,setupAndAwaitFieldsLoading, the NextActions, two 3DS paths, the sandbox test matrix + how to drive it headlesslyreferences/redirect-flow.md— all redirect mechanics:psdk-redirectvs manual form, GET/POST + 414, same-tab / new-tab / WebView window strategies + iframe caveat,isNewWindowRequired/isSameWindowRequired, new-tab gesture, return page (covers 3DS-via-redirect, e-wallets, extra verification)references/payment-status.md—check_status,psdk-statusvs custom UI, the **one **getStatus()rule,status_updated, return pagereferences/payment-methods.md— which method emits which NextAction; redirect systems (PayPal) + SDK / same-window methods, QR (show_qr_code), mobile (show_mobile_payment_screen); PayPal sandbox test recipereferences/google-pay.md— the Google Pay wallet button via the shared dispatcher: thespecial_buttonaction, theshow_fields(ZIP) step a bespoke screen would dropreferences/apple-pay.md— the Apple Pay wallet button: renders insidepsdk-submit-buttonautomatically (no new NextAction), desktop QR fallback, browser-support gating, domain registrationreferences/saved-methods.md— save a method while paying (allowSavefield /savePaymentMethod), detect + show saved methods first (getSavedMethods,psdk-saved-methods), pay with one (paymentWithSavedMethod+savedMethodId, still NextAction-driven), and delete (delete-mode)references/testing.md— headless sandbox testing gotchas: secure-fieldfill()vs real keystrokes (opposite per field), thepsdk-submit-buttonhost click + retry, telling a driver artifact from a real bug
Agent test (reference run)
Prompt: "Integrate Xsolla Headless Checkout into my web app and let me pay with a credit card in
sandbox." Expected: the agent follows Phase 1 — reads SKILL.md, pulls initialization,
credit-card-form, redirect-flow, and payment-status as each step needs them; installs
@xsolla/pay-station-sdk; initializes with sandbox: true; mints a sandbox token; builds the
card form from form.fields; handles the full onNextAction chain; and passes the three
sandbox test cards (incl. the 3DS return page) on a real run. ✅
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

