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

확률 상자

확률 상자는 사용자가 구매하거나 보상으로 받을 수 있는 인게임 아이템 및/또는 가상 통화 세트입니다. 확률 상자의 콘텐츠는 무작위로 생성되며 사용자는 확률 상자가 열리기 전에 안에 든 내용을 알 수 없습니다.

확률 상자 모듈에는 다양한 통합 옵션이 있으며 게임 프로젝트에서 다음을 구성할 수 있습니다.

  • 확률 상자 발행 옵션: 게임 요청 또는 상점 구매
  • 확률 상자 구매 옵션: 실제 또는 가상 화폐
  • 확률 상자 열기 옵션: 실제 또는 가상 화폐를 사용하거나 실제 또는 가상 화폐로 구매한 키를 사용
  • 특정 아이템 또는 가상 화폐 패키지가 확률 상자 안에서 생기는 방법을 정의하는 옵션
  • 특정 아이템 속성이 확률 상자에 나타나는 확률을 설정하는 기능
  • 확률 상자 열기 애니메이션

통합 가이드

다음 기능을 지원하는 모듈입니다.

  • 구매 또는 인게임 이벤트에 따라 사용자의 인벤토리에 확률 상자 추가
  • 새 아이템을 사용자의 인벤토리에 추가 시 애니메이션 시퀀스 표시
  • 확률 상자를 열 때 애니메이션 시퀀스 표시
  • 확률 상자를 연 후에 확률 상자를 인벤토리에서 제거

확률 상자를 사용하려면,

  1. Xsolla 게시자 계정을 등록합니다.
  2. 프로젝트를 생성합니다.
  3. 모듈을 설정합니다.
  4. 확률 상자를 설정합니다.
  5. 토큰을 받습니다.
  6. 상점 UI 열기를 설정합니다.
  7. 웹훅 처리를 설정합니다.
  8. 결제 프로세스를 테스트합니다.
  9. 모듈을 시작하고 계약서에 서명합니다.

통합에 필요한 매개변수는 다음과 같습니다.

  • 판매자 ID — 게시자 계정 URL에 표시: https://publisher.xsolla.com/{merchant_id}/.
  • API 키게시자 계정 > 설정 > 회사에서 생성됨.
  • 프로젝트 ID — 다음과 같은 프로젝트 설정을 볼 때 게시자 계정 URL에 표시됨: https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • 프로젝트 비밀 키 — 프로젝트 설정에서 생성합니다.

프로젝트 생성

  1. 프로젝트로 이동하여 새 프로젝트 만들기를 클릭합니다.
  2. 프로젝트 설정에서,
    a. 웹훅 URL을 지정합니다.
    b. 프로젝트 웹훅에 서명할 비밀 키를 생성합니다.
    c. 가상 아이템 모듈을 활성화합니다.
    d. 사용자로 이동한 후 사용자 데이터를 Xsolla에 저장켜기로 설정합니다.

모듈 설정

확률 상자 사용을 시작하려면, 우선 확률 상자에 저장할 수 있는 가상 아이템 카탈로그를 만듭니다.

  1. 이를 위해, 가상 아이템 모듈 설정으로 이동하여 아이템 그룹 생성을 클릭합니다. 그룹 구성:
    a. 카탈로그 위치(기본으로 루트 폴더)
    b. 코드
    c. 이름 및 설명
    d. 상점 외관 상점에 그룹을 표시하려면 상점에 표시를 체크합니다.
  2. 생성을 클릭합니다.
  3. 기본 모듈 설정으로 돌아가 필요에 따라 카탈로그를 위한 다른 그룹을 생성하려면 아이템 목록을 클릭합니다.
  4. 아이템 생성을 클릭한 후 다음 매개변수를 설정합니다.
    a. 아이템이 속해 있는 그룹 수(하나 이상) 그룹을 선택하지 않은 경우, 상점에 아이템이 표시되지 않습니다.
    b. SKU — 고유 식별자
    c. 이름 및 간단한 설명
    d. 실제 통화로 표시된 가격
    e. 이미지
  5. 생성을 클릭합니다.
  6. 기본 모듈 설정으로 돌아가 필요에 따라 다른 항목을 생성하려면 아이템 목록을 클릭합니다.

확률 상자 설정

확률 상자는 여러 슬롯으로 구성되어 있습니다. 확률 상자를 열면 각 슬롯은 임의의 아이템으로 채워집니다. 관리자는 아이템의 범위와 드롭 확률을 미리 정해야 합니다.

확률 상자를 제작하고 구성하려면 확률 상자 제작 방식을 사용하고 다음 매개변수를 지정합니다.

  • 확률 상자 슬롯 개수
  • 각 슬롯에 나타날 수 있는 각 확률 상자 아이템 확률표
  • 각 슬롯에 나타날 수 있는 특정 속성 아이템 확률표
  • 슬롯이 비어 있을 확률
  • 중복 아이템 가상 화폐 대체 가능 여부(가격 비율 또는 지정된 금액)

매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.

토큰을 받아 상점 열기

상점 UI를 게임에 통합하려면 액세스 토큰이 필요합니다. 액세스 토큰은 게임, 사용자 및 구매 매개변수를 식별하는 문자열입니다.

Xsolla API는 HTTP 기본 인증을 사용합니다. 판매자 ID를 기본 인증 사용자 이름으로 제공하고 API 키를 암호로 제공합니다.

결제 프로세스를 테스트하려면 값을 "mode":"sandbox"로 설정합니다.

토큰 엔드포인트 URL:

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

HTTP POST 요청에서, 상점 UI의 매개변수를 사용할 수 있습니다. 요청 및 응답 페이로드는 JSON 형식으로 되어 있습니다.

요청 예제

아래에는 Xsolla PHP SDK를 사용하여 PHP에서 토큰을 얻는 방법에 대한 샘플 코드가 제공되어 있습니다. 다른 프로그래밍 언어를 사용하고 있는 경우, CURL 탭을 클릭하여 CURL 예제를 살펴봅니다.

PHP
CURL
<?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);
    curl -v https://api.xsolla.com/merchant/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
        "user": {
            "id": {
                "value": "1234567"
            },
            "email": {
                "value": "email@example.com"
            }
        },
        "settings": {
            "project_id": 14004,
            "mode": "sandbox"
        }
    }'

매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.

상점 UI 열기

상점을 열 수 있는 세 가지 방법:

  • Pay Station 임베드 스크립트 사용
  • 새 창 사용
  • Iframe 사용

샌드박스 모드로 상점을 열려면 다음 URL을 사용합니다. https://sandbox-secure.xsolla.com/

Pay Station 임베드

Pay Station 임베드 스크립트가 장치 유형을 결정하고 라이트박스(데스크톱 화면) 또는 새 창(모바일 및 태블릿 화면)에서 상점 UI를 엽니다. 비동기 스크립트 로딩 기능을 사용하는 것이 좋습니다.

비동기 스크립트 로딩 예제:

<script>
     var options = {
         access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
         sandbox: true //TODO please do not forget to remove this setting when going live
     };
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
     s.addEventListener('load', function (e) {
         XPayStationWidget.init(options);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
</script>

<button data-xpaystation-widget-open>크레딧 구입</button>

매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.

새 창

새 창에서 상점 UI를 열려면 다음 링크를 사용합니다. https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, 여기에서 ACCESS_TOKEN이전 단계에서 입수한 토큰입니다.

Iframe

iframe에서 상점 UI를 열려면 다음 메커니즘을 자신 쪽에 적용해야 합니다.

  • 장치 유형(데스크톱 또는 모바일)을 지정하고 장치를 토큰의 settings.ui.version 매개변수 내에서 전송합니다.
  • postMessage를 통해 결제 UI로부터 이벤트를 수신합니다.

새 창에서 상점 UI를 열려면 다음 링크를 사용합니다. https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, 여기에서 ACCESS_TOKEN이전 단계에서 입수한 토큰입니다.

웹훅 설정

Xsolla는 프로젝트에 다음과 같은 웹훅을 전송합니다.

  • 사용자 유효성 검사
  • 결제
  • 인벤토리 콘텐츠 변경
  • 환불

아무런 문제없이 웹훅 알림을 받았음을 확인하려면 사용자 서버가 본문없이 204 HTTP 상태 코드를 반환해야 합니다. 예제를 포함한 웹훅 메커니즘에 대한 내용은 API Reference에 자세히 설명되어 있습니다.

서명 생성

서명 생성 방법:

  1. Xsolla 서버 요청 시 전송된 데이터와 프로젝트의 비밀 키(프로젝트 설정에서 생성)를 연결합니다.
  2. SHA1 알고리즘을 사용하여 문자열 해시합니다.
  3. 서명 헤더에 서명을 전송합니다.

웹훅을 처리할 때 수신한 서명이 서명 헤더에 설정된 서명과 일치하는 확인합니다.

사용자 유효성 검사

Xsolla 서버는 사용자가 게임에 존재하는지 확인하기 위해 프로젝트 웹훅 URL로 요청을 전송합니다.

요청 예제

PHP
CURL
$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "country": "US"
    }
}'

매개변수 전체 목록은API Reference에서 확인할 수 있습니다.

결제

Xsolla 서버는 사용자가 결제를 완료할 때마다 결제 세부 정보가 포함되어 있는 웹훅을 전송합니다.

요청 예제

PHP
CURL
$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_items' => array(
            'items' => array(
                0 => array(
                    'sku' => 'test_item1',
                    'amount' => 1,
                    ),
                1 => array(
                    'sku' => 'test_item2',
                    'amount' => 1,
                    ),
                2 => array(
                    'sku' => 'test_item3',
                    'amount' => 1,
                    ),
            )
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "payment",
    "purchase": {
        "virtual_items": {
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                },
                {
                    "sku": "test_item2",
                    "amount": 1
                },
                {
                    "sku": "test_item3",
                    "amount": 2
                },
            ]
        },
        "total": {
            "currency": "USD",
            "amount": 9.99
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "country": "US"
    },
    "transaction": {
        "id": 87654321,
        "payment_date": "2014-09-23T19:25:25+04:00",
        "payment_method": 1380,
        "dry_run": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 9.99
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 9.49
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 0.19
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 0.31
        }
    }
}'

매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.

인벤토리 콘텐츠 변경

사용자의 인벤토리가 변경될 때마다(아이템이 추가되거나 제거될 때마다) Xsolla 서버가 웹훅을 프로젝트 서버로 전송합니다.

요청 예제

PHP
CURL
$request = array(
    'virtual_currency_balance' => (
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => (
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"semail@example.com
    },
    "operation_type":"inGamePurchase",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation":"66989"
}'

매개변수 전체 목록은API Reference에서 확인할 수 있습니다.

환불

사용자가 결제를 취소할 경우, Xsolla 서버가 지불 정보와 함께 웹훅 알림을 전송합니다.

요청 예제

PHP
CURL
$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => (
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"refund",
    "purchase":{
        "virtual_currency":{
            "name": "Coins",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "date_create": "2014-09-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":1,
        "reason":"Fraud"
    },
    "payment_details":{
        "xsolla_fee":{
            "currency":"USD",
            "amount":"10"
        },
        "payout":{
            "currency":"USD",
            "amount":"200"
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":"20"
        },
        "payment":{
            "currency":"USD",
           "amount":"230"
        }
    }
}'

매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.

웹훅 테스트

웹훅 처리 테스트 방법:

  1. 게시자 계정에서, 모듈 설정을 엽니다.
  2. 테스트 탭으로 이동합니다.
  3. 테스트 데이터를 입력한 후 테스트를 클릭합니다. Xsolla 서버는 가능한 모든 웹훅을 전송합니다.
  4. 녹색으로 표시된 테스트는 유효한 응답을 한 경우이며 빨간색으로 표시된 테스트는 오류가 발생한 경우입니다.

결제 프로세스 테스트

Xsolla 샌드박스는 실제 결제를 제외한 결제 프로세스 관련 모든 기능을 지원하는 독립형 환경입니다. "mode = "sandbox"를 전송하여 샌드박스에 액세스할 수 있습니다(토큰 입수 시 가능).

은행 카드 결제 테스트 방법:

  1. 샌드박스 모드로 상점을 엽니다.
  2. 구매할 항목을 선택합니다.
  3. 신용카드/체크카드를 클릭합니다.
  4. 나머지 필드에 은행 카드 세부 정보와 값을 입력합니다. 오류를 확인하기 위해 잘못된 세부 정보(카드 번호, 만료일, CVV)를 입력할 수도 있습니다.

테스트에 사용할 은행 카드 목록

중요 정보! 샌드박스 은행 카드 결제는 USD, EUR, RUB, GBP, SGD, HKD 또는 THB로만 이용할 수 있습니다.

모듈 시작

테스트를 성공적으로 완료한 후 모듈을 시작하려면 게시자 계정에서 설정을 열고 시작 탭으로 이동한 다음, 켜기를 클릭합니다.

중요 정보! 실제 지불을 받으려면 먼저 다음을 수행해야 합니다.

  1. "mode" = "sandbox"를 제거합니다.
  2. 계약서에 서명합니다.

게임 서버에서 확률 상자 열기

확률 상자가 게임 서버에서 열린 경우,

  • 사용자의 인벤토리에 확률 상자가 있는지 확인할 수 있습니다.
  • 드롭된 아이템 목록을 가져올 수 있습니다.
  • 사용자의 인벤토리에 새 아이템을 추가할 수 있습니다.
  • 확률 상자를 연 후에 인벤토리에서 확률 상자를 제거할 수 있습니다.

이 기능을 사용하려면 계정 관리자에게 연락하십시오.

확률 상자 열기 애니메이션

확률 상자가 Xsolla 서버에서 열린 경우 결과물에 따라 다른 애니메이션 시퀀스를 추가할 수 있습니다. 이 기능을 사용하려면 계정 관리자에게 연락하십시오.