구독 모듈로 사용자에게 구독 상품을 판매하고 특정 기간 동안 사용자가 서비스에 액세스하도록 설정할 수 있습니다. 특히, 다음과 같은 작업을 수행할 수 있습니다.
구독은 다음 중 하나의 상태를 갖게 됩니다.
Canceled. 다음과 같은 사유로 인해 구독이 즉시 취소되었습니다.
Non renewing. 구독 갱신이 취소된 경우. 본 구독은 현재 결제 주기가 종료될 때까지 지속된 다음 Canceled 상태로 변경됩니다. 갱신은 다음과 같은 사유로 인해 취소될 수 있습니다.
모듈 통합 방법:
통합에 필요한 매개변수는 다음과 같습니다.
중요 정보! 하나의 플랜에는 하나의 통화만 지정할 수 있습니다. 개별 프로젝트 통화의 경우 별도의 플랜 세트를 생성해야 합니다.
상점과 통합할 토큰을 받아야 합니다. 토큰은 게임/사용자 데이터 및 결제 설정을 포함하는 문자열입니다. 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
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에서 확인할 수 있습니다.
상점은 다음과 같이 열 수 있습니다.
샌드박스 모드로 상점을 열려면 다음 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는 프로젝트에 다음과 같은 웹훅을 전송합니다.
메시지 본문 없이 HTTP 코드 204로 응답하여 웹훅을 수신하였음을 확인합니다. 예제와 웹훅 처리에 대한 자세한 내용은 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 서버는 사용자가 결제를 완료할 때마다 구독 세부 정보가 포함되어 있는 웹훅을 전송합니다.
<?php
$request = array(
'notification_type' => 'create_subscription',
'user' => (
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => (
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_next_charge' => '2015-01-22T19:25:25+04:00',
'trial' => (
'value' => 90,
'type' => 'day'
)
)
);
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"create_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_create":"2014-09-22T19:25:25+04:00",
"date_next_charge":"2015-01-22T19:25:25+04:00",
"trial": {
"value": 90,
"type": "day"
}
}
}'
매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.
사용자가 구독 플랜을 변경하거나, 구독 기간을 갱신하거나, 다음 청구일이 변경될 때마다 Xsolla 서버가 웹훅을 전송합니다.
요청 예제
<?php
$request = array(
'notification_type' => 'update_subscription',
'user' => (
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => (
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_next_charge' => '2015-01-22T19:25:25+04:00'
)
);
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"update_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_next_charge":"2015-01-22T19:25:25+04:00"
}
}'
매개변수 전체 목록은 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 서버가 웹훅을 전송합니다.
요청 예제
<?php
$request = array(
'notification_type' => 'cancel_subscription',
'user' => (
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => (
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_end' => '2015-01-22T19:25:25+04:00',
)
);
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"cancel_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_create":"2014-09-22T19:25:25+04:00",
"date_end":"2015-01-22T19:25:25+04:00"
}
}'
매개변수 전체 목록은 API Reference에서 확인할 수 있습니다.
웹훅 처리 테스트 방법:
Xsolla 샌드박스는 실제 결제를 제외한 결제 프로세스 관련 모든 기능을 지원하는 독립형 환경입니다. "mode""sandbox"를 전송하여 샌드박스에 액세스할 수 있습니다(토큰 입수 시 가능).
은행 카드 결제 테스트 방법:
중요 정보! 샌드박스 은행 카드 결제는 USD, EUR, RUB, GBP, SGD, HKD 또는 THB로만 이용할 수 있습니다.
테스트를 성공적으로 완료한 후 모듈을 시작하려면 게시자 계정에서 설정을 열고 시작 탭으로 이동한 다음, 켜기를 클릭합니다.
중요 정보! 실제로 결제를 수락하기 전에 다음을 수행해야 합니다.
토큰으로 전달된 custom_parameters 방식을 사용하여 사용자의 인게임 데이터를 전송하고 의심스러운 활동을 감지할 수 있습니다. 예를 들어 게임을 거의 하지 않았지만 레벨이 높은 플레이어는 훔친 은행 카드를 사용하여 캐릭터를 레벨업 한 후 캐릭터를 판매하기 위해 계정을 만든 사기꾼일 수 있습니다.
계정 관리자에게 전달할 매개변수와 각 매개변수에 해당하는 트리거 값을 알려줍니다. 이러한 정보를 사용하여 사기 방지 필터를 구성합니다.
상점을 개설할 경우, settings.payment_method 매개변수에서 결제 방식 ID를 전송할 수 있습니다. 이 경우 사용자는 선택한 결제 방식의 결제 양식으로 즉시 리디렉션됩니다.
요청 예제
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.subscription.plan_id 매개변수에서 플랜 ID를 전송할 수 있습니다. 이 경우, 사용자는 즉시 결제 UI로 리디렉션됩니다.
요청 예제
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": {
"subscription": {
"plan_id": 123
},
}
}'
구독이 취소된 경우, 마지막 결제 항목을 취소할 수도 있습니다. 이를 위해, 구독 업데이트 방식에서 cancel_subscription_payment 매개변수를 사용합니다. 구독이 취소된 경우 사용자가 마지막으로 결제한 금액을 환불할 지 여부를 선택하도록 설정할 수 있습니다. 이 기능을 사용하려면 계정 관리자에게 연락하십시오.
플랜 업데이트 방식에서 구독 플랜을 변경할 수 있습니다. 새로운 플랜은 다음 기간부터 적용됩니다.
다음과 같은 경우에는 플랜을 변경할 수 없습니다.
플랜 변경에 실패하면, 구독이 취소됩니다.
기본으로 구독은 사용자가 저장한 결제 세부 정보를 사용하여 자동으로 갱신됩니다. 사용자가 저장할 수 없고 자동 말소를 지원하지 않는 결제 방식을 사용하여 구독을 수동으로 갱신하도록 허용할 수 있습니다. 결제 주기가 끝났을 때 구독을 갱신하려면 사용자는 이메일 알림에서 링크를 따라 이동한 후 갱신해야 합니다. 이 기능을 사용하려면 계정 관리자에게 연락하십시오.
여러 구독에서 동일한 플랜을 사용하는 경우, 구독을 상품의 일부로 판매할 수 있습니다. 상품은 사용자가 구독할 수 있고, 하나의 그룹에 속해있는 플랜의 모음입니다. 서로 다른 상품에 동일한 플랜을 사용할 수 있습니다.
다음 API 방식을 사용하여 상품을 구성합니다. 상품 생성/업데이트/삭제,상품 나열
구독 모듈을 사용하여 인게임 통화 또는 아이템으로 구독을 갱신하는 사용자에게 보상으로 제공할 수 있습니다. 이 기능을 사용하려면, 우선 가상 통화 및/또는 가상 아이템 모듈을 활성화합니다. 의심가는 내용이 있는 경우, 계정 관리자에게 문의합니다.