agentleFS
xsollaxsolla/xsolla-ai-kit/skills/merchant-setup/SKILL.md

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

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
  1. Distinctive:

    If the user doesn't share a URL, tell them:

    line 78
  2. Very specific:

    Only needed for Xsolla CLI or API calls where the endpoint URL has no project_id path parameter.

    line 102
  3. Very specific:

    Rule of thumb: if the API endpoint URL contains {project_id}, use the project-level key.

    line 107
  4. Very specific:

    When going live, the only change needed is switching the mode from sandbox to production in the integration.

    line 117
  5. Distinctive:

    After writing, confirm to the user:

    line 177

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 login instead of a pasted project key. Never ask the user to paste a session token.
  • When xsolla auth login reports 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 .env or the chat. Check it with one read-only catalog command for this project. If that read returns 401, auth login made no key for this project (seen after switching projects). Create one project key with xsolla publisher create-api-key (confirm it with xsolla publisher --help), write it to .env in 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

IndividualCompany
When to useJust testing, evaluating Xsolla, quick sandbox setupCommitted to going live, need a contract
RegistrationSimple — email, Google, or social loginRequires company details for the licensing agreement
ContractStill needed for live payments, but can skip for sandboxSubmit 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 = 887981
  • https://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:

  1. Open the URL above (with the real IDs)
  2. Click Create
  3. 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


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}
EOF

If .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}
EOF

Then 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 .env

After 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 .env to .gitignore if it isn't there already — the API key must not be committed to version control.

grep -q "^\.env" .gitignore 2>/dev/null || echo ".env" >> .gitignore

Checklist

  • .env checked 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
  • .env added 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.