The following documentation was deprecated. Current version is available at developers.xsolla.com

개요

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

특징

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

시작하기

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

  1. MERCHANT_ID
  2. API_KEY
  3. PROJECT_ID
  4. PROJECT_KEY

이러한 파라미터는 회사 프로필프로젝트 설정에 있는 정보를 사용해 얻을 수 있습니다.

시스템 요구사항

  1. PHP 5.3.9+
  2. 다음과 같은 PHP 확장이 필요합니다.
    1. curl
    2. json

설치

PHP를 위한 Xsolla SDK는 Composer를 통해 설치하는 것이 좋습니다.

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

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

사용법

토큰 가져오기

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

토큰을 가져오는 방법은 여러가지 있습니다. 가장 쉬운 방법은 createCommonPaymentUIToken 메서드를 사용하는 것으로서, Xsolla 시스템 내 프로젝트 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 연동(Pay Station)

다음 코드를 사용해 결제 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 통합과 관련한 더 상세한 정보 및 추가 예제를 알아보려면 이 링크를 클릭하십시오.

Webhook 수신하기

Webhook 처리에 도움을 주기 위한 빌드가 서버 클래스에 있습니다.

<?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 유저을 찾을 수 없을 경우, Xsolla\SDK\Exception\Webhook\InvalidUserException을 throw해야 합니다
            break;
        case Message::PAYMENT:
            /** @var Xsolla\SDK\Webhook\Message\PaymentMessage $message */
            // TODO 알 수 없는 이유로 결제 금액이 전달되지 않은 경우 Xsolla\SDK\Exception\Webhook\XsollaWebhookException을 throw해야 합니다
            break;
        case Message::REFUND:
            /** @var Xsolla\SDK\Webhook\Message\RefundMessage $message */
            // TODO 환불을 처리할 수 없을 경우 Xsolla\SDK\Exception\Webhook\XsollaWebhookException을 throw해야 햡니다
            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 유저을 찾을 수 없을 경우, Xsolla\SDK\Exception\Webhook\InvalidUserException을 throw해야 합니다
        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 알 수 없는 이유로 결제 금액이 전달되지 않은 경우 Xsolla\SDK\Exception\Webhook\XsollaWebhookException을 throw해야 합니다
        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 환불을 처리할 수 없을 경우 Xsolla\SDK\Exception\Webhook\XsollaWebhookException을 throw해야 햡니다
        break;
    default:
        throw new XsollaWebhookException('Notification type not implemented');
}

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

Testing 탭에서 테스트를 통과한 후에는 실제로 구동할 준비가 된 것입니다. 샌드박스 파라미터를 사용했다면, 반드시 코드에서 제거하도록 하십시오.

문제 해결

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

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

Xsolla PHP SDK를 사용하여 당사 서버에 요청을 보낼 때 이러한 유형의 오류가 표시될 수 있습니다(예: 토큰을 가져올 때).

기본적으로 당사는 SSL 인증서 확인을 활성화하고 운영 체제가 제공한 기본 CA 번들을 사용합니다. 하지만 일부 시스템에는 디스크에 알려진 CA 번들이 없습니다. 예를 들어, Windows 및 OS X에는 CA 번들에 대한 단일 공통 위치가 없습니다. 이 문제를 해결할 수 있는 여러 가지 방법이 있습니다.

1) 개발

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

use Xsolla\SDK\API\XsollaClient;

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

2) 프로덕션

보다 안전하고 안정적인 방식은 올바른 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에서 이 파일은 다음 경로에 있을 수 있습니다.

  1. C:\windows\system32\curl-ca-bundle.crt
  2. C:\windows\curl-ca-bundle.crt

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

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

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


"INVALID_SIGNATURE" 오류 코드와 "Xsolla webhook 요청에서 인증 헤더 찾지 못함" 메시지

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

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

Webhook 서버의 "INVALID_CLIENT_IP" 오류 코드

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

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

use Xsolla\SDK\Webhook\WebhookServer;

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

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

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 설명서에 나와 있습니다.

개요

Xsolla는 해당 응용 프로그램에서의 결제를 수락하기 위해 Android Client SDK를 만들었습니다. 이 apk를 다운로드하여 제대로 작동하는지 확인할 수 있습니다.

시작하기 전에 여기에 나열된 모듈 중 하나를 선택하고, Webhook 처리를 구현하고, 액세스 토큰을 만드십시오.

시스템 요구사항

  1. 최소한 요구되는 Android OS 버전: 4.0
  2. Xsolla Android SDK의 경우 인터넷 연결이 중요합니다.

다운로드

Jcentral을 통해 다운로드: 


<dependency><groupId>com.xsolla.android</groupId><artifactId>xsollasdk</artifactId><version>2.3.0</version></dependency>

또는 Gradle:

compile 'com.xsolla.android:xsollasdk:2.3.0'

설치

Android Studio에서 Xsolla Android SDK를 추가할 수 있습니다. 다음 단계를 따르십시오:

  1. 모듈 가져오기 - File > Import Module > xsollasdk
  2. 종속성 추가 - File > Project Structure > Your App Module > Dependency > + > Module Dependency > xsollasdk
  3. 안드로이드 부분에서 다음을 build gradlew에 추가합니다:
     packagingOptions {
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/NOTICE'
     }
    

Github에서 이 프로젝트에 대한 링크는 이곳에서 확인할 수 있습니다.

결제하기

SDK의 적절한 작동을 위해, 액세스 토큰이 있는지 확인하십시오. 액세스 토큰 얻기에 대한 자세한 내용은 여기에 나와 있습니다.

Xsolla UI

SHOP UI를 클릭하여 열 때 결제 단추가 있는 간단한 응용 프로그램의 예를 살펴 보겠습니다.


public class MainActivity extends Activity {

 public void openShop(String token, boolean isTestPayment) {
    XsollaSDK.createPaymentForm(this, token, isTestPayment);
 }

 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   switch (requestCode){
     case XsollaActivity.REQUEST_CODE:
       if(data != null) {
         long objectId = data.getExtras().getLong(XsollaActivity.EXTRA_OBJECT_ID);
         if (resultCode == RESULT_OK) {
           XStatus statusData = (XStatus) XsollaObject.getRegisteredObject(objectId);
           Toast.makeText(this, statusData.toString(), Toast.LENGTH_LONG).show();
         } else {
           XError error = (XError) XsollaObject.getRegisteredObject(objectId);
           Toast.makeText(this, error.toString(), Toast.LENGTH_LONG).show();
         }
       }
   }
 }
}

결제가 처리되면 응용 프로그램이 OnActivityResult 객체를 통해 결과를 얻을 수 있습니다. 또한 응용 프로그램이 닫히면, 서버의 Webhook으로 전송할 것입니다.

개요

Xsolla 팀은 Unity 앱에서 직접 결제가 가능하도록 Unity SDK를 만들었습니다.

GitHub에서 Xsolla Unity SDK의 최신 릴리스를 다운로드하십시오.

시스템 요구 사항

Xsolla Unity SDK에는 Unity 5.0 이상이 필요합니다.

표준 통합

주요 특징:

  • 정기 결제;

  • 저장된 결제 수단;

  • 가상 화폐 구매;

  • 가상 아이템 구매;

  • 구독 서비스 구매;

  • 프로모션;

  • 쿠폰 사용;

  • 사용자의 지불 이력.

Xsolla 결제 UI를 통해 결제를 처리하고자 할 경우에는 다음 단계를 따릅니다:

  1. webhook 처리를 설정합니다. http://developers.xsolla.com/api_v2.html#webhooks
  2. Xsolla 액세스 토큰을 생성하여 최대 보안 상태로 결제를 수행합니다. 토큰 생성 방법과 관련된 문서 자료는 다음 주소에서 확인할 수 있습니다. http://developers.xsolla.com/api_v2.html#payment_ui
  3. XsollaSDK 스크립트를 추가하거나 'Resources -> Prefabs' 폴더에서 바로 사용할 수 있는 prefab을 적용합니다.
  4. XsollaSDK(instance)를 호출하여 바로 사용할 수 있는 결제 양식을 생성합니다
  5. CreatePaymentForm(token, actionOk(XsollaStatusData), actionError(XsollaError), actionMore(string))을 호출합니다.
파라미터 설명
token 토큰 메서드 가져오기를 통해 수신한 구매 토큰
actionOk 결제 프로세스가 완료되었을 때 호출됩니다. 여기에 결제 수락 함수를 삽입합니다.
actionError 결제 프로세스가 취소되었거나 문제가 나타났을 때 호출됩니다. 여기에 이벤트 처리 함수를 삽입합니다.
  1. XsollaSDK.InitPaystation(string token)을 사용하여 네이티브 브라우저에서 결제 UI를 실행할 수도 있습니다.

고유한 결제 UI를 사용하려면, XsollaPaystation에서 상속되는 새 클래스를 선언하십시오.

예를 들어 XsollaPaystationController를 사용할 수 있습니다.

SDK 응답 개체:

public class XsollaResult {

    public string invoice{ get; set;}

    public Status status{ get; set;}

    public Dictionary<string, object> purchases;

}

체험해 보십시오!

데모를 확인해 보십시오.

또한 "XsollaUnitySDK" -> "Resources" -> "_Scenes" 폴더에 테스트 시나리오가 있습니다.

  1. XsollaFarmFreshScene - 아이템 상점을 에뮬레이션합니다.

  2. XollaTokenTestScene – 여기에서 토큰을 테스트할 수 있습니다.