merchant-setup
Skill9 starsChanged 5 months agoMITView on GitHub
Guide for a merchant or developer setting up an Xsolla Account and obtaining API credentials. Use when the user needs that account, API keys, merchant-level versus project-level keys, sandbox mode, to accept payments, to start an Xsolla integration, or to test payments. The agent cannot create the account. This skill gives the exact steps the user completes manually.
- 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
- 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
- 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
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 78
If the user doesn't share a URL, tell them:
- Very specific: line 102
Only needed for Xsolla CLI or API calls where the endpoint URL has no project_id path parameter.
- Very specific: line 107
Rule of thumb: if the API endpoint URL contains {project_id}, use the project-level key.
- Very specific: line 117
When going live, the only change needed is switching the mode from sandbox to production in the integration.
- Distinctive: line 177
After writing, confirm to the user:
≈ “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
Merchant Setup
AI Agent cannot create an Xsolla account automatically. The user must complete the registration steps manually.
Step 0: Check for Existing Credentials
Before anything else, check for a .env file in the project root:
# Check if .env exists and contains Xsolla variables
cat .env 2>/dev/null | grep -E "XSOLLA_MERCHANT_ID|XSOLLA_PROJECT_ID|XSOLLA_PROJECT_API_KEY"If all three variables are present and non-empty — credentials are already configured. Report them to the user (show names and values, except mask the API key as ****) and proceed directly with the integration. Skip all steps below.
✅ Found in .env:
XSOLLA_MERCHANT_ID=887981
XSOLLA_PROJECT_ID=308077
XSOLLA_PROJECT_API_KEY=**** (set)If the file is missing or any variable is absent — walk the user through the steps below.
Where the key lives:
- A shop the user codes (
shop-setup) has a project directory. Write the merchant id, project id, and project API key to.env(Step 5). That file is for the application. - A shop on Xsolla's side with no project directory (
nocode-shop-setup) has nowhere to put.env. Do not create one. Ask the user to generate a separate project API key for this chat, paste it here, and delete that key in Publisher Account when setup is finished. Do not reuse the key a live project already uses. Hold it in the conversation for the calls, and do not write it to a file. - Pasting a key into chat is a stopgap. The durable replacement is an Xsolla MCP that acts as the signed-in user. It is not available for these calls yet. When the agent can run the Xsolla CLI, Shop Builder calls use
xsolla auth logininstead of a pasted project key. Never ask the user to paste a session token. - When
xsolla auth loginreports that it created a Store API key for the project and saved it to the keychain, CLI commands use that key. Don't ask the user for a key and don't copy it into.envor the chat. Check it with one read-only catalog command for this project. If that read returns 401,auth loginmade no key for this project (seen after switching projects). Create one project key withxsolla publisher create-api-key(confirm it withxsolla publisher --help), write it to.envin the folder the CLI runs from, as in Step 5 (the CLI reads it there), and continue. Create one key per project, not one per run.
Step 1: Create a Publisher Account
Direct the user to: https://publisher.xsolla.com/signup
Individual vs. Company account
| Individual | Company | |
| When to use | Just testing, evaluating Xsolla, quick sandbox setup | Committed to going live, need a contract |
| Registration | Simple — email, Google, or social login | Requires company details for the licensing agreement |
| Contract | Still needed for live payments, but can skip for sandbox | Submit from the Agreements tab once ready |
For pure exploration and sandbox testing, an individual account is the fastest path. The user can always add company details later when submitting the licensing agreement.
Publisher Account uses two-factor authentication. Confirmation code is sent to the registered email.
Step 2: Extract IDs from a Publisher Account URL
The user doesn't need to hunt for IDs — they're embedded in every Publisher Account URL. Parse them directly if the user shares a link.
URL pattern:
https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/...Examples:
https://publisher.xsolla.com/887981/settings/api_key→ merchant_id = 887981https://publisher.xsolla.com/887981/projects/308077/edit/api_key→ merchant_id = 887981, project_id = 308077
If the user doesn't share a URL, tell them:
- Merchant ID: visible in the URL on any Publisher Account page, or under
Company settings → Company - Project ID: visible in the sidebar next to the project name, or in the URL when inside a project
Step 3: Generate a Project-Level API Key
⚠️ Critical: The API key is shown only once at creation time. It is never sent by email. The user must copy and save it immediately — it cannot be recovered.
For standard integration, the project-level key is sufficient.
- Location:
Project settings → API key - Direct URL:
https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/edit/api_key - Scope: this project only
- Auth format:
Authorization: Basic Base64({project_id}:{api_key})
To generate:
- Open the URL above (with the real IDs)
- Click Create
- Copy and store the value immediately
Merchant-level API key (optional)
Only needed for Xsolla CLI or API calls where the endpoint URL has no project_id path parameter.
- Location:
Company settings → API keys→https://publisher.xsolla.com/{merchant_id}/settings/api_key - Auth format:
Authorization: Basic Base64({merchant_id}:{api_key})
Rule of thumb: if the API endpoint URL contains {project_id}, use the project-level key. If it doesn't, use the merchant-level key.
Step 4: Sandbox Mode — No Contract Needed
ℹ️ Development can start immediately after account creation — no signed contract required.
A project-level API key is all that's needed to run a full sandbox integration: create tokens, test the payment UI, configure the catalog.
When going live, the only change needed is switching the mode from sandbox to production in the integration. Everything else stays the same.
What requires a signed licensing agreement (submit from the Agreements tab in Publisher Account):
- Accepting real payments from end users
- Completing the Tax Interview (W-8 for non-US / W-9 for US)
Contract review typically takes a few business days — submit it well before the planned launch date.
Full go-live checklist (utils probe, flip sandbox flags, deploy, live payment tests): production.
Quick Reference
| Resource | URL |
| Sign up | https://publisher.xsolla.com/signup |
| Publisher Account | https://publisher.xsolla.com |
| API Reference | https://developers.xsolla.com/api |
| Getting started guide | https://developers.xsolla.com/get-started/work-in-pa/create-first-project/ |
| FAQ — API keys | https://developers.xsolla.com/dev-resources/faq/general/#faq_project_settings |
Step 5: Write Credentials to .env
Once all credentials are confirmed, write them to .env in the project root. Use the XSOLLA_* variable names — other skills depend on these exact names.
If .env already exists, append or update only the Xsolla variables without touching existing content:
# Remove only this skill's own three keys. Deleting every ^XSOLLA_ line also erases
# keys this skill does not own.
sed -i.bak -E '/^XSOLLA_(MERCHANT_ID|PROJECT_ID|PROJECT_API_KEY)=/d' .env && rm .env.bak
cat >> .env << EOF
# Xsolla credentials
XSOLLA_MERCHANT_ID={merchant_id}
XSOLLA_PROJECT_ID={project_id}
XSOLLA_PROJECT_API_KEY={api_key}
EOFIf .env does not exist, create it:
cat > .env << EOF
# Xsolla credentials
XSOLLA_MERCHANT_ID={merchant_id}
XSOLLA_PROJECT_ID={project_id}
XSOLLA_PROJECT_API_KEY={api_key}
EOFThen make the file readable only by its owner. The Xsolla CLI ignores a .env that
other users can read, with only a warning:
chmod 600 .envAfter writing, confirm to the user:
✅ Written to .env:
XSOLLA_MERCHANT_ID={merchant_id}
XSOLLA_PROJECT_ID={project_id}
XSOLLA_PROJECT_API_KEY=****⚠️ Remind the user to add
.envto.gitignoreif it isn't there already — the API key must not be committed to version control.
grep -q "^\.env" .gitignore 2>/dev/null || echo ".env" >> .gitignoreChecklist
.envchecked for existing credentials (Step 0)- Publisher Account created (individual or company)
- Merchant ID known
- Project ID known
- Project-level API key generated and saved securely
- Credentials written to
.env, with mode 600 .envadded to.gitignore- (Optional) Merchant-level API key saved — only needed for CLI or cross-project API calls
Once credentials are in .env, proceed with the integration.
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.

