Xsolla SDK for PHP (unofficial mirror)

Note: This is an unofficial mirror of xsolla/xsolla-sdk-php v4.3.2 (commit 6bea126a37e7f1a419e61418a7b35cbb04475e33, released 2024-05-23). The original repository was removed from GitHub by Xsolla; this copy was recovered from a Composer vendor directory and is preserved here under the terms of its MIT license. This project is not affiliated with or endorsed by Xsolla.

A PHP SDK for interacting with Xsolla API

This SDK can be used for:

• obtaining an authorization token
• processing of basic webhooks (user_validation, payment, refund, etc.)

Features

• Full customisation of Payment UI with the help of different methods of getting token.
• Client for all API methods, making your integration easy and convenient. You can use it for setting up and updating virtual currency, items and subscription plans, for managing the users balance, for checking the finance information with the help of Report API and so on.
• Convenient webhook server:
  • To start you need only one callback function.
  • All security checking already implemented: signature authentication and IP whitelisting.
  • Full customisation of notification processing logic, if standard server class doesn’t suit you.
• SDK is built on Guzzle v3, and utilizes many of its features, including persistent connections, parallel requests, events and plugins (via Symfony2 EventDispatcher), service descriptions, over-the-wire logging, caching, flexible batching, and request retrying with truncated exponential back off.

Requirements

• PHP ^7.3 or ^8.0
• The following PHP extensions are required:
  • curl
  • json

Getting Started

Please register your Publisher Account and create the project. In order to use the PHP SDK Library you'll need:

• MERCHANT_ID
• API_KEY
• PROJECT_ID
• PROJECT_KEY

You can obtain these parameters using the information in your Company Profile and Project Settings.

Installation

Installing via Composer

Since the upstream package is no longer available, point Composer at this repository in your project's composer.json:

{
    "repositories": [
        { "type": "vcs", "url": "git@github.com:Shinobit/xsolla-sdk-php.git" }
    ]
}

Then require the package:

$ cd /path/to/your/project
$ composer require xsolla/xsolla-sdk-php

After installing, you need to require Composer's autoloader:

require '/path/to/vendor/autoload.php';

Quick Examples

Receive webhooks

There is a build in server class to help you to handle the webhooks.

Solution with webhook server:

<?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:
            /** @var Xsolla\SDK\Webhook\Message\UserValidationMessage $message */
            // TODO if user not found, you should throw Xsolla\SDK\Exception\Webhook\InvalidUserException
            break;
        case NotificationTypeDictionary::PAYMENT:
            /** @var Xsolla\SDK\Webhook\Message\PaymentMessage $message */
            // TODO if the payment delivery fails for some reason, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
            break;
        case NotificationTypeDictionary::REFUND:
            /** @var Xsolla\SDK\Webhook\Message\RefundMessage $message */
            // TODO if you cannot handle the refund, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
            break;
        default:
            throw new XsollaWebhookException('Notification type not implemented');
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

Solution with just helper classes in some php function:

public function handleRequest()
{
    $request = Request::createFromGlobals();
    $message = Message::fromArray($request->toArray());

    switch ($message->getNotificationType()) {
        case NotificationTypeDictionary::USER_VALIDATION:
            /**
             * https://developers.xsolla.com/webhooks/operation/user-validation/
             * @var Xsolla\SDK\Webhook\Message\UserValidationMessage $message 
             */
            if ($message->getUserId() !== 'our_user_id') {
                return YourResponseClass(json_encode(['error' => ['code' => 'INVALID_USER', 'message' => 'Invalid user']]), 400);
            }
            
            break;
        case NotificationTypeDictionary::PAYMENT:
            /** @var Xsolla\SDK\Webhook\Message\PaymentMessage $message */
            break;
        case NotificationTypeDictionary::REFUND:
            /** @var Xsolla\SDK\Webhook\Message\RefundMessage $message */
            break;
        default:
            throw new \Exception('Notification type not implemented');
    }
    
    return YourResponseClass('', 200);
}

Once you've finished the handling of notifications on your server, please set up the URL that will receive all webhook notifications on the Settings page for your project.

Troubleshooting

You can find solutions for the most frequently encountered errors in our documentation.

Contributing

Please take a look at the CONTRIBUTING.md to see how to get your changes merged in.

Additional resources

• Website
• Documentation
• Status
• Support and Feedback