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

선주문

선주문은 게시자가 공식 출시일 이전에 게임을 판매할 수 있도록 하는 Xsolla Pay2Play 기반 솔루션입니다. 사용자가 게임을 선주문하면 구매를 확인하는 고유 번호를 받게 됩니다. 게임이 출시되면 사용자가 게임에 액세스할 수 있도록 PIN 코드가 자동으로 전달됩니다.

프로젝트 생성 방법

  1. 프로젝트로 이동하여 새 프로젝트 만들기를 클릭합니다.
  2. 설정 모드에서
    a. 웹훅끄기로 설정합니다.
    b. 서버리스 통합켜기로 설정합니다.
  3. Pay2Play 모듈을 켜기로 설정합니다.

모듈 구성 방법

  1. Pay2Play 설정으로 이동하여 다음과 같은 매개변수를 구성합니다.
    a. 게임 이름
    b. 게임 설명
    c. 시스템 요구 사항
    d. SKU — 고유 식별자
    e. 출시일
    f. 이미지
    g. DRM 플랫폼
    h. 선택한 DRM 플랫폼에서 지원하는 운영 체제/게임 콘솔 버전
  2. 다음을 클릭합니다.
  3. 선택한 DRM 플랫폼의 가격을 설정합니다.

Pay2Play 위젯 통합 방법

Pay2Play 위젯은 라이트 박스(데스크톱 화면)나 새로운 창(모바일 및 태블릿 화면)에서 상점을 엽니다. 위젯이 자동으로 장치의 유형을 판별합니다.

위젯 코드를 얻으려면, 게시자 계정에서 모듈 설정을 연 후 게시 탭으로 이동합니다. 원하는 위젯 코드를 복사한 후 게임 웹사이트에 추가합니다. 비동기 로딩 기능을 사용하는 것이 좋습니다.

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

 <script>
         var access_data = {"settings":{"project_id":14004,"mode":"sandbox"},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
         var target_element = "#widget-example-element";
         var s = document.createElement('script');
         s.type = "text/javascript";
         s.async = true;
         s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
         s.addEventListener('load', function (e) {
                 var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
         }, false);
         var head = document.getElementsByTagName('head')[0];
         head.appendChild(s);
 </script>

위젯 초기화 매개변수의 전체 목록은 API Reference에서 확인할 수 있습니다. 위젯 설치에 대한 지침은 GitHub에서 확인할 수 있습니다.

중요 정보! 실제로 결제를 수락하기 전에 계약서에 서명해야 합니다.

결제 프로세스 테스트 방법

Xsolla 샌드박스는 실제 결제를 제외한 결제 프로세스 관련 모든 기능을 지원하는 독립형 환경입니다. access_data 오브젝트 내에서 "settings.mode" = "sandbox"를 전송하여 샌드박스에 액세스할 수 있습니다. access_data의 JSON 구조와 매개변수는 <a href="../api_v2.html#token target="_blank">토큰 요청과 동일합니다.

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

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

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

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

PIN 코드 업로드 방법

게임이 출시되면 Pay2Play 모듈 설정을 열고 코드 업로드 탭에서 선택한 DRM 플랫폼의 PIN 코드를 업로드합니다.

승인받은 사용자 결제

기존 게임 계정이 있는 사용자가 승인 거래를 하도록 사용자 정보를 전송할 수 있습니다. 기능 활성화 방법:

  1. 프로젝트를 설정합니다.
  2. 토큰을 가져옵니다.
  3. 웹훅 처리를 설정합니다.

다음 매개변수가 필요합니다:

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

프로젝트 설정

프로젝트 설정 방법:

  1. 웹훅켜기로 설정합니다.
  2. 웹훅 URL을 지정합니다.
  3. 프로젝트 웹훅에 서명할 비밀 키를 생성합니다.
  4. 서버리스 통합끄기로 설정합니다.

토큰을 받아 상점 열기

상점 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에서 확인할 수 있습니다.

웹훅 설정

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(
    '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. 녹색으로 표시된 테스트는 유효한 응답을 한 경우이며 빨간색으로 표시된 테스트는 오류가 발생한 경우입니다.

개발자 팁 기능

프로젝트는 각 구매에 대한 팁을 받을 수 있습니다. 이 기능을 활성화하려면, 모듈 설정을 열고 가격 탭으로 이동한 후 Pay2play 위젯에서 팁 기능 사용켜기로 설정합니다. 개별적으로 활성화된 통화별로 3가지 유형의 팁 금액 옵션을 사용할 수 있습니다.

사용자는 상점에 들어가기 전에 팁 금액을 선택할 수 있습니다. 팁은 구매 가격에 추가됩니다.

선주문 수량 제한

프로젝트의 선주문 수량을 제한할 수 있습니다. 선주문 수량이 100개 이하로 남은 경우와 남은 선주문 수량이 없는 경우 다음과 같은 이메일 알림을 받게 됩니다. 사용자가 선주문 한도를 초과한 경우 결제는 처리되지 않습니다.

판매 지역 제한

선주문 모듈을 사용하여 선주문 판매 지역을 제한할 수 있습니다. 특히, 다음과 같은 작업을 수행할 수 있습니다.

  • 개별 국가 또는 국가 그룹별로 다르게 비용을 설정하고
  • 특정 국가에서 판매를 금지할 수 있습니다.

프로젝트가 올바르게 구성된 경우, 판매가 제한된 국가에서 선주문을 하려는 사용자에게 경고 문구가 표시됩니다. 선주문이 금지된 국가에서는 결제가 처리되지 않습니다.

이 기능을 사용하려면 계정 관리자에게 문의합니다. 지역 제한을 적용하는 각 플랫폼에 대해 다음과 같은 정보가 필요합니다.

  • 제한 유형:
    • 활성화: PIN 코드는 특정 국가에서만 활성화할 수 있습니다.
    • 출시: 모든 국가에서 PIN 코드를 활성화할 수 있지만 게임 출시는 특정 국가에서만 할 수 있습니다.
    • 활성화 및 출시: 특정 국가에서만 PIN 코드를 활성화하고 게임을 출시할 수 있습니다.
  • 선주문 가격이 다른 국가 그룹 목록
  • 각 국가 그룹별 설정:
    • 그룹 이름
    • SKU — 고유 그룹 식별자
    • 다른 통화로 표시된 가격 목록 모듈 설정에서 설정된 기본 통화로 표시된 가격을 포함하도록 합니다.
    • 각 그룹에 속한 국가 목록
  • 선주문이 비활성화되어 있는 국가 목록(있는 경우)

단일 플랫폼의 경우 한 국가는 가격이 다른 그룹 또는 선주문이 비활성화되어 있는 그룹 중 하나에 속할 수 있습니다. 그룹에 속하지 않은 국가의 경우 선주문을 기본 모듈 설정에서 설정한 가격으로 아무런 제한없이 사용할 수 있습니다.

중요 정보! PIN 코드 활성화와 게임 출시를 직접 혹은 플랫폼에서 수행한 경우 지역 제한이 구성되어 있는 시스템에 PIN 코드를 업로드해야 합니다.