Xsolla Documentation - はじめる

概要

エクソラAPIは以下のことを含む：

Pay Station API — 決済UIとトークン化メソッド。
Commerce API — ゲーム内ストアおよびBuy Buttonモジュールを操作するメソッド。
Subscription API — サブスクリプションのためのメソッド。
Publisher Account API — パブリッシャーアカウントのプロジェクトとユーザー、レポート、サポートチケットを操作するメソッド。
Login API — 独自のインターフェースを使用したユーザー認証のためのメソッド（統合ガイドを参照してください）。

エクソラAPIはRESTに基づいて設計されています。APIには、予測可能なリソース指向のURLがあり、HTTPレスポンスコードを使用してAPIエラーを示します。APIは、エラーの場合を含め、常にJSON形式で応答します。

APIは、HTTP認証やHTTP動詞などの組み込みのHTTP機能を使用します。これは、既製のHTTPクライアントによって解釈できます。また、クロスオリジンリソースシェアリングをサポートしているため、クライアントWebアプリケーションから安全にアクセスできます。

エクソラAPIは次のエンドポイントのパスを使います：

https://api.xsolla.com-Pay Station API、Commerce API、Publisher Account API
https://login.xsolla.com/api-Login API

ほとんどのエンドポイントのパスには、merchant_idパラメーターが含まれています。これは、アプリケーションが出品者のために機能していることを示します。

リクエストとレスポンス

エクソラAPIのリクエストに必要なこと：

HTTPSで送信。
TLS 1.2以降を使用。
認証パラメータを含める。
追加ヘッダーContent-Type: application/jsonをPUTリクエストとPOSTリクエストに含める。

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パラメータを追加する。
HTTPリクエストヘッダを追加する。
有効なパラメータに無効な値が含まれているリクエストを拒否する。
解析ロジックが変更された場合、寛大な構文解析のために以前に受け入れられた不適切な形式のリクエストを拒否する。
文書化されていない機能をいつでも追加、変更、削除することができる。

変更に関係なく、クライアントは機能し続けます。たとえば、クライアントによって認識されない新しいJSONパラメータは、通常の操作を妨げてはいけません。

バージョン管理

すべてのエクソラAPIメソッドはバージョン管理をサポートしています。現在のバージョンと互換性のない変更があるたびに新しいバージョンを発行します。バージョンは、URLの"/merchant"接頭辞に続く"v1"や"v2"などの識別子によって識別されます。

初めてAPIを使用する場合は、最新のバージョンを使用してください。バージョンを省略すると、デフォルトで最初のバージョンが使用されます。

Info: エクソラでは、同じバージョン内でのみAPIの完全性を保証することができます。

認証

エクソラAPIは基本アクセス認証を採用しています。APIに対する全リクエストは、Authorization: Basic <your_authorization_basic_key>ヘッダーを含む必要があります。<your_authorization_basic_key>はmerchant_id:api_keyのペアで、Base64の基準に従ってエンコードしています。

エクソラのパブリッシャーアカウントを開いてパラメータ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);

エンドポイントの種類

エンドポイントのタイプは、どのような種類のデータを処理するのか、どのような処理を実行するのかを示します。最も一般的なアクションは次のとおりです。

アクション	HTTPメソッド	説明文
作成	`POST`	指定されたタイプのエンティティを作成して保存します。
リスト	`GET`	クエリに一致するエンティティのリストを返します。エンティティの詳細を取得するには、最初に対応するリストのエンドポイントを使用してそのIDを見つけ、このIDを対応する取得のエンドポイントに提供します。
取得	`GET`	指定されたIDを持つエンティティの詳細を提供します。
置換	`PUT`	指定されたIDを持つエンティティのすべてのフィールドを変更します。
更新	`PATCH`	指定されたIDを持つエンティティの指定されたフィールドを変更します。
削除	`DELETE`	指定されたIDを持つエンティティを削除します。

日付形式

すべての日付は、ISO 8601に従って文字配列として指定されます。日付文字配列は、UTC（例：2013-01-15T00:00:00Z）、またはUTCオフセット（例えばUTC+8の場合、2013-01-15T00:00:00-08:00）を指定できます。後者の場合は、夏時間を考慮してください。

ページネーション

リストのエンドポイントは、返された結果にページ区切りを付けることがあります。つまり、すべての結果を単一のレスポンスで返す代わりに、これらのエンドポイントは結果の一部と、次の結果セットにリンクするレスポンスヘッダを返す可能性があります。この目的のために、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レスポンスコードと完全に一致するわけではありません。たとえば、リクエストが有効であったにもかかわらず失敗した場合、APIは422エラーコードを返します。

すべてのAPIエラーレスポンスは、JSONオブジェクトに次のフィールドを提供します。

名前	種類	説明文
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"
}

ウェブフック

概要

ウェブフックを使用すると、エクソラトランザクションに発生したイベントの通知を受け取ることができます。ウェブフックを使用して、ステータスやその他のトランザクション関連情報の提供など、バックエンド機能や補足機能を自動化してください。

ウェブフックは次のような目的で使用します：

仮想通貨やアイテムの購入、銀行カード決済などの支払い
定期的な支払いとサブスクリプションアクション
取引関連のチャージバック/返金

ほとんどの場合、ウェブフックはウェブサイト上のユーザアクションによってトリガーされます。しかし、他のアクションによってトリガーされることもあります。たとえば、ウェブサイトのバックエンドプロセスによってAPIメソッドが呼び出されて決済が払い戻されたり、決済システムが請求額の訂正に関する通知を送信したりすることがあります。

ウェブフックを受信して処理するには、いわゆるリスナまたはハンドラを作成または使用する必要があります。これは、ウェブフックを待ち、通常は内部ワークフローに渡し、適切に応答するプログラムです。

たとえば、ウェブフック受信後に、次の操作を実行できます。

ユーザーの残高に入金、
ユーザーにアイテムを与える、
サブスクリプションのアクティブ化、
詐欺行為を行うユーザーをブロックするなど。

次のIPアドレスのウェブフックを使う：185.30.20.0/24、185.30.21.0/24、185.30.23.0/24。

Notice: データベースには、同じIDを持つ2つの成功したトランザクションを含めることはできません。視聴者が既存のトランザクションIDを持つウェブフックを受信した場合、そのトランザクションの最新の結果を返す必要があります。ユーザーに2回課金することまたはデータベースに重複したレコードを作成することを避けてください。

私たちが送信するすべてのウェブフックを視聴者が受け取ることを保証することはできません。インターネット接続は100％安定ではないため、ウェブフックが時間どおりに表示されない、または全然表示されない場合があります。さらに、視聴者はサーバーの一時的なエラーに対して5xx HTTPコードを返す場合があります。たとえば、ユーザーが正常に購入した仮想アイテムがユーザーの在庫に追加されなかった場合、視聴者は500HTTP応答コードを返します。

これらの問題に対処するために、視聴者がメッセージを受信するまで、失敗したメッセージを幾つかの間隔で再送信する再試行メカニズムを提供しています。繰り返されるウェブフックは前回より12時間以内に発送する場合がございます。再試行の最大数は12です。

Note: 接続の問題により、実際にウェブフックが失われたり、遅延したり、重複したりする可能性がありますが、よく見られる原因は、視聴者側のロジックの欠陥です。

署名リクエスト

デジタル署名は、安全なデータ伝送を可能にします。署名を生成するには、（1）リクエストのJSON本体をプロジェクトの秘密鍵と連結し、（2）結果の文字列に。

作成された署名が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"
      }
    }'

レスポンス

エクソラAPIは、成功したリクエストと失敗したリクエストのための従来のHTTPレスポンスコードを受け入れます。コード204は、処理が成功したことを示します。コード400を返します。サーバーでの一時的なエラーにはコード500を使用してください。

ウェブフック一覧

通知のタイプは、notification_typeparameterで送信されます。

通知タイプ	説明
user_validation	ユーザーがゲームに存在するかどうかを確認。
user_search	パブリックユーザーIDに基づいてユーザー情報を取得。
payment	ユーザーが決済を完了したときに送信。
refund	何らかの理由で決済をキャンセルする必要がある場合に送信。
afs_reject	AFSチェック中にトランザクションが拒否されると、エクソラはトランザクションの詳細をURLウェブフックに送信します。
afs_black_list	AFSブロックリストが更新されると送信する。
create_subscription	ユーザーがサブスクリプションを作成すると送信。
update_subscription	サブスクリプションが更新または変更されたときに送信。
cancel_subscription	サブスクリプションがキャンセルされたときに送信。
non_renewal_subscription	ステータスが非更新に設定されると送信されます。
get_pincode	エクソラAPIがゲームキーを取得する必要があるときに送信。
user_balance_operation	ユーザーの残高が変更されたときに送信（操作の種類はoperation_typeで送信されます）。
redeem_key	ユーザーがキーを有効にすると送信。
upgrade_refund	アップグレードがキャンセルされたときに送信します。
payment_account_add	ユーザーが決済アカウントを追加または保存すると送信されます。
payment_account_remove	ユーザーが保存済みアカウントから決済アカウントを削除すると送信されます。

ユーザーの確認

ユーザーがゲームに存在することを確認するために送信されます。

パラメータ	種類	説明文
notification_type	string	通知の種類。必須。
settings	object	カスタムプロジェクト設定（オブジェクト）。
settings.project_id	integer	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.ip	string	ユーザーIP。
user.phone	string	ユーザーの電話。
user.email	string	ユーザーのEメール。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.country	string	ユーザーの国。2文字の国コード（大文字）は、ISO 3166-1 alpha-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

ユーザーの検索

Public User IDを使用してユーザーの詳細を取得するために送信されます。これにより、ユーザはゲームストア外で（例えば、現金キオスクを介して）購入することができます。

パラメータ	種類	説明文
notification_type	string	通知の種類。必須。
settings	object	カスタムプロジェクト設定（オブジェクト）。
settings.project_id	integer	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。必須。
user.public_id	string	Public User 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"
    }
}

支払い

ユーザーが決済を完了したときに送信。支払いの詳細を含む。

ゲーム内ストアを統合した場合、order_paidウェブフックを介して支払いの詳細を受け取ることができます。

パラメータ	種類	説明文
notification_type	string	通知の種類。必須。
settings	object	カスタムプロジェクト設定（オブジェクト）。
settings.project_id	integer	ゲームのエクソラID。パブリッシャ―アカウントにあります。
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	購入通貨。ISO 4217に準拠した3文字の通貨コード。
purchase.virtual_currency.amount 非推奨	float	現金通貨での価格。
purchase.checkout	object	チェックアウトの詳細（オブジェクト）。
purchase.checkout.currency	string	購入通貨。ISO 4217に準拠した3文字の通貨コード。
purchase.checkout.amount	float	購入金額。
purchase.subscription	object	サブスクリプションの詳細（オブジェクト）。
purchase.subscription.plan_id	string	プランID（プランがAPIを使用して作成された場合は外部）。
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	サブスクリプションの通貨。ISO 4217に準拠した3文字の通貨コード。
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	購入通貨。ISO 4217に準拠した3文字の通貨コード。
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	ゲームキーを購入する通貨。ISO 42173文字通貨コード。
purchase.pin_codes.amount 非推奨	float	値段。
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	贈り主の情報を受取り側に公開するかどうか。
purchase.total	object	購入（オブジェクト）の合計価格。必須。
purchase.total.currency	string	購入通貨。ISO 4217に準拠した3文字の通貨コード。
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	ユーザーのEメール。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.country	string	ユーザーの国。2文字の国コード（大文字）は、ISO 3166-1 alpha-2に従って使用されます。
user.zip	string	Zipまたは郵便番号。
transaction	object	トランザクションの詳細（オブジェクト）。必須。
transaction.id	integer	トランザクションID。
transaction.external_id	string	トランザクション外部ID。
transaction.payment_date	string	支払日。
transaction.payment_method	integer	決済方法のID。
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	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payment.amount	string	金額。
payment_details.payment_method_sum	object	決済システムから振り込まれた金額。
payment_details.payment_method_sum.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payment_method_sum.amount	string	金額。
payment_details.xsolla_balance_sum	object	エクソラの残高から振り込まれた金額。
payment_details.xsolla_balance_sum.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.xsolla_balance_sum.amount	string	金額。
payment_details.payout	object	配当の詳細（オブジェクト）。
payment_details.payout.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payout.amount	float	金額。
payment_details.vat	object	VATの詳細（オブジェクト；EUのみ）。
payment_details.vat.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.vat.amount	float	金額。
payment_details.vat.percent	float	消費税率。
payment_details.payout_currency_rate	float	決済と配当間の為替レート。
payment_details.xsolla_fee	object	エクソラ料金（オブジェクト）。
payment_details.xsolla_fee.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.xsolla_fee.amount	float	金額。
payment_details.payment_method_fee	object	決済システム料金。
payment_details.payment_method_fee.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payment_method_fee.amount	float	金額。
payment_details.sales_tax	object	売上税（オブジェクト；米国とカナダのみ）。
payment_details.sales_tax.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.sales_tax.amount	float	金額。
payment_details.sales_tax.percent	float	売上税率。
payment_details.direct_wht	object	直接源泉徴収税。
payment_details.direct_wht.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.direct_wht.amount	float	金額。
payment_details.direct_wht.percent	float	直接源泉徴収税率。
payment_details.repatriation_commission	object	本国送金費用のデータ付きオブジェクト。サードパーティがエクソラに課します。
payment_details.repatriation_commission.currency	string	本国送金通貨。ISO 4217に準拠した3文字の通貨コードです。
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
            'percent' => 20
        ),
        'sales_tax' => array(
            'currency' => 'USD',
            'amount' => 0
            'percent' => 0
        ),
        'direct_wht' => array(
            'currency' => 'USD',
            'amount' => 0
            'percent' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        '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
            "percent": 20
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0
            "percent": 0
        },
        "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
            "percent": 20
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0
            "percent": 0
        },
        "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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
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	購入通貨。ISO 4217に準拠した3文字の通貨コード。
purchase.virtual_currency.amount 非推奨	float	現金通貨での価格。
purchase.checkout	object	チェックアウトの詳細（オブジェクト）。
purchase.checkout.currency	string	購入通貨。ISO 4217に準拠した3文字の通貨コード。
purchase.checkout.amount	float	購入金額。
purchase.subscription	object	サブスクリプションの詳細（オブジェクト）。
purchase.subscription.plan_id	string	プランID（プランがAPIを使用して作成された場合は外部）。
purchase.subscription.tags	array	プランのタグ。
purchase.subscription.subscription_id	integer	エクソラデータベースのサブスクリプションID。
purchase.subscription.date_create	string	サブスクリプション作成日。日付時刻表記は、ISO 8601形式。
purchase.subscription.currency	string	サブスクリプションの通貨。ISO 4217に準拠した3文字の通貨コード。
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	購入通貨。ISO 4217に準拠した3文字の通貨コード。
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	購入通貨。ISO 4217に準拠した3文字の通貨コード。
purchase.total.amount	float	支払額合計。
user	object	ユーザーの詳細（オブジェクト）。
user.ip	string	ユーザーIP。
user.phone	string	ユーザーの電話。
user.email	string	ユーザーのEメール。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.country	string	ユーザーの国。2文字の国コード（大文字）は、ISO 3166-1 alpha-2に従って使用されます。
user.zip	string	Zipまたは郵便番号。
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	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payment.amount	string	金額。
payment_details.payment_method_sum	object	決済システムから振り込まれた金額。
payment_details.payment_method_sum.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payment_method_sum.amount	string	金額。
payment_details.xsolla_balance_sum	object	エクソラの残高から振り込まれた金額。
payment_details.xsolla_balance_sum.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.xsolla_balance_sum.amount	string	金額。
payment_details.payout	object	配当の詳細（オブジェクト）。
payment_details.payout.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payout.amount	float	金額。
payment_details.vat	object	VATの詳細（オブジェクト；EUのみ）。
payment_details.vat.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.vat.amount	float	金額。
payment_details.vat.percent	float	消費税率。
payment_details.payout_currency_rate	float	決済と配当間の為替レート。
payment_details.xsolla_fee	object	エクソラ料金（オブジェクト）。
payment_details.xsolla_fee.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.xsolla_fee.amount	float	金額。
payment_details.payment_method_fee	object	決済システム料金。
payment_details.payment_method_fee.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.payment_method_fee.amount	float	金額。
payment_details.sales_tax	object	売上税（オブジェクト；米国とカナダのみ）。
payment_details.sales_tax.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.sales_tax.amount	float	金額。
payment_details.sales_tax.percent	float	消費税率。
payment_details.direct_wht	object	直接源泉徴収税。
payment_details.direct_wht.currency	string	通貨。ISO 4217に準拠した3文字の通貨コード。
payment_details.direct_wht.amount	float	金額。
payment_details.direct_wht.percent	float	直接源泉徴収税率。
payment_details.repatriation_commission	object	本国送金費用のデータ付きオブジェクト。サードパーティがエクソラに課します。
payment_details.repatriation_commission.currency	string	本国送金通貨。ISO 4217に準拠した3文字の通貨コードです。
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
            'percent' => 20
        ),
        'sales_tax' => array(
            'currency' => 'USD',
            'amount' => 0
            'percent' => 0
        ),
        'direct_wht' => array(
            'currency' => 'USD',
            'amount' => 0
            'percent' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        '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
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0
            "percent": 0
        },
        "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
                "percent": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0
                "percent": 0
            },
            "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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
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プラットフォーム。
ownership	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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.ip	string	ユーザーIP。
user.phone	string	ユーザーの電話。
user.email	string	ユーザーのEメール。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.country	string	ユーザーの国。2文字の国コード（大文字）は、ISO 3166-1 alpha-2に従って使用されます。
user.zip	string	Zipまたは郵便番号。
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_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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
subscription	object	サブスクリプションの詳細（オブジェクト）。
subscription.plan_id	string	プランID（プランがAPIを使用して作成された場合は外部）。
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）が変更された場合、およびサブスクリプションが更新されるたびに、ウェブフックURLでupdate_subscription通知が送信されます。

パラメータ	種類	説明文
notification_type	string	通知の種類。必須。
settings	object	カスタムプロジェクト設定（オブジェクト）。
settings.project_id	integer	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
subscription	object	サブスクリプションの詳細（オブジェクト）。
subscription.plan_id	string	プランID（プランがAPIを使用して作成された場合は外部）。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
subscription	object	サブスクリプションの詳細（オブジェクト）。
subscription.plan_id	string	プランID（プランがAPIを使用して作成された場合は外部）。
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	ユーザーのEメール。
subscription	object	サブスクリプションの詳細（オブジェクト）。
subscription.subscription_id	integer	エクソラデータベースのサブスクリプションID。
subscription.plan_id	string	プランID（プランがAPIを使用して作成された場合は外部）。
subscription.date_create	string	サブスクリプション作成日。日付時刻表記は、ISO 8601形式。
subscription.date_next_charge	string	次の請求日。これは、ユーザーのサブスクリプションが非更新に設定される前に次の支払いが予想される日付です。ISO 8601の日付と時刻。
subscription.currency	string	サブスクリプションの通貨。ISO 4217に準拠した3文字の通貨コード。
subscription.amount	float	現金通貨での価格。

ゲームキーの取得

決済が成功するたびに、ゲームのアクティベーションコードを取得するためにサーバーにAPI呼び出しが行われます。

パラメータ	種類	説明文
notification_type	string	通知の種類。
settings	object	カスタムプロジェクト設定（オブジェクト）。
settings.project_id	integer	ゲームのエクソラID。パブリッシャ―アカウントにあります。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
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に従って大文字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アルファベット順にソートしたパラメータ値を連結する。結果の文字列にSHA-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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
operation_type	string	操作の種類。
id_operation	integer	エクソラデータベースの操作ID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.email	string	ユーザーのEメール。
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	ゲームのエクソラ ID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
operation_type	string	操作の種類。
id_operation	integer	エクソラデータベースの操作ID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.email	string	ユーザーのEメール。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
operation_type	string	操作の種類。
id_operation	integer	エクソラデータベースの操作ID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.email	string	ユーザーのEメール。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
operation_type	string	操作の種類。
id_operation	integer	エクソラデータベースの操作ID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.email	string	ユーザーのEメール。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
operation_type	string	操作の種類。
id_operation	integer	エクソラデータベースの操作ID。
user	object	ユーザーの詳細（オブジェクト）。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.email	string	ユーザーのEメール。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.ip	string	ユーザーIP。
user.email	string	ユーザーのEメール。
user.id	string	ユーザーID。必須。
user.name	string	ユーザー名。
user.country	string	ユーザーの国。2文字の国コード（大文字）は、ISO 3166-1 alpha-2に従って使用されます。
user.zip	string	Zipまたは郵便番号。
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	ゲームのエクソラID。パブリッシャ―アカウントにあります。
settings.merchant_id	integer	マーチャントID。
user	object	ユーザーの詳細（オブジェクト）。
user.email	string	ユーザーのEメール。
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"
    }
}

ご意見ありがとうございました！

あなたのメッセージを確認し、体験を向上させるために利用させていただきます。

このページを評価する

答えたくない

ご意見ありがとうございました！

最終更新日: 2021年8月16日

誤字脱字などのテキストエラーを見つけましたか？テキストを選択し、Ctrl+Enterを押します。

Your browser is not supported. Please try a different browser

はじめる

概要

リクエストとレスポンス

APIの変更点

バージョン管理

認証

エンドポイントの種類

日付形式

ページネーション

エラー処理

ウェブフック

概要

署名リクエスト

レスポンス

ウェブフック一覧

ユーザーの確認

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