실제 상품
실제 상품은 가상 아이템 모듈에 기반한 솔루션이며 게임 개발자는 이를 통해 게임 관련 용품을 판매할 수 있습니다. Xsolla API에 기반하여 게임 측에 상점을 생성합니다. Xsolla는 결제 UI를 제공하고 최종 사용자를 위한 제공 서비스를 구성합니다.
실제 상품은 가상 아이템 모듈에 기반한 솔루션이며 게임 개발자는 이를 통해 게임 관련 용품을 판매할 수 있습니다. Xsolla API에 기반하여 게임 측에 상점을 생성합니다. Xsolla는 결제 UI를 제공하고 최종 사용자를 위한 제공 서비스를 구성합니다.
모듈 통합 방법:
통합에 필요한 매개변수는 다음과 같습니다.
실제 상품 관리 방법:
각 파트너가 이용할 수 있는 제공 서비스 목록은 개별적으로 논의됩니다. 보다 자세한 정보를 얻으려면 계정 관리자에게 풀필먼트 플랫폼 목록과 ID를 전송합니다.
결제 UI를 게임에 통합하려면 액세스 토큰을 입수해야 합니다. 액세스 토큰은 게임, 사용자 및 구매 매개변수를 식별하는 문자열입니다. Xsolla API는 HTTP 기본 인증을 사용합니다. 판매자 ID를 기본 인증 사용자 이름으로 제공하고 API 키를 암호로 제공합니다.
결제 프로세스를 테스트하려면 값을 "mode":"sandbox"로 설정합니다.
토큰 끝점 얻기:
https://api.xsolla.com/merchant/merchants/{merchant_id}/token
HTTP POST 요청에서, 상점 UI의 매개변수를 사용할 수 있습니다. 요청 및 응답 페이로드는 JSON 형식으로 되어 있습니다.
요청 예제
아래에는 Xsolla PHP SDK를 사용하여 PHP에서 토큰을 얻는 방법에 대한 예제가 제공되어 있습니다. 다른 프로그래밍 언어를 사용하고 있는 경우, CURL 탭을 클릭하여 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를 열 수 있는 세 가지 방법:
샌드박스 모드에서 결제 UI를 열려면 다음 URL을 사용합니다. https://sandbox-secure.xsolla.com/
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에서 결제 UI를 열려면 다음 메커니즘을 실행해야 합니다.
새 창에서 결제 UI를 열려면 다음 링크를 사용합니다. https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, 여기에서 ACCESS_TOKEN은 이전 단계에서 입수한 토큰입니다.
Xsolla는 프로젝트에 다음과 같은 웹훅을 전송합니다.
아무런 문제없이 웹훅 알림을 받았음을 확인하려면 사용자 서버가 본문없이 204 HTTP 상태 코드를 반환해야 합니다. 예제를 포함한 웹훅 메커니즘에 대한 내용은 API Reference에 자세히 설명되어 있습니다.
서명 생성 방법:
웹훅을 처리할 때 수신한 서명이 서명 헤더에 설정된 서명과 일치하는 확인합니다.
Xsolla 서버는 사용자가 게임에 존재하는지 확인하기 위해 프로젝트 웹훅 URL로 요청을 전송합니다.
요청 예제
$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 서버는 사용자가 결제를 완료할 때마다 결제 세부 정보가 포함되어 있는 웹훅을 전송합니다.
요청 예제
$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 서버가 지불 정보와 함께 웹훅 알림을 전송합니다.
요청 예제
$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에서 확인할 수 있습니다.
웹훅 처리 테스트 방법:
Xsolla 샌드박스는 실제 결제를 제외한 결제 프로세스 관련 모든 기능을 지원하는 독립형 환경입니다. "mode" = "sandbox"를 전송하여 샌드박스에 액세스할 수 있습니다( 토큰 입수 시 가능).
은행 카드 결제 테스트 방법:
중요 정보! 샌드박스 은행 카드 결제는 USD, EUR, RUB, GBP, SGD, HKD 또는 THB로만 이용할 수 있습니다.
테스트를 성공적으로 완료한 후 모듈을 시작하려면 게시자 계정에서 설정을 열고 시작 탭으로 이동한 다음, 켜기를 클릭합니다.
중요 정보! 실제 지불을 받으려면 먼저 다음을 수행해야 합니다.