엑솔라 SDK

PHP SDK

엑솔라 PHP SDK는 엑솔라 API와 상호 작용하기 위한 오픈 소스 라이브러리입니다. GitHub에서 이 프로젝트에 대한 링크는 이곳에서 확인할 수 있습니다.

특징

  1. 다양한 토큰 가져오기 수단을 이용하여 완전한 사용자 설정이 가능한 결제 UI.
  2. 모든 API 메소드에 대한 클라이언트로 통합이 간편함. 가상 통화, 아이템, 구독 요금제의 설정 및 업데이트, 사용자 잔고 관리, 보고서 API를 통한 재무 정보 확인 등에 사용할 수 있습니다.
  3. 편리한 웹훅 서버:
    • 콜백 함수 하나만으로 시작 가능.
    • 서명 인증 및 IP 허용 목록 등 모든 보안 확인 기능이 이미 적용됨.
    • 표준 서버 클래스가 부적합할 경우 알림 처리 논리의 사용자 설정 가능.
  4. SDK는 Guzzle v3에 구축되어 있으며 지속 연결, 병렬 요청, 이벤트 및 플러그 인(Symfony2 EventDispatcher 사용), 서비스 안내, over-the-wire logging, 캐싱, 유동적 일괄 처리, truncated exponential back off로 요청 재시도 등 다양한 기능을 사용합니다.

시작하기

판매자 계정 을 등록하고 프로젝트를 생성합니다. PHP SDK 라이브러리 사용을 위해 필요한 파라미터:

  • MERCHANT_ID
  • API_KEY
  • PROJECT_ID
  • PROJECT_KEY

이러한 매개변수는 회사 설정 및 프로젝트 설정에 있는 정보를 사용해 얻을 수 있습니다.

시스템 요구사항

  • PHP 5.3.9+
  • 다음과 같은 PHP 확장이 필요합니다:
    • curl
    • json

설치

엑솔라 PHP SDK는 Composer를 통해 설치하는 것이 좋습니다.

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

다른 설치 방법에 관해서는 GitHub project site를 참조하십시오.

사용법

토큰 가져오기

결제 UI를 게임과 통합하려면 액세스 토큰을 얻어야 합니다. 액세스 토큰은 게임, 유저, 구매 매개변수를 식별하는 문자열입니다.

토큰을 가져오는 방법은 여러가지 있습니다. 가장 쉬운 방법은 createCommonPaymentUIToken 메소드를 사용하는 것으로서, 엑솔라 시스템 내 프로젝트 ID와 게임 내 유저 ID만 전달하면 됩니다:

use Xsolla\SDK\API\XsollaClient;

$client = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$paymentUIToken = $client->createCommonPaymentUIToken(PROJECT_ID, USER_ID,
$sandboxMode = true);

Json안에 더 많은 매개변수를 추가하여 요청하실 수 있습니다:

<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;


$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

결제 UI를 여는데 필요한 사용자 정의 매개변수(예: “settings.ui.theme”)를 일부 사용하려는 경우 다음 예제를 사용할 수 있습니다.

<?php

use Xsolla\SDK\API\XsollaClient;

$tokenContent = array (
    'user' =>
        array (
            'id' =>
                array (
                    'value' => '1234567',
                    'hidden' => true,
                )
        ),
    'settings' =>
        array (
            'project_id' => 14004,
            'ui' =>
                array(
                    'theme' => 'default_dark'
                )
        )
);


$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$response = $xsollaClient->CreatePaymentUIToken(array('request' => $tokenContent));
$token = $response['token'];

결제 UI 연동(페이 스테이션)

다음 코드를 사용해 결제 UI를 개발자 페이지에 추가할 수 있습니다.

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

결제 UI 통합과 관련한 더 상세한 정보 및 추가 예제를 알아보려면 이 링크를 클릭하십시오.

웹훅 수신하기

웹훅 처리에 도움을 주기 위한 내장형 서버 클래스가 있습니다.

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    switch ($message->getNotificationType()) {
        case Message::USER_VALIDATION:
            /** @var Xsolla\SDK\Webhook\Message\UserValidationMessage $message */
            // TODO if user not found, you should throw Xsolla\SDK\Exception\Webhook\InvalidUserException
            break;
        case Message::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 Message::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();

표준 서버 클래스가 적합하지 않을 경우, 자체적으로 만들 수 있습니다:

<?php

use Xsolla\SDK\Webhook\WebhookRequest;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Webhook\WebhookResponse;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$httpHeaders = array();//TODO fetch HTTP request headers from $_SERVER or apache_request_headers()
$httpRequestBody = file_get_contents('php://input');
$clientIPv4 = $_SERVER['REMOTE_ADDR'];
$request = new WebhookRequest($httpHeaders, $httpRequestBody, $clientIPv4);
//or $request = WebhookRequest::fromGlobals();

$this->webhookAuthenticator->authenticate($request, $authenticateClientIp = true);// throws Xsolla\SDK\Exception\Webhook\XsollaWebhookException

$requestArray = $request->toArray();

$message = Message::fromArray($requestArray);
switch ($message->getNotificationType()) {
    case Message::USER_VALIDATION:
        /** @var Xsolla\SDK\Webhook\Message\UserValidationMessage $message */
        $userArray = $message->getUser();
        $userId = $message->getUserId();
        $messageArray = $message->toArray();
        // TODO if user not found, you should throw Xsolla\SDK\Exception\Webhook\InvalidUserException
        break;
    case Message::PAYMENT:
        /** @var Xsolla\SDK\Webhook\Message\PaymentMessage $message */
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $messageArray = $message->toArray();
        // TODO if the payment delivery fails for some reason, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
        break;
    case Message::REFUND:
        /** @var Xsolla\SDK\Webhook\Message\RefundMessage $message */
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
        break;
    default:
        throw new XsollaWebhookException('Notification type not implemented');
}

일단 서버의 알림 메시지 처리가 끝났다면, 해당 프로젝트의 설정 페이지에서 모든 웹훅 알림을 수신할 URL를 설정합니다.

테스트를 통과하였다면 실제로 구동할 준비가 된 것입니다. 샌드박스 매개변수를 사용했다면, 반드시 코드에서 제거하도록 하십시오.

문제 해결

여기에는 엑솔라 PHP SDK에서 반환하는 가장 자주 발생하는 오류를 처리하고 방지하기 위한 몇 가지 팁이 나와 있습니다.

[curl] 77: 오류 설정 인증서 확인 위치: CAfile

엑솔라 PHP SDK를 사용하여 당사 서버에 요청을 보낼 때 이러한 유형의 오류가 표시될 수 있습니다(예: 토큰을 가져올 때). 기본적으로 당사는 SSL 인증서 확인을 활성화하고 운영 체제가 제공한 기본 CA 번들을 사용합니다. 하지만 일부 시스템에는 디스크에 알려진 CA 번들이 없습니다. 예를 들어, Windows 및 OS X에는 CA 번들에 대한 단일 공통 위치가 없습니다.

이 문제를 해결할 수 있는 여러 가지 방법이 있습니다.

개발. 개발 모드에 있는 경우 인증서 확인을 비활성화할 수 있습니다. 프로덕션 환경에서 이 사항에 대한 추가적인 테스트가 필요합니다.

use Xsolla\SDK\API\XsollaClient;

$client = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$client->setDefaultOption('ssl.certificate_authority', false);

제작. 보다 안전하고 안정적인 방식은 올바른 CA 번들을 제공하는 것입니다. 다음 코드를 사용하여 파일에 대한 CA 경로를 지정할 수 있습니다:

use Xsolla\SDK\API\XsollaClient;

$client = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$сlient->setDefaultOption('ssl.certificate_authority', '/path/to/file');

Windows에서 이 파일은 다음 경로에 있을 수 있습니다:

  • C:\windows\system32\curl-ca-bundle.crt
  • C:\windows\curl-ca-bundle.crt

이러한 파일이 있는지 확인하고 해당 CA 경로를 설정하십시오.

명시된 곳에 이 인증서가 없는 경우, 여기 (cURL의 유지 관리자가 제공함)에서 다운로드할 수 있는 Mozilla 제공 인증서를 사용해 볼 수 있습니다.

윈도우용 PHP 일부 버전에서, 인증서 경로의 프로그램 환경설정과 관련한 문제가 있습니다. 이 문제를 해결하려면, 다음 파일: cacert.pem을 다운받으신 후, 이 파일의 경로를 php.ini: curl.cainfo=c:/cacert.pem내에 직접적으로 명시해 주십시오.

"INVALID_SIGNATURE" 오류 코드와 "Authorization header not found in Xsolla webhook request" 메시지

Apache 아래 php-cgi는 기본적으로 HTTP Basic 사용자/패스를 PHP에 전달하지 않습니다. 이렇게 작동하게 하려면 다음 줄을 .htaccess 또는 httpd.conf Apache 파일에 추가해야 합니다.

RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

웹훅 서버의 "INVALID_CLIENT_IP" 오류 코드

기본적으로 엑솔라 PHP SDK는 보안상의 이유로 웹훅이 전송된 IP를 확인합니다. 개발 환경의 localhost에서 웹훅 서버를 테스트하거나, 프로덕션에서 부하 분산 장치와 같은 일부 프록시 유형 뒤에서 응용 프로그램 서버가 작동하는 경우 오류 코드 “INVALID_CLIENT_IP”가 반환될 수 있습니다.

사용자가 프록시 뒤에 있는 경우 수동으로 프록시를 허용 목록에 넣어야 합니다.

개발 환경에 있는 경우 다음 코드를 사용하여 IP 검사를 비활성화할 수 있습니다.

use Xsolla\SDK\Webhook\WebhookServer;

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start($webhookRequest = null, $authenticateClientIp = false);

보다 안전하고 안정적인 방식은 역방향 프록시 IP 주소를 웹훅 서버로 설정하는 것입니다.

use Xsolla\SDK\Webhook\WebhookServer;
use Symfony\Component\HttpFoundation\Request;

$request = Request::createFromGlobals();
$request->setTrustedProxies(array('YOUR_PROXY_SERVER_IP_OR_CIDR'));

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

자세한 내용은 Symfony 설명서에 나와 있습니다.