The following documentation was deprecated. Current version is available at developers.xsolla.com
문서로 돌아가기

Pay2Play

Pay2Play 모듈을 통해 웹사이트에서 직접 게임 개발자가 PIN 코드를 판매할 수 있습니다. 사용자는 Pay2Play 위젯을 사용하여 상점에 액세스할 수 있습니다. 모듈에는 다양한 통합 옵션이 있으므로 개발자는 다음을 수행할 수 있습니다.

  • 다른 DRM 플랫폼 선택
  • 각 DRM 플랫폼에 다른 가격 설정
  • 위젯 크기와 컬러 테마 구성
  • 개발자에게 팁 지급

사용자 플로우

통합 옵션

고급 또는 단순 모드로 모듈을 통합할 수 있습니다.

기본 통합

기본 통합:

  • 빠르게 구현할 수 있으며
  • 토큰 생성이나 서버 구현을 요구하지 않고
  • 사용자 사전 승인을 요구하지 않는 게임에 적합합니다.

고급 통합

고급 통합:

  • 게임에서 추가 연결을 할 수 있도록 사용자 및 구매 데이터를 안전하게 전송할 수 있으며
  • 서버에서 구현해야 합니다.

기본 통합 가이드

기본 통합 구현 방법:

  1. Xsolla 게시자 계정을 등록합니다.
  2. 프로젝트를 생성합니다.
  3. 모듈을 구성합니다.
  4. 결제 프로세스를 테스트합니다.
  5. Pay2Play 위젯을 게임 페이지에 추가합니다.
  6. 계약서에 서명합니다.

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

  • 프로젝트 ID — 프로젝트 설정을 볼 때 게시자 계정 URL에 표시: https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.

프로젝트 생성

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

모듈 구성 방법

  1. Pay2Play 모듈 설정으로 이동하여 게임에 대한 다음 매개변수를 구성합니다.
    • 이름.
    • 설명.
    • 시스템 요구 사항.
    • SKU — 고유 식별자.
    • 릴리스 날짜.
    • 이미지.
    • DRM 플랫폼.
    • 선택한 DRM 플랫폼에 대한 운영 체제/게임 콘솔 버전.
  2. 다음을 클릭합니다.
  3. 선택한 DRM 플랫폼의 가격을 구성합니다. 다음을 클릭합니다.
  4. 업로드된 코드를 켜기로 설정합니다.
  5. 선택한 DRM 플랫폼에 대한 PIN 코드를 업로드합니다.

결제 프로세스 테스트

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

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

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

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

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

Pay2Play 위젯 통합 방법

Pay2Play 위젯은 라이트 박스(데스크톱 화면)나 새로운 창(모바일 및 태블릿 화면)에서 상점을 엽니다. 위젯이 자동으로 장치의 유형을 판별합니다. 위젯 코드를 얻으려면, 게시자 계정에서 모듈 설정을 연 후 게시 탭으로 이동합니다. 원하는 위젯 코드를 복사한 후 게임 웹사이트에 추가합니다. 비동기 로딩 기능을 사용하는 것이 좋습니다.

비동기 로딩 예제

HTML
 <script>
     var access_data = {"settings":{"project_id":14004},"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에서 확인할 수 있습니다.

고급 통합 가이드

고급 통합 구현 방법:

  1. Xsolla 게시자 계정을 등록합니다.
  2. 프로젝트를 생성합니다.
  3. 모듈을 구성합니다.
  4. 토큰을 받습니다.
  5. 웹훅 처리를 설정합니다.
  6. 결제 프로세스를 테스트합니다.
  7. Pay2Play 위젯을 게임 페이지에 추가하고 계약서에 서명합니다.

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

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

프로젝트 생성

  1. 프로젝트로 이동하여 새 프로젝트 만들기를 클릭합니다.
  2. 프로젝트 설정에서,
    • 웹훅을 켜기로 설정합니다.
    • 웹훅 URL을 지정합니다.
    • 프로젝트 웹훅에 서명할 비밀 키를 생성합니다.
    • 서버리스 통합을 끄기로 설정합니다.
    • Pay2Play 모듈을 켭니다.

모듈 구성

  1. Pay2Play 모듈 설정으로 이동하여 게임에 대한 다음 매개변수를 구성합니다.
    • 이름.
    • 설명.
    • 시스템 요구 사항.
    • SKU — 고유 식별자.
    • 릴리스 날짜.
    • 이미지.
    • DRM 플랫폼.
    • 선택한 DRM 플랫폼에 대한 운영 체제/게임 콘솔 버전.
  2. 다음을 클릭합니다.
  3. 선택한 DRM 플랫폼의 가격을 구성합니다. 다음을 클릭합니다.
  4. 업로드된 코드를 켜기로 설정합니다.
  5. 선택한 DRM 플랫폼에 대한 PIN 코드를 업로드합니다.

상점 토큰 가져오기

상점과 통합할 토큰을 받아야 합니다. 토큰은 게임/사용자 데이터 및 결제 설정을 포함하는 문자열입니다. Xsolla API는 기본 HTTP 인증을 사용합니다. 판매자 ID를 사용자 이름으로 지정하고 API 키를 암호로 지정합니다.

샌드박스 모드를 활성화하려면 "mode" = "sandbox"로 설정합니다.

토큰 검색 URL:

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

결제 UI로 전달하기 원하는 매개변수를 포함하여 HTTP POST 요청을 변경할 수 있습니다. 요청 및 응답은 JSON 형식으로 되어 있습니다.

여기에 나와 있는 예제는 PHP 및 Xsolla PHP SDK를 사용하여 토큰을 받는 예제입니다. 다른 언어를 사용하는 경우, 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는 프로젝트에 다음과 같은 웹훅을 전송합니다.

  • 사용자 유효성 검사
  • 결제
  • 환불

메시지 본문 없이 HTTP 코드 204로 응답하여 웹훅을 수신하였음을 확인합니다. 예제와 웹훅 처리에 대한 자세한 내용은 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. 녹색으로 표시된 테스트는 유효한 응답을 한 경우이며 빨간색으로 표시된 테스트는 오류가 발생한 경우입니다.

결제 프로세스 테스트

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

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

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

테스트용 은행 카드 목록

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

Pay2Play 위젯 통합 방법

Pay2Play 위젯은 라이트 박스(데스크톱 화면)나 새로운 창(모바일 및 태블릿 화면)에서 상점을 엽니다. 위젯이 자동으로 장치의 유형을 판별합니다. 위젯 코드를 얻으려면, 게시자 계정에서 모듈 설정을 연 후 게시 탭으로 이동합니다. 원하는 위젯 코드를 복사한 후 게임 웹사이트에 추가합니다. 비동기 로딩 기능을 사용하는 것이 좋습니다.

비동기 로딩 예제

HTML
 <script>
     var access_data = {"settings":{"project_id":14004},"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에서 확인할 수 있습니다.

추가 기능

개발자 팁 기능

프로젝트는 각 구매에 대한 팁을 받을 수 있습니다. 옵션을 활성화하려면, Pay2Play 가격 설정을 열고 Pay2Play 위젯에서 팁 사용을 켜기로 설정합니다. 추가한 각각의 통화에 대해 사전에 정의한 3개의 팁 금액을 사용할 수 있습니다.

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

API를 통한 PIN 코드 전달

파일에 PIN 코드 목록을 업로드하는 대신 구매가 이루어진 후에 각각 PIN 코드를 전송할 수 있습니다. 기능 활성화 방법:

  • PIN 코드 가져오기 웹훅을 구현합니다.
  • Pay2Play 설정에서, 코드 업로드로 이동하여, 주문형을 켜기로 설정하고 코드 업로드를 끄기로 설정합니다.

PIN 코드 판매 제한

한 프로젝트에 판매할 수 있는 PIN 코드 수를 제한할 수 있습니다. 100개 이하의 PIN 코드가 남은 경우와 PIN 코드가 남지 않은 경우에 이메일 알림을 받게 됩니다. 한도를 초과한 경우, 사용자는 결제할 수 없게 됩니다.

지역별 판매 제한

Pay2Play 모듈을 사용하여 PIN 코드 판매 지역을 제한하는 설정을 할 수 있습니다. 특히, 다음과 같은 작업을 수행할 수 있습니다.

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

프로젝트를 올바르게 구성하면, 제한된 국가에서 PIN 코드를 구매하려는 사용자에게 해당 경고가 표시됩니다. PIN 코드 판매가 금지된 국가에서는 결제할 수 없습니다.

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

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

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

중요 정보! PIN 코드 활성화 및 게임 출시를 자신 또는 DRM 플랫폼에서 수행하는 경우, 릴리스 날짜에 지역 제한을 미리 구성한 PIN 코드를 업로드해야 합니다.