Xsolla Documentation - 시작하기

개요

엑솔라 API 포함 사항:

Pay Station API — 결제 UI 및 토큰화 메소드.
Commerce API — 인게임 스토어 및 구매 버튼 모듈을 사용하는 작업 메소드.
Subscription API — 정기결제 메소드.
Publisher Account API — 게시자 계정 프로젝트 및 사용자, 보고서, 지원 티켓을 사용하는 작업 메소드.
Login API — 자체 인터페이스를 이용하는 사용자 인증 메소드(통합 가이드 보기).

엑솔라 API는 REST를 기반으로 구성되어 있습니다. 예측 가능한 리소스 중심의 URL과 함께 API 오류를 HTTP 응답 코드로 표시하도록 구성된 API입니다. 오류를 포함한 API의 모든 응답에서 JSON이 반환됩니다.

HTTP 인증 및 HTTP 동사(verb) 등 상용 HTTP 클라이언트가 이해할 수 있는 기본 HTTP 기능을 사용하며, 교차 원본(cross-origin) 리소스 공유를 지원하여 개발자가 클라이언트측 웹 애플리케이션에서 API 와 보안된 상호작용을 할 수 있도록 했습니다.

엑솔라 API는 다음 Endpoint 경로를 사용합니다.

https://api.xsolla.com — Pay Station API, Commerce API, Publisher Account API
https://login.xsolla.com/api — Login API

대부분의 Endpoint 경로에는 merchant_id 매개변수가 포함되어 있습니다. 이는 애플리케이션이 사용자를 대신하여 작업 중임을 나타냅니다.

요청및응답

엑솔라 API에 대한 요청은

HTTPS를 통해 전송해야 하며
TLS 1.2 이상을 사용해야 하고
인증 매개변수를 포함해야 하며
PUT과 POST 요청에 대해추가 헤더(Content-Type: application/json)를 포함해야 합니다.

Copy

Full screen

Small screen

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

기본적으로 모든 요청은 본문에 있는 JSON으로 데이터를 제공하며 헤더에 Content-Type: application/json를 포함합니다.

API 변경사항

엑솔라는 API로 기능을 변경할 수 있습니다.

엑솔라는 새로운 API 자원을 추가할 수 있습니다.
엑솔라는 선택적 요청 매개변수를 추가할 수 있습니다.
엑솔라는 기존 API 응답에 대한 새로운 속성을 추가할 수 있습니다.
엑솔라는 나열된 값들의 묶음들로 이루어진 기존 매개변수에 새 값들을 추가할 수 있습니다.
엑솔라는 JSON에 새 webhook 타입들과 매개변수들을 추가할 수 있습니다.
엑솔라는 선택적 HTTP 요청 헤더를 추가할 수 있습니다.
엑솔라는 유효한 매개변수에 유효하지 않은 매개변수 값이 포함된 요청을 거부할 수 있습니다.
지나치게 관대한 파싱으로 인해 승인된 부적절한 형식의 요청들은 파싱로직이 올바르다면 거부될 수도 있습니다.
엑솔라는 언제든지 문서화되지 않은 기능을 추가, 변경 또는 제거할 수 있습니다.

당신의 고객은 이러한 변경사항과 관계없이 계속 운영할 수 있어야만 합니다. 예를 들어, 클라이언트가 알아채지 못한 새로운 JSON 매개변수로 인해 제대로 동작하는 능력이 방해받지는 않습니다.

버전 관리

모든 엑솔라 API 방식은 버전 관리를 지원합니다. 현재 버전과 호환되지 않는 변경 사항이 있을 때마다 새 버전을 발행합니다. 이러한 버전은 "v1"/"v2" 등으로 식별하며 URL에 "/merchant"와 같은 식별자가 붙습니다.

API를 처음으로 사용하는 경우 최신 버전을 사용하도록 합니다. 버전을 생략하는 경우, 기본값으로 첫 번째 버전을 사용합니다.

Info: 동일한 버전을 사용하는 경우에만 API 무결성이 보장됩니다.

인증

엑솔라 API는 기본 액세스 인증을 사용합니다. 모든 API 요청에는 Authorization: Basic <your_authorization_basic_key> 헤더가 있어야 합니다. <your_authorization_basic_key>여기에는 Base64 표준에 따라 인코딩된 merchant_id:api_key 페어가 있습니다.

엑솔라 게시자 계정으로 이동하여 merchant_id와 api_key 매개변수를 찾으십시오.

merchant_id: 회사 설정 > 회사 > 판매자 ID
api_key: 회사 설정 > API 키

Notice:

여러분의 API 키를 잘 보관하세요. 이를 통해 개인 계정과 게시자 계정의 프로젝트에 접근할 수 있습니다.
API 키를 변경하면 모든 프로젝트에 대한 지불이 중단될 수 있습니다. 신규 키로 업데이트하기 전까지는 현재 키를 사용하는 API 호출은 작동하지 않게 됩니다.

Copy

Full screen

Small screen

http

예시:

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>

curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'

<?php

// if you use Xsolla SDK for PHP
use Xsolla\SDK\API\XsollaClient;
$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$eventsList = $client->ListEvents(array());

// if you don’t use Xsolla SDK for PHP
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key>" }

conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
  .get()
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

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://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Endpoint 형식

Endpoint 형식이란 처리할 데이터 형식과 해당 데이터에서 수행하는 작업을 나타냅니다. 가장 일반적인 작업은 다음과 같습니다:

동작	HTTP 방식	설명
Create	`POST`	해당 형식의 엔터티를 생성하고 유지합니다.
List	`GET`	입력한 쿼리 파라미터와 일치하는 모든 엔터티에 대한 요약 정보가 리턴됩니다. 특정 엔터티에 대한 전체 정보를 얻으려면 먼저 List endpoint를 통해 엔터티 ID를 가져온 다음 해당 Retrieve endpoint에 ID를 입력합니다.
Retrieve	`GET`	입력한 식별자와 일치하는 단일 엔터티에 대한 전체 정보를 제공합니다.
Replace	`PUT`	입력한 식별자와 일치하는 기존 엔터티의 모든 필드를 수정합니다.
Update	`PATCH`	입력한 식별자와 일치하는 기존 엔터티의 모든 필드를 수정합니다.
Delete	`DELETE`	입력한 식별자와 일치하는 기존 엔터티를 삭제합니다.

날짜 형식

모든 날짜는 ISO 8601 형식의 문자열로 표현합니다. UTC(예: 2013-01-15T00:00:00Z) 또는 UTC에 시차를 가감한(UTC보다 8시간 늦을 경우의 예: 2013-01-15T00:00:00-08:00) 날짜 문자열을 입력하여 시간대를 표시할 수 있습니다. 시차를 가감한 날짜를 입력할 때는 정확한 서머 타임을 고려하도록 하십시오.

페이징

List endpoint 리스트는 리턴한 결과에 페이지를 매길 수도 있습니다. 이 말은 전체 결과를 단일 응답으로 리턴하지않고, 다음 결과와 연결된 응답 헤더와 함께 일부 결과만 리턴 할수있다는 뜻입니다. 이를 위해 offset 및 limit 파라미터 가 사용됩니다.

오류 처리

지원 HTTP 오류 목록:

200, 201, 204 — 오류 없음
400 Bad Request — 보통 필수 매개 변수가 누락되었음을 나타냅니다. 자세한내용은 응답 본문을 참조합니다.
401 Unauthorized — 제공된 유효한 API 키가 없습니다.
402 Request Failed — 유효한 매개 변수이지만 요청이 실패했습니다.
403 Forbidden — 권한이 없습니다. 자세한내용은 응답 본문을 참조합니다.
404 Not Found — 요청한 항목이 존재하지 않습니다.
409, 422 — 잘못된 요청 매개 변수입니다.
412 Precondition Failed — 프로젝트가 아직 활성화되지 않았습니다(토큰 가져오기 방식에서 사용).
415 Unsupported Media Type — HTTP 헤더에 "Content-Type: application/json"이 없습니다.
500, 502, 503, 504 Server Errors — 문제가 발생했습니다.

엑솔라는 기본 HTTP 응답 코드를 사용하여 API 요청의 성공 또는 실패를 표시합니다. 일반적으로 2xx 코드는 성공을 뜻하고, 4xx 코드는 입력한 정보로 인한 오류(예: 필수 파라미터 누락, 인증 실패 등)를 나타내며, 5xx 코드는 엑솔라 서버와 관련된 오류를 나타냅니다.

하지만 모든 오류를 HTTP응답 코드에 명확히 대응시킬 수 있는 것은 아닙니다. 올바른 요청인 경우에도 성공적으로 완료되지 않으면 422 오류가 반환됩니다.

모든 API 오류 응답은 json 개체에 다음 필드를 제공합니다.

{< T "api_table_name" >}}	유형	설명
http_status_code	integer	HTTP 코드
message	string	판독 가능한 메시지로서 오류를 설명합니다. 이 메시지는 항상 영문입니다. 특정 오류에 대한 설명은 나중에 변경될 수도 있습니다.
extended_message	string	오류에 대한 확장된 설명입니다.
request_id	string	문제 해결에 도움이 될 수 있는 고유한 ID입니다.

Copy

Full screen

Small screen

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

웹훅

개요

엑솔라 트랜잭션에 발생한 이벤트에 대한 알림을 받으려면 Webhook을 사용하십시오. Webhook을 사용하면 상태 및 기타 트랜잭션 관련 정보 제공과 같은 백오피스 및 관리 기능을 자동화할 수 있습니다.

웹훅은 다음과 같은 이벤트에 대한 알림을 보낼 때 사용하는 서비스입니다.

인게임 재화 및 아이템 구매, 은행 카드 결제 등
정기 결제 및 구독 작업
트랜잭션과 관련된 승인 실패/환불

많은 경우에 Webhook을 작동시키는 것은 개발자 웹 사이트에서의 게임유저 작업입니다. 하지만 그외 작업도 Webhook을 작동시킬 수 있습니다. 예를 들어, 개발자 사이트의 백오피스 프로세스가 환불을 위해 엑솔라 API를 호출하거나, 결제 시스템이 엑솔라에게 부정 결제를 알릴 수 있습니다.

Webhook은 개발자가 직접 작성한 프로그램인 수신기(핸들러)를 통해 수신하여 처리합니다. 이 프로그램은 Webhook을 대기했다가, 적절히 응답하여 관리자 프로세스로 전달합니다.

개발자측 작업의 예:

게임유저의 잔액 충전하기
새 아이템 잠금 해제하기
정기결제 서비스 시작하기
부정결제 감지 후 게임유저 차단하기

다음 IP 주소의 Webhook을 수락해야 합니다: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.

Notice: 데이터베이스에 동일한 ID의 트랜잭션이 중복 되어서는 안됩니다. 시스템이 데이터베이스에 이미 존재하는 ID로 Webhook을 다시 보내면 이전 요청 처리 결과를 리턴합니다. 게임유저에게 구매 정보를 다시 제공하거나 데이터베이스에 중복된 값을 생성하지 마십시오.

Webhook 서비스는 알림을 받을 서버에서 모든 Webhook을 수신할 것이라고 가정하지 않습니다. 인터넷 안정성은 100%가 아니기에 웹훅이 소실되거나 지연될 수 있습니다. 또한, 수신 장치에서 귀하의 서버의 일시적인 오류에 대해 5xx HTTP 코드를 반환할 수도 있습니다. 예를 들어 사용자가 구매한 가상 상품을 성공적으로 사용자 인벤토리에 추가하지 못한 경우 수신 장치는 500 HTTP 응답 코드를 반환합니다.

문제의 해결을 위해 Webhook 서비스에는 서버가 수신할 때까지 다양한 간격으로 메시지를 재전송하는 기능이 있습니다. Webhook은 원본 메시지를 전송하고 나서 최대 12시간 후까지 재전송할 수 있습니다. 재전송 시도 최대 횟수는 12회입니다.

Note: 연결 문제로 인해 웹훅 소실, 지연, 중복 현상이 나타나더라도 보통 수신측의 자체 논리 오류로 인해 이러한 문제가 발생하는 경우가 많습니다.

서명 요청

전자 서명은 데이터 전송에 보안을 제공합니다. 서명 생성은 두 가지 단계로 이뤄집니다. 첫 번째 단계는 JSON 콘텐츠와 프로젝트 시크릿 키를 연결하는 것입니다. 두 번째 단계는 첫 번째 단계에서 얻어진 콘텐츠에SHA-1암호화 해시 기능을 사용하는 것으로 구성됩니다.

생성한 서명이 HTTP 헤더에서 통과된 서명과 동일한지 확인해야 합니다.

Copy

Full screen

Small screen

http

요청

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}

$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

응답

엑솔라는 기본 HTTP 응답 코드를 사용하여 결제 알림(IPN) 요청의 성공 또는 실패를 표시합니다. 코드 204는 결제 수신 성공을 나타냅니다. 400 코드를 제공해야 하는 영구적인 오류가 있을 경우, 제공된 정보(예: 필수 파라미터 누락, 결제 실패 등)로 인한 오류를 표시합니다. 코드 500은 일시적 서버 오류를 나타냅니다.

Webhook 목록

알림 유형은 notification_type 파라미터로 보냅니다.

알림 유형	설명
user_validation	게임 시스템 내 유저의 존재를 확인해 줍니다.
user_search	공개 사용자 ID별로 사용자 정보를 가져옵니다.
payment	유저가 결제 프로세스를 완료했을 때 보냅니다.
refund	알수없는이유로결제가취소되었을때보냅니다.
afs_reject	AFS 확인 중에 거래가 거부된 경우.
afs_black_list	AFS 차단 목록이 업데이트될 때 보냅니다.
create_subscription	유저가 정기 결제를 만들면 보냅니다.
update_subscription	정기 결제를 업데이트되었을 때 보냅니다.
cancel_subscription	정기 결제를 취소되었을 때 보냅니다.
non_renewal_subscription	상태가 비갱신으로 설정되면 전송됨.
get_pincode	게임 키를 얻어야 하는 경우 전송됩니다.
user_balance_operation	유저 잔고에 변화가 있을 때 보냅니다 (작업 유형을 operation_type 으로 보냄).
redeem_key	사용자가 키를 활성화하면 보냅니다.
upgrade_refund	업그레이드가 취소되었을 때 전송합니다.
payment_account_add	사용자가 결제 계정을 추가하거나 저장할 때 전송됨.
payment_account_remove	사용자가 저장된 계정에서 결제 계정을 제거할 때 전송됨.

게임유저 유효성 검사

엑솔라 서버가 게임 내 캐릭터 존재를 확인하기 위해 결제 알림 스크립트에 요청을 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.ip	string	유저 IP 주소입니다.
user.phone	string	유저 전화 번호입니다(국제 형식).
user.email	string	사용자 이메일.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.country	string	사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'user_validation',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "user_validation",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}

$ 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":"user_validation",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },    
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isUserValidation()) {
       $userArray = $message->getUser();
       $userId = $message->getUserId();
       $messageArray = $message->toArray();
       //TODO if user not found, you should throw InvalidUserException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

사용자 검색

엑솔라 서버가 공개 사용자 ID별로 사용자에 대한 정보를 가져오기 위해 Webhook URL로 요청을 보냅니다.공개 사용자 ID - 고유하게 사용자를 식별할 수 있고 사용자 ID와 달리 사용자에 대해 알려진 매개 변수(이메일, 애칭 등)입니다. 이 webhook은 게임 스토어 외부에서 구매할 수 있는 경우 사용됩니다(예: 캐시 키오스크의 게임 버튼).

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다. 필수.
user.public_id	string	공개 사용자 ID입니다.
user.id	string	사용자 ID.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'user_search',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'public_id' => 'public_email@example.com'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "user_search",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "public_id": "public_email@example.com"
    }
}

$ 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": "user_search",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "public_id": "public_email@example.com"
    }
}'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;

$callback = function (Message $message) {
    if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
        $userArray = $message->getUser();
        $userPublicId = $message->getUserPublicId();
        // TODO get a user from your database and fill the user data to model.
        $user = new \Xsolla\SDK\Webhook\User();
        $user->setId('user_id')
            ->setPublicId($userPublicId)
            ->setEmail('user_email') //Optional field
            ->setPhone('user_phone') //Optional field
            ->setName('user_name'); //Optional field
        //TODO if user not found, you should throw InvalidUserException
        return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}

{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}

결제

게임유저가 결제 프로세스를 완료할 때마다 트랜잭션 세부 사항을 결제 알림 스크립트에 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
purchase	object	구매 데이터 관련 값입니다.
purchase.virtual_currency	object	구매 게임머니 데이터와 관련된 값입니다.
purchase.virtual_currency.name	string	게임머니 이름.
purchase.virtual_currency.sku	string	게임머니 패키지 SKU입니다(게임머니 패키지에 대해 설정된 경우).
purchase.virtual_currency.quantity	float	가상 항목의 수량입니다.
purchase.virtual_currency.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.virtual_currency.amount	float	구매 금액입니다.
purchase.checkout	object	결제 파라미터 데이터와 관련된 값입니다.
purchase.checkout.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.checkout.amount	float	구매 금액입니다.
purchase.subscription	object	정기결제 세부 정보(오브젝트).
purchase.subscription.plan_id	string	요금제 ID(API를 통해 생성된 경우, 외부 ID).
purchase.subscription.subscription_id	integer	엑솔라 시스템 내의 정기결제 ID입니다.
purchase.subscription.product_id	string	상품 ID(액세스 토큰으로 보낸 경우)입니다.
purchase.subscription.tags	array	플랜 태그.
purchase.subscription.date_create	string	정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
purchase.subscription.date_next_charge	string	다음 충전 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
purchase.subscription.currency	string	정기결제 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.subscription.amount	float	구매 금액입니다.
purchase.virtual_items	object	게임 아이템 구매 데이터와 관련된 값입니다.
purchase.virtual_items.items	array	아이템 구매 데이터와 관련된 배열입니다.
purchase.virtual_items.items.sku	string	아이템 ID입니다.
purchase.virtual_items.items.amount	integer	아이템 수량입니다.
purchase.virtual_items.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.virtual_items.amount	float	구매 금액입니다.
purchase.pin_codes	object	게임 키에 대한 데이터가 포함된 배열입니다.
purchase.pin_codes.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.drm	string	게임을 배포하는데 사용되는 DRM 플랫폼으로서 `steam`, `playstation`, `xbox`, `uplay`, `origin`, `drmfree`, `gog`, `epicgames`, `nintendo_eshop`, `discord_game_store` 혹은 `oculus`가 될 수 있습니다. 게시자 계정에서 필요한 DRM을 구성했는지 확인하십시오.
purchase.pin_codes.currency	string	게임 키의 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.pin_codes.amount	float	PIN 코드의 가격입니다.
purchase.pin_codes.upgrade	object	업그레이드 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_from	object	사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_from.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.upgrade.digital_content_from.DRM	string	게임 DRM플랫폼.
purchase.pin_codes.upgrade.digital_content_to	object	사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_to.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.upgrade.digital_content_to.DRM	string	게임 DRM플랫폼.
purchase.pin_codes.upgrade.currency	string	구매 통화입니다. ISO 4217에 따른 3자리 통화 코드입니다.
purchase.pin_codes.upgrade.amount	float	구매 금액입니다.
purchase.gift	object	기프트에 대한 데이터를 포함하고 있는 객체입니다.
purchase.gift.giver_id	string	제공자 ID.
purchase.gift.receiver_id	string	기프트 수령인 ID.
purchase.gift.receiver_email	string	기프트 수령인 이메일.
purchase.gift.message	string	제공자로부터 전송된 메시지.
purchase.gift.hide_giver_from_receiver	string	수신자에서 제공자 ID를 숨길지 여부.
purchase.total	object	구매 총 가격 데이터와 관련된 값입니다. 필수.
purchase.total.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.total.amount	float	총 구매 금액입니다.
purchase.promotions	array	이 트랜잭션에 적용된 프로모션 데이터와 관련된 배열입니다.
purchase.promotions.technical_name	string	프로모션의 기술명입니다.
purchase.promotions.id	integer	프로모션 ID입니다.
purchase.coupon	object	쿠폰 데이터 관련 값입니다(이 트랜잭션에 쿠폰이 사용된 경우).
purchase.coupon.coupon_code	string	쿠폰 코드.
purchase.coupon.campaign_code	string	쿠폰 캠페인 코드입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.ip	string	유저 IP 주소입니다.
user.phone	string	유저 전화 번호입니다(국제 형식).
user.email	string	사용자 이메일.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.country	string	사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
user.zip	string	우편번호.
transaction	object	트랜잭션 데이터 관련 값입니다. 필수.
transaction.id	integer	트랜잭션 ID.
transaction.external_id	string	트랜잭션 외부 ID 입니다.
transaction.payment_date	string	결제 날짜입니다.
transaction.payment_method	integer	결제 방식 식별자.
transaction.payment_method_order_id	string	결제 시스템의 결제 ID.
transaction.dry_run	integer	테스트 트랜잭션(거래). 테스트 트랜잭션의 경우 매개변수는 1개 값을 갖습니다. 또는, 트랜잭션(거래)이 실제로 이루어지는 경우 매개변수가 전송되지 않습니다.
transaction.agreement	integer	계약 ID입니다.
payment_details	object	결제 내역 관련 값입니다. 필수.
payment_details.payment	object	게임유저 결제 데이터 관련 값입니다.
payment_details.payment.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payment.amount	string	총계.
payment_details.payment_method_sum	object	결제 방법에서 청구된 금액에 대한 데이터가 포함된 값입니다.
payment_details.payment_method_sum.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payment_method_sum.amount	string	총계.
payment_details.xsolla_balance_sum	object	엑솔라 잔액에서 청구된 금액에 대한 데이터가 포함된 값입니다.
payment_details.xsolla_balance_sum.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.xsolla_balance_sum.amount	string	총계.
payment_details.payout	object	지급 내역 관련 값입니다.
payment_details.payout.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payout.amount	float	총계.
payment_details.vat	object	VAT 세율입니다(유럽연합만 해당).
payment_details.vat.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.vat.amount	float	총계.
payment_details.payout_currency_rate	float	결제 통화를 지급 통화로 환전할 때의 환율입니다.
payment_details.xsolla_fee	object	엑솔라 수수료 요율입니다.
payment_details.xsolla_fee.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.xsolla_fee.amount	float	총계.
payment_details.payment_method_fee	object	결제 방식 수수료율입니다.
payment_details.payment_method_fee.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payment_method_fee.amount	float	총계.
payment_details.sales_tax	object	판매세(대상; 미국과 캐나다만).
payment_details.sales_tax.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.sales_tax.amount	float	총계.
payment_details.direct_wht	object	직접 원천징수세.
payment_details.direct_wht.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.direct_wht.amount	float	금액.
payment_details.repatriation_commission	object	본국 송금 비용에 대한 데이터가 있는 오브젝트. 타사가 엑솔라에 부과.
payment_details.repatriation_commission.currency	string	본국 송금 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.repatriation_commission.amount	float	본국 송금 비용.
custom_parameters	object	사용자 지정 파라미터입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'payment',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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,
        'payment_method_order_id' => 1234567890123456789,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'sales_tax' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'direct_wht' => array(
            'currency' => 'USD',
            'amount' => 70
        ),
        '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
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542

{
    "notification_type": "payment",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "purchase":{
        "virtual_currency": {
            "name": "Coins",
            "sku": "test_package1",
            "quantity": 10,
            "currency": "USD",
            "amount": 100
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-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
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": "853"
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        }
    },
    "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,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0.70
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": "10"
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}

$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type": "payment",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "purchase": {
        "virtual_currency": {
            "name": "Coins",
            "sku": "test_package1",
            "quantity": 10,
            "currency": "USD",
            "amount": 100
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-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
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": "853"
        }],
        "coupon": {
             "coupon_code": "ICvj45S4FUOyy",
             "campaign_code": "1507"
        }
    },
    "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,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0.70
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": "10"
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isPayment()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $messageArray = $message->toArray();
        // TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

환불

지불이 취소될 때마다 전송됩니다. 지불 세부 내역을 포함합니다. 레시피에서 환불 절차에 대해 자세히 알아보세요.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
purchase	object	구매 데이터 관련 값입니다.
purchase.virtual_currency	object	구매 게임머니 데이터와 관련된 값입니다.
purchase.virtual_currency.name	string	게임머니 이름.
purchase.virtual_currency.quantity	float	가상 항목의 수량입니다.
purchase.virtual_currency.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.virtual_currency.amount	float	구매 금액입니다.
purchase.checkout	object	결제 파라미터 데이터와 관련된 값입니다.
purchase.checkout.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.checkout.amount	float	구매 금액입니다.
purchase.subscription	object	정기결제 세부 정보(오브젝트).
purchase.subscription.plan_id	string	요금제 ID(API를 통해 생성된 경우, 외부 ID).
purchase.subscription.tags	array	플랜 태그.
purchase.subscription.subscription_id	integer	엑솔라 시스템 내의 정기결제 ID입니다.
purchase.subscription.date_create	string	정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
purchase.subscription.currency	string	정기결제 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.subscription.amount	float	구매 금액입니다.
purchase.virtual_items	object	게임 아이템 구매 데이터와 관련된 값입니다.
purchase.virtual_items.items	array	아이템 구매 데이터와 관련된 배열입니다.
purchase.virtual_items.items.sku	string	아이템 ID입니다.
purchase.virtual_items.items.amount	integer	아이템 수량입니다.
purchase.virtual_items.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.virtual_items.amount	float	구매 금액입니다.
purchase.pin_codes	object	게임 키에 데이터가 포함된 값입니다.
purchase.pin_codes.upgrade	object	업그레이드 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_from	object	사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_from.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.upgrade.digital_content_from.DRM	string	게임 DRM플랫폼.
purchase.pin_codes.upgrade.digital_content_to	object	사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_to.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.upgrade.digital_content_to.DRM	string	게임 DRM플랫폼.
purchase.pin_codes.upgrade.currency	string	구매 통화입니다. ISO 4217에 따른 3자리 통화 코드입니다.
purchase.pin_codes.upgrade.amount	float	구매 금액입니다.
purchase.total	object	구매 총 가격 데이터와 관련된 값입니다.
purchase.total.currency	string	구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.total.amount	float	총 구매 금액입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.ip	string	유저 IP 주소입니다.
user.phone	string	유저 전화 번호입니다(국제 형식).
user.email	string	사용자 이메일.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.country	string	사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
user.zip	string	우편번호.
transaction	object	트랜잭션 데이터 관련 값입니다. 필수.
transaction.id	integer	트랜잭션 ID.
transaction.external_id	string	트랜잭션 외부 ID 입니다.
transaction.dry_run	integer	테스트 트랜잭션(거래). 테스트 트랜잭션의 경우 매개변수는 1개 값을 갖습니다. 또는, 트랜잭션(거래)이 실제로 이루어지는 경우 매개변수가 전송되지 않습니다.
transaction.agreement	integer	계약 ID입니다.
refund_details	object	환불 세부 정보(오브젝트).
refund_details.code	integer	코드 ID.
refund_details.reason	string	환불 이유입니다.
refund_details.author	string	환불 개시 프로그램.
payment_details	object	결제 내역 관련 값입니다. 필수.
payment_details.payment	object	게임유저 결제 데이터 관련 값입니다.
payment_details.payment.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payment.amount	string	총계.
payment_details.payment_method_sum	object	결제 방법에서 청구된 금액에 대한 데이터가 포함된 값입니다.
payment_details.payment_method_sum.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payment_method_sum.amount	string	총계.
payment_details.xsolla_balance_sum	object	엑솔라 잔액에서 청구된 금액에 대한 데이터가 포함된 값입니다.
payment_details.xsolla_balance_sum.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.xsolla_balance_sum.amount	string	총계.
payment_details.payout	object	지급 내역 관련 값입니다.
payment_details.payout.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payout.amount	float	총계.
payment_details.vat	object	VAT 세율입니다(유럽연합만 해당).
payment_details.vat.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.vat.amount	float	총계.
payment_details.payout_currency_rate	float	결제 통화를 지급 통화로 환전할 때의 환율입니다.
payment_details.xsolla_fee	object	엑솔라 수수료 요율입니다.
payment_details.xsolla_fee.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.xsolla_fee.amount	float	총계.
payment_details.payment_method_fee	object	결제 방식 수수료율입니다.
payment_details.payment_method_fee.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.payment_method_fee.amount	float	총계.
payment_details.sales_tax	object	판매세(대상; 미국과 캐나다만).
payment_details.sales_tax.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.sales_tax.amount	float	총계.
payment_details.direct_wht	object	직접 원천징수세.
payment_details.direct_wht.currency	string	통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.direct_wht.amount	float	총계.
payment_details.repatriation_commission	object	본국 송금 비용에 대한 데이터가 있는 오브젝트. 타사가 엑솔라에 부과.
payment_details.repatriation_commission.currency	string	본국 송금 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
payment_details.repatriation_commission.amount	float	본국 송금 비용.
custom_parameters	object	사용자 지정 파라미터입니다.

환불 코드:

코드	환불 이유	설명
1.	Cancellation by the user request / the game request.	판매자 계정에서 취소가 요청된 경우 사용됩니다.
2.	지불 거절.	트랜잭션 지불 거절이 요청되었습니다.
3.	Integration Error.	엑솔라와 게임 사이의 연동에 문제가 있을 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
4.	Fraud.	부정결제 가능성이 있을 경우 사용됩니다.
5.	Test Payment.	테스트 트랜잭션인 경우 사용되며 이후 취소로 이어집니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
6.	Expired Invoice.	후불 결제 방식에 의해 트랜잭션이 이뤄진 경우 사용됩니다.
7.	PS debt cancel.	결제 방식에 의해 트랜잭션이 이뤄졌지만 지급 거절된 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
8.	Cancellation by the PS request.	결제시스템이 취소를 요청한 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
9.	Cancellation by the user request.	게임유저의 요청에 의한 환불 사유입니다. 어떤 이유로 게임유저가 게임 또는 구매에 만족하지 못한 못하였음을 의미합니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
10.	Cancellation by the game request.	게임이 취소를 요청한 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
11.	Account holder called to report fraud.	계정 소유자가 본인 미사용 결제로 신고한 경우입니다.
12.	Friendly fraud.	우호적인 부정결제에 대한 메시지를 수신했을 때 사용됩니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'refund',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),    
    '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' => array(
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'sales_tax' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'direct_wht' => array(
            'currency' => 'USD',
            'amount' => 70
        ),
        '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
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
    "notification_type": "refund",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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": {
        "sales_tax": {
            "currency": "USD",
            "amount": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0.70
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": "10"
        },
        "payout": {
            "currency": "USD",
            "amount": "200"
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": "20"
        },
        "payment": {
            "currency": "USD",
            "amount": "230"
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": "10"
        }
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "refund",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": "10"
            }
        }
    }
}'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isRefund()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

업그레이드 환불

사용자가 업그레이드와 관련된 결제를 환불하면 엑솔라는 취소된 모든 업그레이듣 및 현재 게임 패키지를 웹훅 URL로 전송합니다.

파라미터	유형	설명
notification_type	string	알림 유형. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
purchase	object	구매 데이터가 있는 객체입니다. 필수.
purchase.pin_codes	object	구매한 게임 패키지 데이터가 있는 객체입니다.
purchase.pin_codes.purchase_type	string	구매 유형. `regular`(패키지 구매) 또는 `upgrade`(패키지 업그레이드) 가능.
purchase.pin_codes.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.DRM	string	게임 DRM플랫폼.
purchase.pin_codes.currency	string	구매 통화입니다. ISO 4217에 따른 3자리 통화 코드입니다.
purchase.pin_codes.amount	float	구매 금액입니다.
purchase.pin_codes.transaction	object	거래 데이터가 있는 객체입니다.
purchase.pin_codes.transaction.id	integer	트랜잭션 ID.
purchase.pin_codes.upgrade	object	업그레이드 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_from	object	사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_from.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.upgrade.digital_content_from.DRM	string	게임 DRM플랫폼.
purchase.pin_codes.upgrade.digital_content_to	object	사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.
purchase.pin_codes.upgrade.digital_content_to.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
purchase.pin_codes.upgrade.digital_content_to.DRM	string	게임 DRM플랫폼.
소유권	object	사용자가 소유한 패키지의 데이터가 있는 객체입니다. 필수.
ownership.digital_content	string	판매자 계정으로 설정된 게임의 SKU입니다.
ownership.DRM	string	게임 DRM플랫폼.

Copy

Full screen

Small screen

php

요청

<?php

$request = array (
  'notification_type' => 'upgrade_refund',
  'settings' => array(
     'project_id' => 18404,
     'merchant_id' => 2340
  ),
  'purchase' =>
  array (
    'pin_codes' =>
    array (
      0 =>
      array (
        'purchase_type' => 'regular',
        'digital_content' => 'silver',
        'DRM' => 'drmfree',
        'currency' => 'USD',
        'amount' => 40,
        'transaction' =>
        array (
          'id' => '361697569',
        ),
      ),
      1 =>
      array (
        'purchase_type' => 'upgrade',
        'upgrade' =>
        array (
          'digital_content_from' =>
          array (
            'digital_content' => 'silver',
            'DRM' => 'drmfree',
          ),
          'digital_content_to' =>
          array (
            'digital_content' => 'gold',
            'DRM' => 'drmfree',
          ),
        ),
        'currency' => 'USD',
        'amount' => 20,
        'transaction' =>
        array (
          'id' => '361697570'
        ),
      ),
      2 =>
      array (
        'purchase_type' => 'upgrade',
        'upgrade' =>
        array (
          'digital_content_from' =>
          array (
            'digital_content' => 'gold',
            'DRM' => 'drmfree',
          ),
          'digital_content_to' =>
          array (
            'digital_content' => 'platinum',
            'DRM' => 'drmfree',
          ),
        ),
        'currency' => 'USD',
        'amount' => 20,
        'transaction' =>
        array (
          'id' => '361697571'
        ),
      ),
    ),
  ),
  'ownership' =>
  array (
    'digital_content' => NULL,
    'DRM' => NULL,
  ),
)

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Authorization: Signature <signature>

{
  "notification_type": "upgrade_refund",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "purchase": {
    "pin_codes": [
      {
        "purchase_type": "regular",
        "digital_content": "silver",
        "DRM": "drmfree",
        "currency": "USD",
        "amount": "40",
        "transaction": {
          "id": "361697569"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "silver",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "gold",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697570"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "gold",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "platinum",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697571"
        }
      }
    ]
  },
  "ownership": {
    "digital_content": null,
    "DRM": null
  }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type": "upgrade_refund",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "purchase": {
    "pin_codes": [
      {
        "purchase_type": "regular",
        "digital_content": "silver",
        "DRM": "drmfree",
        "currency": "USD",
        "amount": "40",
        "transaction": {
          "id": "361697569"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "silver",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "gold",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697570"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "gold",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "platinum",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697571"
        }
      }
    ]
  },
  "ownership": {
    "digital_content": null,
    "DRM": null
  }
}'

응답

AFS 거부 거래

AFS 확인 중에 거래가 거부된 경우, 엑솔라에서 거래 세부 정보를 URL 웹훅으로 전송합니다. 이 알림을 활성화하려면 계정 관리자에게 문의하세요.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.ip	string	유저 IP 주소입니다.
user.phone	string	유저 전화 번호입니다(국제 형식).
user.email	string	사용자 이메일.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.country	string	사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
user.zip	string	우편번호.
transaction	object	트랜잭션 데이터 관련 값입니다. 필수.
transaction.id	integer	트랜잭션 ID.
transaction.external_id	string	트랜잭션 외부 ID 입니다.
transaction.dry_run	integer	테스트 트랜잭션(거래). 테스트 트랜잭션의 경우 매개변수는 1개 값을 갖습니다. 또는, 트랜잭션(거래)이 실제로 이루어지는 경우 매개변수가 전송되지 않습니다.
transaction.agreement	integer	계약 ID입니다.
refund_details	object	환불 세부 정보(오브젝트).
refund_details.code	integer	코드 ID.
refund_details.reason	string	환불 이유입니다.
refund_details.author	string	환불 개시 프로그램.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
  'notification_type' => 'afs_reject',
  'settings' => array(
    'project_id' => 18404,
    'merchant_id' => 2340
  ),
  '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' => array(
    'code' => 4,
    'reason' => 'Potential fraud'
  )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
  "notification_type": "afs_reject",
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "user": {
    "ip": "127.0.0.1",
    "phone": "18777976552",
    "email": "semail@example.com",
    "id": "1234567",
    "name": "Xsolla User",
    "country": "US"
  },
  "transaction": {
    "id": 1,
    "external_id": 1,
    "dry_run": 1,
    "agreement": 1
  },
  "refund_details": {
    "code": 4,
    "reason": "Potential fraud"
  }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type": "afs_reject",
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "user": {
    "ip": "127.0.0.1",
    "phone": "18777976552",
    "email": "semail@example.com",
    "id": "1234567",
    "name": "Xsolla User",
    "country": "US"
  },
  "transaction": {
    "id": 1,
    "external_id": 1,
    "dry_run": 1,
    "agreement": 1
  },
  "refund_details": {
    "code": 4,
    "reason": "Potential fraud"
  }
}'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
  if ($message->isRefund()) {
    $userArray = $message->getUser();
    $paymentArray = $message->getTransaction();
    $paymentId = $message->getPaymentId();
    $externalPaymentId = $message->getExternalPaymentId();
    $customParametersArray = $message->getCustomParameters();
    $isDryRun = $message->isDryRun();
    $refundArray = $message->getRefundDetails();
    $messageArray = $message->toArray();
    // TODO if you cannot handle the refund, you should throw XsollaWebhookException
  }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

AFS 업데이트된 차단 목록

AFS 차단 목록이 업데이트되었을 때(매개 변수 추가 또는 제거), 엑솔라가 알림을 웹훅 URL에 보냅니다. 매개 변수 추가는 자동으로 엑솔라 측에서 수행되거나 요청 시에 수행됩니다. 매개 변수 제거는 요청 시에만 가능합니다. 이 알림을 활성화하려면 계정 관리자에게 문의하십시오.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
event	object	AFS 차단 목록 이벤트에 대한 정보가 있는 개체. 필수.
event.action	string	이벤트 유형. 가능한 값: `adding`, `removing`.
event.reason	string	이벤트 원인. 가능한 값: 추가: `chargeback` — 지불 거절, `fraud_activity` — 사기, `suspicious_activity` — 의심스러운 활동, `ps_reported_fraud` — 사기 관련 결제 시스템 알림, `linked_chargeback` — 지불 거절 관련, `partner_request` — 요청 시, `friendly_fraud` — 우호적인 사기, `user_reported_fraud` — 사용자가 사기에 대해 보고, `linked_parameter` — AFS 차단 목록의 연결된 매개 변수, `other_data_in_blacklist` — AFS 차단 목록의 다른 매개 변수, `by_afs_filters` — AFS 필터. 제거: `wrongly_added` — 실수로 추가됨, `removed_by_cs_review` — 엑솔라 기술 지원팀에 보고 후 제거됨, `other_forgiveness_reason` — 제거에 대한 다른 이유.
event.parameter	string	이벤트가 발생한 매개 변수 이름. 가능한 값: `nick` — 사용자의 별명, `email` — 사용자의 이메일 주소, `ps_account` — 사용자의 청구 계정, `ip_address` — 사용자의 IP 주소, `card_issuer` — 사용자의 신용 카드 발행 은행, `phone` — 사용자의 전화번호.
event.parameter_value	string	이벤트가 발생하는 매개 변수의 값.
event.date_of_last_action	string	가장 최근의 ISO 8601 형식의 AFS 차단 목록 이벤트.
event.transaction_id	string	이벤트가 발생한 매개 변수와 관련된 트랜잭션 ID.

Copy

Full screen

Small screen

http

요청

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 233
Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6

{
  "event": {
    "action": "adding",
    "date_of_last_action": "2020-11-27T10:09:05+03:00",
    "parameter": "email",
    "parameter_value": "some_cool_email@gmail.com",
    "reason": "ps_reported_fraud",
    "transaction_id": "111111111"
  },
  "notification_type": "afs_black_list"
}

$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
-d '{
  "event": {
    "action": "adding",
    "date_of_last_action": "2020-11-27T10:09:05+03:00",
    "parameter": "email",
    "parameter_value": "some_cool_email@gmail.com",
    "reason": "ps_reported_fraud",
    "transaction_id": "111111111"
  },
  "notification_type": "afs_black_list"
}'

응답

HTTP/1.1 204 No Content

정기결제 생성

게임유저가 정기결제를 한 경우, 이에 대한 알림 메시지를 결제알림 스크립트를 통해 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
subscription	object	정기결제 세부 정보(오브젝트).
subscription.plan_id	string	요금제 ID(API를 통해 생성된 경우, 외부 ID).
subscription.tags	array	플랜 태그.
subscription.subscription_id	integer	엑솔라 시스템 내의 정기결제 ID입니다.
subscription.product_id	string	상품 ID(액세스 토큰으로 보낸 경우)입니다.
subscription.date_create	string	정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
subscription.date_next_charge	string	다음 충전 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
subscription.trial	object	정기결제 평가 기간 데이터와 관련된 값입니다.
subscription.trial.value	integer	무료체험 기간 길이입니다.
subscription.trial.type	string	평가 기간 형식(day)입니다.
custom_parameters	object	사용자 지정 파라미터입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'create_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        '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' =>  array(
                'value' =>  90,
                'type' =>  'day'
            )
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "create_subscription",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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"
                }
        }
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof CreateSubscriptionMessage) {
       $messageArray = $message->toArray();
       // TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

업데이트된 정기결제

정기결제의 일부 매개 변수(plan_id, date_next_charge)가 변경된 경우 그리고 정기결제 갱신 시마다, 당사는 해당 webhook URL의 update_subscription 알림을 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
subscription	object	정기결제 세부 정보(오브젝트).
subscription.plan_id	string	요금제 ID(API를 통해 생성된 경우, 외부 ID).
subscription.tags	array	플랜 태그.
subscription.subscription_id	integer	엑솔라 시스템 내의 정기결제 ID입니다.
subscription.product_id	string	상품 ID(액세스 토큰으로 보낸 경우)입니다.
subscription.date_next_charge	string	다음 충전 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'update_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "update_subscription",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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"
        }
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
  if ($message instanceof UpdateSubscriptionMessage) {
     $messageArray = $message->toArray();
     // TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
  }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

취소된 정기결제

어떤 이유로 정기결제가 취소된 경우,이에 대한 알림 메시지를 결제알림 스크립트를 통해 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
subscription	object	정기결제 세부 정보(오브젝트).
subscription.plan_id	string	요금제 ID(API를 통해 생성된 경우, 외부 ID).
subscription.tags	array	플랜 태그.
subscription.subscription_id	integer	엑솔라 시스템 내의 정기결제 ID입니다.
subscription.product_id	string	상품 ID(액세스 토큰으로 보낸 경우)입니다.
subscription.date_create	string	정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
subscription.date_end	string	정기결제 종료 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        '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',
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "cancel_subscription",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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"
        }
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof CancelSubscriptionMessage) {
       $messageArray = $message->toArray();
       // TODO if the subscription canceling fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

비갱신 정기결제

어떠한 이유로 정기 결제가 비갱신으로 설정되는 경우, 다음 정기 결제 알림 non_renewal_subscription을 여러분의 웹훅 URL로 송부합니다.

파라미터	유형	설명
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	게임의 엑솔라 ID. 게시자 계정에서 찾을 수 있습니다. 필수.
settings.merchant_id	integer	판매자 ID입니다.
notification_type	string	알림 유형. 필수.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.email	string	사용자 이메일.
subscription	object	정기결제 세부 정보(오브젝트).
subscription.subscription_id	integer	엑솔라 시스템 내의 정기결제 ID입니다.
subscription.plan_id	string	요금제 ID(API를 통해 생성된 경우, 외부 ID).
subscription.date_create	string	정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
subscription.date_next_charge	string	다음 청구일. 정기 결제가 비갱신으로 설정되기 전 다음 지불 예정일입니다. 날짜 및 시간 당 ISO 8601.
subscription.currency	string	정기결제 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
subscription.amount	float	구매 금액입니다.

게임 키 가져오기

게임유저가 각 구매를 성공적으로 마친 후에 게임 활성화 코드를 얻기 위해 귀사의 서버로 API 호출을 진행합니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
pin_code	object	게임 키에 대한 데이터가 포함된 값입니다.
pin_code.digital_content	string	게임의 SKU입니다.
pin_code.DRM	string	DRM 사용이 가능한 게임입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array (
       'notification_type' => 'get_pincode',
       'settings' => array(
          'project_id' => 18404,
          'merchant_id' => 2340
       ),
       'user' =>
           array (
               'id' => '1234567',
               'name' => 'Xsolla User',
           ),
       'pin_code' =>
           array (
               'digital_content' => 'Game SKU',
               'DRM' => 'Steam',
           ),
   );

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "get_pincode",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "id": "1234567",
        "name": "Xsolla User"
    },
    "pin_code": {
        "digital_content": "Game SKU",
        "DRM": "Steam"
    }
}

$ 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": "get_pincode",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "pin_code": {
            "digital_content": "Game SKU",
            "DRM": "Steam"
        }
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof GetPinCodeMessage) {
        $userArray = $message->getUser();
        $drmSku = $message->getDRM();
        $digitalContentSku = $message->getDigitalContent();
        // TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
        $newPinCode = 'NEW_PIN_CODE';
        // TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
        return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 200 OK
Content-Type: application/json
{
    "pin_code": "PIN_CODE"
}

키 활성화

사용자가 키를 활성화하면 엑솔라는 알림 메시지를 웹훅 URL로 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
key	string	활성화 키.
sku	string	고유 키 패키지 ID.
user_id	string	사용자 ID.
activation_date	datetime	ISO 8601에 따라 키 활성화 날짜는 YYYYMMDDHHMMSS형식입니다.
user_country	string	사용자 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 대문자 국가 코드를 사용합니다.
restriction	object	지역 제한 클러스터 설정이 있는 오브젝트. 클러스터는 제한 유형과 게임을 이용할 수 있는 국가, 서버, 로캘 목록을 포함합니다.
restriction.sku	string	고유 클러스터 ID.
restriction.name	string	클러스터 이름.
restriction.types	array	제한 유형 배열.
restriction.countries	array	클러스터의 국개 바열.
restriction.servers	array	게임 서버 배열.
restriction.locales	array	로캘 배열.

Copy

Full screen

Small screen

php

요청

<?php
$request = array(
    'notification_type' => 'redeem_key',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'key' => ‘wqdqwwddq9099022’,
    'sku' => 123,
    'user_id' => ‘sample_user’,
    'activation_date' => ‘2018-11-20T08:38:51+03:00’,
    'user_country' => ‘EN’,
    'restriction' =>
           array(
                'name' => ‘cls_1’,
                'types' =>
                        array(
                            ‘activation’
                        ),
                'countries' =>
                        array(
                            ‘RU’
                        ),
             ),
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{
  "notification_type": "redeem_key",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
        ]
  }
}

$ 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": "redeem_key",
  "settings": {
        "project_id": 18404,
        "merchant_id": 2340
  },
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
         ]
    }
}'

응답

<?php

$response = null;

HTTP/1.1 204 No Content

친구 가져오기

파트너 측에서 API를 실행해야 합니다. 최대 친구 수는 2000. 명입니다. 레시피를 참조하십시오.

HTTP 요청

Copy

Full screen

Small screen

GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1

파라미터	유형	설명
notification_type	string	친구 목록을 가져오는 요청 유형을 정의하는 ID입니다.값은 `friends_list`입니다'.
user	string	기프트를 구입하는 사용자의 고유 ID.
query	string	친구의 이름 또는 ID(전체 또는 일부).
limit	string	페이지 요소 개수 제한. 필수.
offset	integer	목록이 생성된 요소 개수(개수는 0부터 시작함).
sign	string	서명 라인 생성: 연결 notification_type + 키에 의해 알파벳순으로 정렬된 매개변수 값 + secret_key 결과 스트링에 A-1을 적용

Copy

Full screen

Small screen

http

요청

GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
-X GET \
-u merchant_id:merchant_api_key

응답

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "friends": [
      {
        "id": "1",
        "name": "doctor",
        "email": "doctor@hospital.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "cook",
        "email": "cook@kitchen.com",
        "image_url": "https://partner/link/cook.jpg"
      },
      {
        "id": "3",
        "name": "teacher",
        "email": "teacher@school.com"
      },
      {
        "id": "4",
        "name": "god",
        "email": "god@heaven.com",
        "image_url": "https://partner/link/god.jpg"
      }
      ],
    "total": 10
  }
]

[
  {
  "friends": [
      {
        "id": "1",
        "name": "John Carter",
        "email": "carter@xsolla.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "John Smith",
        "email": "smith@xsolla.com",
        "image_url": "https://partner/link/cook.jpg"
      }
    ],
  "total": 10
  }
]

게임유저 잔액: 결제

게임유저가 결제를 진행한 경우,게임유저 잔액 변화에 관한 특별알림 메시지를 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
operation_type	string	작업 유형입니다.
id_operation	integer	엑솔라 시스템 내 작업 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.email	string	사용자 이메일.
virtual_currency_balance	object	시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
virtual_currency_balance.old_value	string	현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
virtual_currency_balance.new_value	string	현재 작업이 처리된 후 게임유저의 새잔액입니다.
virtual_currency_balance.diff	string	구매에 사용된 게임 머니 금액입니다.
transaction	object	트랜잭션 데이터 관련 값입니다. 필수.
transaction.id	integer	트랜잭션 ID.
transaction.date	string	트랜잭션 날짜입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '200',
        'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'transaction' => array(
        'id' => '123456789',
        'date' => '2015-05-19T15:54:40+03:00'
    ),
    'operation_type' => 'payment',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '66989'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "200",
        "diff": "200"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "transaction": {
        "id": "123456789",
        "date": "2015-05-19T15:54:40+03:00"
    },
    "operation_type": "payment",
    "notification_type": "user_balance_operation",
    "id_operation": "66989"
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "200",
            "diff": "200"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "transaction": {
            "id": "123456789",
            "date": "2015-05-19T15:54:40+03:00"
        },
        "operation_type": "payment",
        "notification_type": "user_balance_operation",
        "id_operation": "66989"
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

게임유저 잔액: 구매

게임유저가 게임 내에서 구매한 경우(예: 게임 아이템 구입) 게임유저 잔액 변화에 관한 특별 알림 메시지를 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
operation_type	string	작업 유형입니다.
id_operation	integer	엑솔라 시스템 내 작업 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.email	string	사용자 이메일.
virtual_currency_balance	object	시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
virtual_currency_balance.old_value	string	현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
virtual_currency_balance.new_value	string	현재 작업이 처리된 후 게임유저의 새잔액입니다.
virtual_currency_balance.diff	string	구매에 사용된 게임 머니 금액입니다.
items_operation_type	string	인게임 구매의 작업 유형입니다.
items	array	인게임 구매 아이템 데이터와 관련된 배열입니다.
items.sku	string	아이템 ID입니다.
items.amount	integer	아이템 수량입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "200",
        "diff": "200"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "operation_type": "inGamePurchase",
    "notification_type": "user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation": "66989"
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "200",
            "diff": "200"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "inGamePurchase",
        "notification_type": "user_balance_operation",
        "items_operation_type": "add",
             "items": [{
             "sku": "1468",
             "amount": "2"
             }],
        "id_operation": "66989"
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

게임유저 잔액: 쿠폰 사용

게임유저가 쿠폰을 사용하여 아이템이나 게임머니를 구매할 경우, 이에 관한 특별 알림 메시지를 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
operation_type	string	작업 유형입니다.
id_operation	integer	엑솔라 시스템 내 작업 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.email	string	사용자 이메일.
virtual_currency_balance	object	시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
virtual_currency_balance.old_value	string	현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
virtual_currency_balance.new_value	string	현재 작업이 처리된 후 게임유저의 새잔액입니다.
virtual_currency_balance.diff	string	구매에 사용된 게임 머니 금액입니다.
items_operation_type	string	인게임 구매의 작업 유형입니다.
items	array	인게임 구매 아이템 데이터와 관련된 배열입니다.
items.sku	string	아이템 ID입니다.
items.amount	integer	아이템 수량입니다.
coupon	object	쿠폰 데이터 관련 값입니다.
coupon.coupon_code	string	쿠폰 코드.
coupon.campaign_code	string	쿠폰 캠페인 코드입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '0',
        'diff' => '0'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'coupon',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989',
    'coupon' =>  array(
         'coupon_code' =>  'test123',
         'campaign_code' =>  'Xsolla Campaign'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "0",
        "diff": "0"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "operation_type": "coupon",
    "notification_type": "user_balance_operation",
    "items_operation_type": "add",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation": "66989",
    "coupon": {
         "coupon_code": "test123",
         "campaign_code": "Xsolla Campaign"
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "0",
            "diff": "0"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "coupon",
        "notification_type": "user_balance_operation",
        "items_operation_type": "add",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation": "66989",
        "coupon": {
             "coupon_code": "test123",
             "campaign_code": "Xsolla Campaign"
        }
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

게임유저 잔액: 수동 업데이트

게임유저 잔액을 직접 변경할 필요가 있을 경우.

파라미터	유형	설명
notification_type	string	알림 유형입니다.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
operation_type	string	작업 유형입니다.
id_operation	integer	엑솔라 시스템 내 작업 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.email	string	사용자 이메일.
virtual_currency_balance	object	시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
virtual_currency_balance.old_value	string	현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
virtual_currency_balance.new_value	string	현재 작업이 처리된 후 게임유저의 새잔액입니다.
virtual_currency_balance.diff	string	구매에 사용된 게임 머니 금액입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '100',
        'diff' => '100'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'internal',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '67002'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "100",
        "diff": "100"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "operation_type": "internal",
    "notification_type": "user_balance_operation",
    "id_operation": "67002"
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "100",
            "diff": "100"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "internal",
        "notification_type": "user_balance_operation",
        "id_operation": "67002"
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

게임유저 잔액: 환불

게임유저가 결제를 취소한 경우,게임유저 잔액 변화에 관한 특별 알림 메시지를 보냅니다.

파라미터	유형	설명
notification_type	string	알림 유형입니다.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
operation_type	string	작업 유형입니다.
id_operation	integer	엑솔라 시스템 내 작업 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.email	string	사용자 이메일.
virtual_currency_balance	object	시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
virtual_currency_balance.old_value	string	현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
virtual_currency_balance.new_value	string	현재 작업이 처리된 후 게임유저의 새잔액입니다.
virtual_currency_balance.diff	string	구매에 사용된 게임 머니 금액입니다.
transaction	object	트랜잭션 데이터 관련 값입니다. 필수.
transaction.id	integer	트랜잭션 ID.
transaction.date	string	트랜잭션 날짜입니다.
items_operation_type	string	인게임 구매의 작업 유형입니다.
items	array	인게임 구매 아이템 데이터와 관련된 배열입니다.
items.sku	string	아이템 ID입니다.
items.amount	integer	아이템 수량입니다.

Copy

Full screen

Small screen

php

요청

<?php

$request = array(
     'settings' => array(
         'project_id' => 18404,
         'merchant_id' => 2340
     ),
     'virtual_currency_balance' => array(
         'old_value' => '0',
         'new_value' => '0',
         'diff' => '0'
     ),
     'user' => array(
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
     ),
     'transaction' => array(
         'id' => '123456789',
         'date' => '2015-05-19T15:54:40+03:00'
     ),
     'operation_type' => 'cancellation',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'remove',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
     'id_operation' => '66989'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "0",
        "diff": "0"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "transaction": {
        "id": "123456789",
        "date": "2015-05-19T15:54:40+03:00"
    },
    "operation_type": "cancellation",
    "notification_type": "user_balance_operation",
    "items_operation_type": "remove",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation": "66989"
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "0",
            "diff": "0"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "transaction": {
            "id": "123456789",
            "date": "2015-05-19T15:54:40+03:00"
        },
        "operation_type": "cancellation",
        "notification_type": "user_balance_operation",
        "items_operation_type": "remove",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation": "66989"
    }'

응답

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

결제 계정 추가

사용자가 결제 계정을 수동으로 추가하거나 게임 내에서 무언가를 구매하면서 결제 계정을 저장할 때 전송됩니다. 이 알림을 사용하려면, 계정 관리자에게 문의하십시오.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.ip	string	유저 IP 주소입니다.
user.email	string	사용자 이메일.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
user.country	string	사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
user.zip	string	우편번호.
payment_account	object	결제 계정 세부내역 (객체).
payment_account.id	string	결제 계정 ID. 필수.
payment_account.name	string	결제 시스템의 결제 계정 명칭(예: 결제 카드 번호, 이메일).
payment_account.payment_method	integer	결제 수단의 ID입니다.
payment_account.type	string	결제 계정 유형(예: 카드, PayPal).

Copy

Full screen

Small screen

http

요청

POST /your/uri HTTP/1.1
Host:           your.hostname
Accept:         application/json
Content-Length: 255
Content-Type:   application/json
Authorization:  Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843

{
    "notification_type": "payment_account_add",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type":"payment_account_add",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'

응답

HTTP/1.1 204 No Content

결제 계정 제거

사용자가 저장된 계정에서 결제 계정 제거 시 전송됨. 본 알림을 사용하려면, 계정 관리자에게 문의하세요.

파라미터	유형	설명
notification_type	string	알림 유형입니다. 필수.
settings	object	사용자 지정 프로젝트 설정와 관련된 객체입니다.
settings.project_id	integer	엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다.
settings.merchant_id	integer	판매자 ID입니다.
user	object	사용자에 대한 데이터가 포함된 개체입니다.
user.email	string	사용자 이메일.
user.id	string	사용자 ID. 필수.
user.name	string	사용자 이름.
payment_account	object	결제 계정 세부내역 (객체).
payment_account.id	string	결제 계정 ID. 필수.
payment_account.name	string	결제 시스템의 결제 계정 명칭(예: 결제 카드 번호, 이메일).
payment_account.payment_method	integer	결제 수단의 ID입니다.
payment_account.type	string	결제 계정 유형(예: 카드, PayPal)

Copy

Full screen

Small screen

http

요청

POST /your/uri HTTP/1.1
Host:           your.hostname
Accept:         application/json
Content-Length: 258
Content-Type:   application/json
Authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


{
    "notification_type": "payment_account_remove",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "payment_account_remove",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'

응답

HTTP/1.1 204 No Content

웹훅 오류

영구적 오류 코드:

코드	메시지
INVALID_USER	잘못된 게임유저입니다.
INVALID_PARAMETER	잘못된 파라미터입니다.
INVALID_SIGNATURE	잘못된 서명입니다.
INCORRECT_AMOUNT	잘못된 금액입니다.
INCORRECT_INVOICE	잘못된 인보이스입니다.

Copy

Full screen

Small screen

HTTP/1.1 400 Bad Request

{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

의견을 보내 주셔서 감사드립니다!

메시지를 검토한 후 사용자 경험 향상에 사용하겠습니다.

Your browser is not supported. Please try a different browser

시작하기

개요

요청및응답

API 변경사항

버전 관리

인증

Endpoint 형식

날짜 형식

페이징

오류 처리

웹훅

개요

서명 요청

응답

Webhook 목록

게임유저 유효성 검사

notification_type

settings

settings.project_id

settings.merchant_id

user

user.ip

user.phone

user.email

user.id

user.name

user.country

사용자 검색

notification_type

settings

settings.project_id

settings.merchant_id

user

user.public_id

user.id

결제

notification_type

settings

settings.project_id

settings.merchant_id

purchase

purchase.virtual_currency

purchase.virtual_currency.name

purchase.virtual_currency.sku

purchase.virtual_currency.quantity

purchase.virtual_currency.currency

purchase.virtual_currency.amount

purchase.checkout

purchase.checkout.currency

purchase.checkout.amount

purchase.subscription

purchase.subscription.plan_id

purchase.subscription.subscription_id

purchase.subscription.product_id

purchase.subscription.tags

purchase.subscription.date_create

purchase.subscription.date_next_charge

purchase.subscription.currency

purchase.subscription.amount

purchase.virtual_items

purchase.virtual_items.items

purchase.virtual_items.items.sku

purchase.virtual_items.items.amount

purchase.virtual_items.currency

purchase.virtual_items.amount

purchase.pin_codes

purchase.pin_codes.digital_content

purchase.pin_codes.drm

purchase.pin_codes.currency

purchase.pin_codes.amount

purchase.pin_codes.upgrade

purchase.pin_codes.upgrade.digital_content_from

purchase.pin_codes.upgrade.digital_content_from.digital_content

purchase.pin_codes.upgrade.digital_content_from.DRM

purchase.pin_codes.upgrade.digital_content_to

purchase.pin_codes.upgrade.digital_content_to.digital_content

purchase.pin_codes.upgrade.digital_content_to.DRM

purchase.pin_codes.upgrade.currency

purchase.pin_codes.upgrade.amount