새로운 Commerce API 메소드 사용 방법
작동 방식
주요 기능:
- 엑솔라 로그인이나 페이 스테이션 액세스 토큰을 통한 인증
- 가상 아이템 관리
- 사용자 인벤토리 관리
- 카트 및 주문 관리
사용자
- 스토어 인터페이스를 구현하고 서버 구현을 위해 서드파티 솔루션을 사용하려고 하는 파트너.
- 이미 엑솔라와의 서버 통합을 구현하고 스토어를 새
Commerce API 메소드로 연결하려고 하는 경우.
획득 방법
앱에
통합하려면 프로젝트 설정 > 웹훅에 표시된 프로젝트 ID가 필요합니다. 프로젝트 ID는
인증 설정
다음 사용자 인증 옵션을 사용할 수 있습니다:
- 엑솔라 로그인 사용. 엑솔라와의 서버 통합을 구현하지 않은 경우 이 옵션을 선택합니다.
- 페이 스테이션 액세스 토큰. 엑솔라와의 서버 통합을 구현한 경우 이 옵션을 선택합니다.
엑솔라 로그인을 통한 인증
- 게시자 계정 프로젝트를 지침에 따라 설정합니다.
- JSON 웹 토큰 혹은 OAuth 2.0 프로토콜을 통하여 인증 메소드 호출을 구현합니다.
사용자 데이터가 엑솔라 데이터 스토리지에 보관되는 경우, 다음 메소드 호출을 구현합니다:
사용자 데이터가 PlayFab 데이터 스토리지에 있는 경우, PlayFab 레시피를 사용하세요.
사용자 데이터를 여러분 자신이 보관하는 경우, 사용자 정의 스토리지 레시피를 사용하세요.
페이 스테이션 액세스 토큰을 통한 인증
인증 절차:
- 애플리케이션(클라이언트)가 서버로 인증 요청을 보냅니다.
- 서버는 판매자 ID 및 API 키를 엑솔라 서버로 보내고 access_token를 요청합니다.
- 엑솔라 서버는 access_token를 서버에 보냅니다.
- 서버는 access_token를 클라이언트에게 보냅니다.
반환된 access_token는
스토어 관리 메소드
스토어 관리 방식에는 다음과 같은 방식 그룹이 포함되어 있습니다.
- 게임 아이템 관리.
- 카트 및 주문 관리.
- 사용자 인벤토리 관리.
Get virtual items list
스토어에 추가된 전체 게임 아이템 목록을 표시하려면 Get virtual items list API 방식을 구현합니다.
예제
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");
xhr.send(data);
//RESPONSE
"items": [
{
"attributes": [],
"description": "Conquer your foes with vindication using the Basic Blaster! ",
"groups": [
"all",
"featured",
"Xsolla",
"weapons"
],
"image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
"is_free": false,
"name": "Xsolla Basic Blaster 1",
"order": 1,
"price": {
"amount": "0.9950000000000000",
"amount_without_discount": "1.9900000000000000",
"currency": "USD"
},
"sku": "gun_1",
"type": "virtual_good"
Get item groups list
- Get item groups list API 메소드를 구현하여 여러분의 스토어에 추가된 가상 아이템 그룹의 전체 목록을 표시합니다.
- 다음의 개별 sku 매개 변수 값은 Get virtual items list 메소드에서 반환되는데 이에 대하여 해당 값이 속하는 그룹의 external_id를 지정합니다. sku와 external_id를 게시자 계정에서 아이템이 그룹 지어진 방식과 같이 일치시킵니다.
예제
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/groups");
xhr.send(data);
//RESPONSE
"groups": [
{
"children": [],
"description": "all",
"external_id": "all",
"id": 10,
"image_url": "http://none",
"level": 0,
"name": "all",
"order": null,
"parent_external_id": null
}
Get cart
가상 아이템 구매를 위하여 Get cart by ID 또는 Get current user’s cart API를 구현합니다. 카트 ID는 아이템 추가/제거에 사용됩니다.
예제
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en¤cy=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"cart_id": "custom_id",
"is_free": true,
"items": [],
"price": null
}
Create order with all items
- 다음 API 메소드 중 하나를 구현합니다:
생성한 주문은 신규 주문 상태를 받게 됩니다.
- 새 창에서 결제 UI를 열려면, 다음 링크를 사용합니다:
https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
, 여기서ACCESS_TOKEN
는 주문 생성 시 받은 토큰입니다. - 결제 프로세스 테스트 방법:
- 다음 URL 사용:
https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
. - 요청에서 sandbox 매개 변수를 true으로 설정합니다.
- 테스트용 은행 카드 목록을 사용합니다.
- 다음 URL 사용:
예제
- js
var data = JSON.stringify({
"currency": "USD",
"locale": "en",
"sandbox": false
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"order_id": 641,
"token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}
Get order
Get order API 메소드를 구현하여 구매가 이미 처리되었는지 확인합니다. 다음 주문 상태가 가능합니다:
- New — 주문이 생성되었으나 지불되지 않음
- Paid — 주문이 지불됨
- Cancelled — 주문이 취소됨
- Done — 주문이 지불되고 아이템이 인벤토리에 추가됨
예제
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"content": {
"is_free": false,
"items": [
{
"is_free": false,
"price": {
"amount": "0.9950",
"amount_without_discount": "1.9900",
"currency": "USD"
},
"quantity": 123,
"sku": "gun_1"
}
],
"price": {
"amount": "122.3850",
"amount_without_discount": "122.3850",
"currency": "USD"
}
},
"order_id": 656,
"status": "new"
}
Get user’s inventory
구매 후 인벤토리에 추가된 아이템 목록을 가져오려면 Get user’s inventory API 가져오기 메소드를 구현합니다.
예제
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"items": [
{
"description": "Conquer your foes with vindication using the Basic Blaster! ",
"image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
"instance_id": null,
"long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
"name": "Xsolla Basic Blaster 1",
"quantity": 22,
"sku": "gun_1",
"type": "virtual_good"
},
{
"description": "Protect your noggin' with style",
"image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
"instance_id": null,
"long_description": "merchant_virtual_items_virtual_item_long_description_159429",
"name": "Xsolla Helmet",
"quantity": 18,
"sku": "helmet_1",
"type": "virtual_good"
}
]
}