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

가상 통화

가상 통화 모듈을 통해 개발자가 인게임 통화를 포괄적인 방법으로 판매할 수 있습니다. 모듈에는 다양한 통합 옵션이 있으므로 게임 프로젝트에서 다음을 수행할 수 있습니다.

  • 패키지 및 임의 수량의 인게임 통화 판매
  • 다양한 통화 지원 사용
  • 사용자 지정 이미지 및 프로모션 레이블 사용
  • 마케팅 캠페인 실행
  • 인게임 통화 사용자 잔액 관리
  • 사용자 통화 및 국가 자동 감지

사용자 플로우

파트너 플로우

통합 가이드

모듈 통합 방법:

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

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

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

프로젝트 생성

  1. 프로젝트로 이동하여 새 프로젝트 만들기를 클릭합니다.
  2. 설정 모드에서
    , 1) 웹훅 URL을 지정합니다.
    2) 프로젝트 웹훅에 서명할 비밀 키를 생성합니다.
    3) 가상 통화 모듈을 켭니다.

모듈 구성

  1. 가상 통화 모듈 설정으로 이동하여 인게임 통화에 대한 다음 매개변수를 구성합니다.
    • 이름.
    • 단위당 가격.
    • 이미지.
  2. 패키지 탭으로 이동하여 패키지 추가를 클릭합니다. 다음 매개변수를 지정합니다.
    • 가격.
    • 이미지.
  3. 상점에서 패키지를 활성화 또는 비활성화하려면, 활성화를 켜기 또는 끄기로 각각 설정합니다.

상점 토큰 가져오기

상점과 통합할 토큰을 받아야 합니다. 토큰은 게임/사용자 데이터 및 결제 설정을 포함하는 문자열입니다. 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에서 확인할 수 있습니다.

상점 UI 열기

상점은 다음과 같이 열 수 있습니다.

  • Pay Station Embed 스크립트 사용
  • 새로운 창
  • 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는 프로젝트에 다음과 같은 웹훅을 전송합니다.

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

메시지 본문 없이 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로만 이용할 수 있습니다.

모듈 시작

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

중요 정보! 실제로 결제를 수락하기 전에 다음을 수행해야 합니다.

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

추가 기능

인게임 매개변수를 사용하여 사기 방지

토큰으로 전달된 custom_parameters 방식을 사용하여 사용자의 인게임 데이터를 전송하고 의심스러운 활동을 감지할 수 있습니다. 예를 들어 게임을 거의 하지 않았지만 레벨이 높은 플레이어는 훔친 은행 카드를 사용하여 캐릭터를 레벨업 한 후 캐릭터를 판매하기 위해 계정을 만든 사기꾼일 수 있습니다.

사용 가능한 매개변수 목록

계정 관리자에게 전달할 매개변수와 각 매개변수에 해당하는 트리거 값을 알려줍니다. 이러한 정보를 사용하여 사기 방지 필터를 구성합니다.

선택한 방식으로 결제

상점을 개설할 경우, settings.payment_method 매개변수에서 결제 방식 ID를 전송할 수 있습니다. 이 경우 사용자는 선택한 결제 방식의 결제 양식으로 즉시 리디렉션됩니다.

요청 예제

CURL
    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"
            },
        },
        "settings": {
            "project_id": 14004,
            "payment_method": 24
        }
    }'

결제 방식 ID 목록은 게시자 계정 > 결제 시스템 또는 결제 시스템 나열 API 방식을 사용하여 가져옵니다.

선택한 패키지 구매

상점을 연 경우, purchase.virtual_currency.quantity에 패키지 ID를 전송할 수 있습니다. 이 경우, 사용자는 즉시 결제 UI로 리디렉션됩니다.

요청 예제

CURL
    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"
            },
        },
        "settings": {
            "project_id": 14004
        },
        "purchase": {
            "virtual_currency": {
                "quantity": 100
            },
        }
    }'

사용자 잔액 관리

사용자 잔액을 Xsolla에서 인게임 통화로 보관할 수 있습니다. 이렇게 하면 다음을 수행할 수 있습니다.

  • 잔액으로 저장된 인게임 통화를 위한 가상 아이템 판매(가상 아이템 모듈 필요)
  • 인게임 통화 패키지를 판매하여 사용자 잔액 충전
  • API를 통해 사용자 잔액 변경

기능 활성화 방법:

  1. 게시자 계정에서 프로젝트 설정을 엽니다.
  2. 사용자를 클릭합니다.
  3. 다음 스위치를 켜기로 설정합니다.
    • 사용자의 데이터를 Xsolla에 저장
    • 사용자의 프로필을 Pay Station 3.0에 표시

결제 단말기를 통해 인게임 통화 판매

사용자는 프로젝트 설정에 따라 별명, 이메일 등을 사용하여 자신을 식별한 후 결제 단말기를 통해 인게임 통화를 구매할 수 있습니다. 기능 활성화 방법:

  • 프로젝트에서 임의의 수량의 인게임 통화를 판매할 수 있도록 하고 가능한 한 적은 수의 매개변수로 웹훅을 처리하도록 합니다.
  • 게시자 계정에서 프로젝트 설정으로 이동한 후 Public User ID를 켜기로 설정합니다.

인게임 통화 임의 금액 활성화

사용자가 임의의 금액의 인게임 통화를 구매하도록 허용할 수 있습니다. 기능 활성화 방법:

  • 모듈 설정에서, 구매 후 남은 자금 반환 기능 활성화를 선택 해제하고 사용자가 구매할 수 있는 인게임 통화의 최소/최대 금액을 표시합니다.
  • 상점을 열 때 settings.ui.components.virtual_currency.custom_amount 매개변수를 포함시킵니다.