An official PHP SDK for seamless integration with Xsolla API. This SDK streamlines the implementation of payment processing, user authentication, and webhook handling in your PHP applications.
- Complete Payment UI Customization: Flexible token-based system for full control over the payment interface
- Comprehensive API Integration: Easy-to-use client for all Xsolla API methods, including:
- Virtual currency management
- Item and subscription handling
- User balance operations
- Financial reporting through Report API
- Advanced Webhook Processing:
- Simple single-callback implementation
- Built-in security features (signature authentication and IP whitelisting)
- Customizable notification handling logic
- Robust Architecture: Built on Guzzle v3, featuring:
- Persistent connections
- Parallel request processing
- Event-driven architecture
- Service descriptions
- Comprehensive logging
- Request caching
- Flexible batching
- Automatic retry mechanism
- PHP ^7.3 or ^8.0
- Required PHP extensions:
- curl
- json
- Register your Publisher Account
- Create a new project
- Obtain the following credentials from your Company Profile and Project Settings:
- MERCHANT_ID
- API_KEY
- PROJECT_ID
- PROJECT_KEY
The SDK includes Docker support for easy deployment and development. To get started:
-
Clone the repository:
git clone https://github.com/Luamtech/xsolla-sdk-php.git cd xsolla-sdk-php -
Configure your environment variables:
- Copy the example environment file:
cp .env.example .env
- Update the following variables in .env:
MERCHANT_ID=your_merchant_id API_KEY=your_api_key PROJECT_SECRET_KEY=your_project_secret_key
- Copy the example environment file:
-
Build and run with Docker Compose:
docker-compose up -d
The SDK will be available at http://localhost:9000.
You can check the container status using:
docker psExample output:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
91b72b0574c7 xsolla-sdk-php "docker-php-entrypoi…" 12 seconds ago Up 4 seconds (health: starting) 9000/tcp xsolla-sdk-php
The health status indicators help you monitor the container's state:
(health: starting): Container is initializing(healthy): Container is running properly(unhealthy): Container has failed health checks
The implemented healthcheck mechanism provides several advantages:
- Automatic monitoring of PHP-FPM service status
- Early detection of service failures
- Prevention of traffic routing to malfunctioning containers
- Facilitates automatic recovery and failover
- Enables container orchestration platforms to make informed scheduling decisions
- Provides visibility into container health without manual intervention
Docker environment features:
- PHP-FPM 7.3 (configurable via build args)
- Built-in health monitoring
- Volume mounting for development
- Automatic restart policy
- Optimized multi-stage build
composer require xsolla/xsolla-sdk-phpThen include the autoloader:
require 'vendor/autoload.php';<?php
use Xsolla\SDK\API\XsollaClient;
$client = XsollaClient::factory([
'merchant_id' => MERCHANT_ID,
'api_key' => API_KEY
]);
$paymentUIToken = $client->createCommonPaymentUIToken(
PROJECT_ID,
USER_ID,
$sandboxMode = true
);Implement in your HTML:
<html>
<head lang="en">
<meta charset="UTF-8">
</head>
<body>
<button data-xpaystation-widget-open>Buy Credits</button>
<?php \Xsolla\SDK\API\PaymentUI\PaymentUIScriptRenderer::send($paymentUIToken, $isSandbox = true); ?>
</body>
</html><?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Webhook\Message\NotificationTypeDictionary;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
switch ($message->getNotificationType()) {
case NotificationTypeDictionary::USER_VALIDATION:
// Handle user validation
break;
case NotificationTypeDictionary::PAYMENT:
// Process payment
break;
case NotificationTypeDictionary::REFUND:
// Handle refund
break;
default:
throw new XsollaWebhookException('Notification type not implemented');
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();When using Docker, you can run tests and development tools:
# Run tests
docker-compose exec xsolla-sdk-php vendor/bin/phpunit
# Install development dependencies
docker-compose exec xsolla-sdk-php composer install --dev
# Run code style checks
docker-compose exec xsolla-sdk-php vendor/bin/phpcsFor common issues and solutions, please refer to our troubleshooting guide.
Please read our CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
To expose your API at grindinggear.api.luam.tech through Nginx and forward traffic to the Docker container running on port 9000, follow these steps:
sudo apt install nginx
sudo apt install certbot python3-certbot-nginxsudo nano /etc/nginx/sites-available/apiserver {
listen 80;
server_name grindinggear.api.luam.tech;
location / {
proxy_pass http://localhost:9000;
proxy_set_header HOST $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}sudo ln -s /etc/nginx/sites-available/api /etc/nginx/sites-enabled/api
sudo systemctl restart nginxsudo nginx -tIf everything is correct, you should see:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
sudo certbot --nginx -d grindinggear.api.luam.techdocker psIf the status appears as (unhealthy), check the container logs:
docker logs xsolla-sdk-phpWith this configuration, Nginx will act as a reverse proxy for your API, making it accessible through HTTP.