Merchant setup

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, then write the credentials to .env at the end (Step 5).

---

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 = 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

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 any existing XSOLLA_* lines, then append fresh values
sed -i.bak '/^XSOLLA_/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

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
• .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.