カタログAPI (2.0.0)
- Version: 2.0.0
- Servers:
https://store.xsolla.com/api - Contact Us by Email
- Contact URL: https://xsolla.com/
- Required TLS version: 1.2
The Catalog API allows you to configure a catalog of in-game items on the Xsolla side and display the catalog to users in your store.
The API allows you to manage the following catalog entities:
- Virtual items — in-game items such as weapons, skins, boosters.
- Virtual currency — virtual money used to purchase virtual goods.
- Virtual currency packages — predefined bundles of virtual currency.
- Bundles — combined packages of virtual items, currency, or game keys sold as a single SKU.
- Game keys — keys for games and DLCs distributed via platforms like Steam or other DRM providers.
- Groups — logical groupings for organizing and sorting items within the catalog.
The API is divided into the following groups:
Admin — calls for creating, updating, deleting, and configuring catalog items and groups. Authenticated via basic access authentication with your merchant or project credentials. Not intended for storefront use.Catalog — calls for retrieving items and building custom storefronts for end users. Designed to handle high-load scenarios. Support optional user JWT authorization to return personalized data such as user-specific limits and active promotions.
API calls require authentication either on behalf of a user or on behalf of a project. The authentication scheme used is specified in the Security section in the description of each call.
User's JWT authentication is used when a request is sent from a browser, mobile application, or game. By default, the XsollaLoginUserJWT scheme is applied. For details on how to create a token, see the Xsolla Login API documentation.
The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data.
別の方法として、決済UIを開くためのトークンを使用することも可能です。
Basic HTTP authentication is used for server-to-server interactions, when an API call is sent directly from your server rather than from a user's browser or mobile application. HTTP Basic authentication with an API key is typically used.
The API key is confidential and must not be stored or used in client applications.
With basic server-side authentication, all API requests must include the following header:
- for
basicAuth—Authorization: Basic <your_authorization_basic_key>, whereyour_authorization_basic_keyis theproject_id:api_keypair encoded in Base64 - for
basicMerchantAuth—Authorization: Basic <your_authorization_basic_key>, whereyour_authorization_basic_keyis themerchant_id:api_keypair encoded in Base64
You can find the parameter values in Publisher Account:
merchant_idis displayed:- In Company settings > Company.
- In the URL in the browser address bar on any Publisher Account page. The URL has the following format:
https://publisher.xsolla.com/<merchant_id>.
project_idis displayed:- Next to the project name in Publisher Account.
- In the URL in the browser address bar when working on a project in Publisher Account. The URL has the following format:
https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
api_keyis shown in Publisher Account only at the time of creation and must be stored securely on your side. You can create an API key in the following sections:
If a required API call doesn't include the
project_id path parameter, use an API key that is valid across all company projects for authorization.For more information about working with API keys, see the API references.
AuthForCart認証スキームはカートでの購入用であり、以下の2つのモードに対応しています：
Authentication with a user's JWT. The token is passed in the
Authorizationheader in the following format:Authorization: Bearer <user_JWT>, where<user_JWT>is the user token. The token identifies the user and provides access to personalized data. Alternatively, you can use a token for opening the payment UI.Simplified mode without Authorization header. This mode is used only for unauthorized users and can be applied only for game key sales. Instead of a token, the request must include the following headers:
x-unauthorized-idwith a request IDx-userwith the user's email address encoded in Base64
Items of all types (virtual items, bundles, virtual currency, and keys) use a similar data structure. Understanding the basic structure simplifies working with the API and helps you navigate the documentation more easily.
Some calls may include additional fields but they don't change the basic structure.
Identification
merchant_id— company ID in Publisher Accountproject_id— project ID in Publisher Accountsku— item SKU, unique within the project
Store display
name— item namedescription— item descriptionimage_url— image URLis_enabled— item availabilityis_show_in_store— whether the item is displayed in the catalog
For more information about managing item availability in the catalog, see the documentation.
Organization
type— item type, for example, a virtual item (virtual_item) or bundle (bundle)groups— groups the item belongs toorder— display order in the catalog
Sale conditions
prices— prices in real or virtual currencylimits— purchase limitsperiods— availability periodsregions— regional restrictions
Example of core entity structure:
{
"attributes": [],
"bundle_type": "virtual_currency_package",
"content": [
{
"description": {
"en": "Main in-game currency"
},
"image_url": "https://.../image.png",
"name": {
"en": "Crystals",
"de": "Kristalle"
},
"quantity": 500,
"sku": "com.xsolla.crystal_2",
"type": "virtual_currency"
}
],
"description": {
"en": "Crystals x500"
},
"groups": [],
"image_url": "https://.../image.png",
"is_enabled": true,
"is_free": false,
"is_show_in_store": true,
"limits": {
"per_item": null,
"per_user": null,
"recurrent_schedule": null
},
"long_description": null,
"media_list": [],
"name": {
"en": "Medium crystal pack"
},
"order": 1,
"periods": [
{
"date_from": null,
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"prices": [
{
"amount": 20,
"country_iso": "US",
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"regions": [],
"sku": "com.xsolla.crystal_pack_2",
"type": "bundle",
"vc_prices": []
}The Xsolla API allows you to implement in-game store logic, including retrieving the item catalog, managing the cart, creating orders, and tracking their status. Depending on the integration scenario, API calls are divided into Admin and Catalog subsections, which use different authentication schemes.
The following example shows a basic flow for setting up and operating a store, from item creation to purchase.
Create an item catalog for your store, such as virtual items, bundles, or virtual currency.
Example API calls:
Configure user acquisition and monetization tools, such as discounts, bonuses, daily rewards, or offer chains.
Example API calls:
Configure item display in your application.
Do not use API calls from the Admin subsection to build a user catalog. These API calls have rate limits and aren't intended for user traffic.
Example API calls:
By default, catalog API calls return items that are currently available in the store at the time of the request. To retrieve items that are not yet available or are no longer available, include the parameter
"show_inactive_time_limited_items": 1 in the catalog request.
You can sell items using the following methods:
- Fast purchase — sell one SKU multiple times.
- Cart purchase — the user adds items to the cart, removes items, and updates quantities within a single order.
If an item is purchased using virtual currency instead of real money, use the Create order with specified item purchased by virtual currency API call. The payment UI is not required, as the charge is processed when the API call is executed.
For free item purchase, use the Create order with specified free item API call or the Create order with free cart API call. The payment UI is not required — the order is immediately set to the done status.
Use the client-side API call to create an order with a specified item. The call returns a token used to open the payment UI.
Discount information is available to the user only in the payment UI. Promo codes are not supported.
Cart setup and purchase can be performed on the client or on the server side.
Set up and purchase a cart on the client
Implement the logic of adding and removing items by yourself. Before calling the API for setting up a cart, you will not have information about which promotions will be applied to the purchase. This means that the total cost and details of the added bonus items will not be known.
Implement the following cart logic:
- After the player has filled a cart, use the Fill cart with items API call. The call returns the current information about the selected items (prices before and after discounts, bonus items).
- Update the cart contents based on user actions:
- To add an item or change item quantity, use the Update cart item by cart ID API call.
- To remove an item, use the Delete cart item by cart ID API call.
To get the current status of the cart, use the Get current user's cart API call.
- Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to
newstatus by default.
Set up and purchase a cart on the server
This setup option may take longer for setting the cart up, since each change to the cart must be accompanied by API calls.
Implement the following cart logic:
- After the player has filled a cart, use the Fill cart with items API call. The call returns current information about the selected items (prices before and after discounts, bonus items).
- Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to
newstatus by default.
Use the returned token to open the payment UI in a new window. Other ways to open the payment UI are described in the documentation.
| Action | Endpoint |
|---|---|
| Open in production environment. | https://secure.xsolla.com/paystation4/?token={token} |
| Open in sandbox mode. | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
Use sandbox mode during development and testing. Test purchases don't charge real accounts. You can use test bank cards.
After the first real payment is made, a strict sandbox payment policy takes effect. A payment in sandbox mode is available only to users specified in Publisher Account > Company settings > Users.
Buying virtual currency and items for real currency is possible only after signing a license agreement with Xsolla. To do this, in Publisher Account, go to Agreements & Taxes > Agreements, complete the agreement form, and wait for confirmation. It may take up to 3 business days to review the agreement.
To enable or disable sandbox mode, change the value of the sandbox parameter in the request for fast purchase and cart purchase. Sandbox mode is off by default.
Possible order statuses:
new— order createdpaid— payment receiveddone— item deliveredcanceled— order canceledexpired— order expired
Track order status using one of the following methods:
API calls that return large sets of records (for example, when building a catalog) return data in pages. Pagination is a mechanism that limits the number of items returned in a single API response and allows you to retrieve subsequent pages sequentially.
Use the following parameters to control the number of returned items:
limit— number of items per pageoffset— index of the first item on the page (numbering starts from 0)has_more— indicates whether another page is availabletotal_items_count— total number of items
Example request:
GET /items?limit=20&offset=40Response example:
{
"items": [...],
"has_more": true,
"total_items_count": 135
}It is recommended to send subsequent requests until the response returns has_more = false.
Dates and time values are passed in the ISO 8601 format.
The following are supported:
- UTC offset
nullvalue when there is no time restriction for displaying an item- Unix timestamp (in seconds) used in some fields
Format: YYYY-MM-DDTHH:MM:SS±HH:MM
Example: 2026-03-16T10:00:00+03:00
Xsolla supports localization of user-facing fields such as item name and description. Localized values are passed as an object where the language code is used as the key. The full list of supported languages is available in the documentation.
Supported fields
Localization can be specified for the following parameters:
namedescriptionlong_description
Locale format
The locale key can be specified in one of the following formats:
- Two-letter language code:
en,ru - Five-letter language code:
en-US,ru-RU,de-DE
Examples
Example with a two-letter language code:
{
"name": {
"en": "Starter Pack",
"ru": "Стартовый набор"
}
}Example with a five-letter language code:
{
"description": {
"en-US": "Premium bundle",
"de-DE": "Premium-Paket"
}
}The user's country determines catalog prices, the payment currency, and available payment methods in the payment UI. Depending on the API call, the country is determined as follows:
- In client-side API calls, the country is determined by the IP address of the request.
- In server-side API calls,
the country is determined by the value of the
user.country.valueparameter or by the user's IP address from theX-User-Ipheader. If both are passed, theuser.country.valueparameter takes precedence.
If an error occurs, the API returns an HTTP status and a JSON response body. The full list of store-related errors is available in the documentation.
Response example:
{
"errorCode": 1102,
"errorMessage": "Validation error",
"statusCode": 422,
"transactionId": "c9e1a..."
}errorCode— error code.errorMessage— short error description.statusCode— HTTP response status.transactionId— request ID. Returned only in some cases.errorMessageExtended— additional error details, such as request parameters. Returned only in some cases.
Extended response example:
{
"errorCode": 7001,
"errorMessage": "Chain not found",
"errorMessageExtended": {
"chain_id": "test_chain_id",
"project_id": "test_project_id",
"step_number": 2
},
"statusCode": 404
}Common HTTP status codes
400— invalid request401— authentication error403— insufficient permissions404— resource not found422— validation error429— rate limit exceeded
Recommendations
- Handle the HTTP status and the response body together.
- Use
errorCodeto process errors related to application logic. - Use
transactionIdto identify requests more quickly when analyzing errors.
概要
仮想アイテムと仮想通貨を使用してインゲームストアを構築し、ユーザーへの表示方法を設定できます。以下のアイテムタイプが利用可能です：
- 仮想アイテム — 武器、スキン、ブースターなどのゲーム内アイテム。実際のお金または仮想通貨で販売できます。
- 仮想通貨 — 仮想アイテムの購入に使用されるゲーム内通貨。実際のお金または仮想通貨で販売できます。
- 仮想通貨パッケージ — 仮想通貨の固定数量パック。実際のお金または仮想通貨で販売できます。
グループは、カタログ内のアイテムを整理するために使用されます。アイテムを論理的にグループ化し、表示方法を管理することができます。
管理者サブセクションのAPIコールを使用して、アイテムの作成、更新、削除を行います。
カタログサブセクションのAPIコールを使用して、アイテムのリストを取得し、ユーザーに表示します。
管理者サブセクションのAPIコールを使用してストアカタログを構築しないでください。
仮想アイテムリストを取得するAPIコールは、価格や属性を含む詳細なアイテムデータを返し、ページネーションをサポートします。ストアフロントでカタログページを表示するために使用してください。
すべての仮想アイテムリストを取得するAPIコールは、ページネーションなしでアイテムSKU、名前、説明、グループIDと名前を返します。クライアント側の検索やインデックス作成に使用してください。
仮想通貨で購入する場合、仮想通貨で購入された指定アイテムで注文を作成するAPIコールを使用してください。当該APIコールの実行時に課金処理が行われるため、決済UIを表示する必要はありません。
仮想通貨での購入フローの例：
プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}
- Mock serverhttps://xsolla.redocly.app/_mock/ja/api/catalog/v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_items/sku/booster_mega_1プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/virtual_currency
- Mock serverhttps://xsolla.redocly.app/_mock/ja/api/catalog/v2/project/{project_id}/admin/items/virtual_currency
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_currency?limit=50&offset=0'仮想通貨のリストは正常に受信されました。
一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。
アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
2文字の小文字の言語コード。
アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
2文字の小文字の言語コード。
アイテムの長文説明のローカライズを含むオブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のバリアント（例：enとen-US）が提供された場合、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
2文字の小文字の言語コード。
アイテムが所属するグループ。
属性リスト。
一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。
属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。
属性の一意の値ID。external_idには、半角小文字の英数字、ハイフン、アンダースコアのみを含めることができます。
スクリーンショット、ゲームプレイ動画などのアイテム追加アセット。
商品価格の通貨。3文字のコードISO4217 規格詳細については、ドキュメントを参照してください。エクソーラでサポートされている通貨。
この価格がカタログでの表示およびアイテムの購入に使用されるかどうか。falseの場合、この価格は使用されず、別の価格が適用されます。価格設定に関する詳細な情報は、当社のドキュメントを参照してください。
画像URL。決済UI上で画像を正しく表示し、高速に読み込ませるために、当社の画像およびURLガイドラインを確認ください：
- サポートされているフォーマット：WebP（推奨）、PNG、JPG
- ファイルサイズ：50 KB以下（WebPの場合）または150 KB以下（PNGおよびJPGの場合）
- 画像サイズ：280 × 280 px
- カラースペース：sRGB
- プロトコル：バージョン管理されたURLに対する、長期キャッシュを伴うHTTPS
アイテムが利用可能かどうか。falseの場合、そのアイテムをストアで購入することや、バンドルの一部、またはマーケティングキャンペーン内で取得することはできません。アイテムの可用性に関する詳細な情報は、当社のドキュメントを参照してください。
カタログにおけるアイテムの表示順。この値が大きいほど、アイテムはリストの下位に配置されます。 値が同じ場合は作成日時順でソートされ、新しいアイテムほど上方に表示されます。
アイテムをカタログに表示するかどうか。falseかつis_enabled: true の場合、そのアイテムはカタログ上には表示されませんが、バンドルの一部やマーケティングキャンペーン内での取得は可能です。アイテムの可用性に関する詳細な情報は、当社のドキュメントを参照してください。
アイテムが利用可能な地域の配列。配列が空であるか、または渡されなかった場合、そのアイテムはすべての地域で利用可能です。
プロジェクト内のプ地域ID。
詳細な情報については、地域の販売制限に関するドキュメントおよび地域管理用のAPIコールを参照してください。
アイテム制限。
別ユーザーのアイテム制限。
購入制限に達してから次回の制限リセットまでの間、カタログ内でのアイテムの表示・非表示を決定します。
これは、recurrent_schedule配列で定期的な制限リセットが設定されているアイテムに適用されます。
購入制限のリセットが設定されていない場合、購入制限に達した後は、limit_exceeded_visibilityの値に関わらず、そのアイテムはカタログに表示されなくなります。
指定可能な値：
show— 購入制限に達した後も、カタログ取得用のAPIコールに対してアイテム情報が返却されます。クライアントサイドのカタログ取得APIコールにおいては、制限に達した時点でアイテムにcan_be_bought: falseフラグが付与されて返されます。次回のリセット日時はreset_next_dateに格納されて返却されます。hide— 購入制限に達した時点から、制限値がリセットされるまでの間、カタログ取得用のAPIコールにおいてアイテムは返されなくなります。
グローバルアイテム制限。
制限更新期間。
ユーザー制限更新期間。
ユーザー制限の日次更新タイプ。
希望するタイムゾーンでのリミットの更新時刻（時間単位への四捨五入）。
制限が更新された日時（UNIXタイムスタンプ）。
最初の制限更新の日時（ISO 8601）。
アイテム販売期間。
{ "items": [ { … }, { … } ] }
プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。
アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
2文字の小文字の言語コード。
アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
2文字の小文字の言語コード。
アイテムの長文説明のローカライズを含むオブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のバリアント（例：enとen-US）が提供された場合、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
2文字の小文字の言語コード。
画像URL。決済UI上で画像を正しく表示し、高速に読み込ませるために、当社の画像およびURLガイドラインを確認ください：
- サポートされているフォーマット：WebP（推奨）、PNG、JPG
- ファイルサイズ：50 KB以下（WebPの場合）または150 KB以下（PNGおよびJPGの場合）
- 画像サイズ：280 × 280 px
- カラースペース：sRGB
- プロトコル：バージョン管理されたURLに対する、長期キャッシュを伴うHTTPS
スクリーンショット、ゲームプレイ動画などのアイテム追加アセット。
アイテムが所属するグループの外部IDsのリスト。
例：["horror", "action"]
属性リスト。
一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。
属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。
商品価格の通貨。3文字のコードISO4217 規格詳細については、ドキュメントを参照してください。エクソーラでサポートされている通貨。
この価格がカタログでの表示およびアイテムの購入に使用されるかどうか。falseの場合、この価格は使用されず、別の価格が適用されます。価格設定に関する詳細な情報は、当社のドキュメントを参照してください。
仮想通貨価格の配列。
一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。
アイテムが利用可能かどうか。falseの場合、そのアイテムをストアで購入することや、バンドルの一部、またはマーケティングキャンペーン内で取得することはできません。アイテムの可用性に関する詳細な情報は、当社のドキュメントを参照してください。
アイテムをカタログに表示するかどうか。falseかつis_enabled: true の場合、そのアイテムはカタログ上には表示されませんが、バンドルの一部やマーケティングキャンペーン内での取得は可能です。アイテムの可用性に関する詳細な情報は、当社のドキュメントを参照してください。
アイテムが利用可能な地域の配列。配列が空であるか、または渡されなかった場合、そのアイテムはすべての地域で利用可能です。
アイテム制限。
制限更新期間。
購入制限のリセットは、指定された時間間隔で実行されます。
アイテム販売期間。
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/virtual_currency
- Mock serverhttps://xsolla.redocly.app/_mock/ja/api/catalog/v2/project/{project_id}/admin/items/virtual_currency
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_currency \
-H 'Content-Type: application/json' \
-d '{
"sku": "com.xsolla.coin_1",
"name": {
"en-US": "Gold coin",
"de-DE": "Goldmünze"
},
"is_enabled": true,
"is_free": false,
"is_paid_randomized_reward": false,
"groups": [
"gold"
],
"order": 1,
"description": {
"en-US": "The main currency of your kingdom",
"de-DE": "Die Hauptwährung deines Königreichs"
},
"prices": [
{
"amount": 100,
"currency": "USD",
"is_enabled": true,
"is_default": true
}
],
"attributes": [
{
"external_id": "material",
"name": {
"en-US": "Material"
},
"values": [
{
"external_id": "gold",
"value": {
"en-US": "Gold"
}
}
]
}
],
"limits": {
"per_user": 5,
"per_item": 10000
},
"periods": [
{
"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"custom_attributes": {
"purchased": 0,
"attr": "value"
}
}'{ "sku": "com.xsolla.item_1" }
概要
ゲームキーは、ユーザーがゲームプラットフォーム上でゲームやDLCにアクセスできるようにするための、使い切りのユニークな半角英数字コードです。ゲームキーは、ダイレクトリンク、ストアUI、またはウィジェットを介して販売することができます。また、特定の国でゲームキーを販売するために、地域別制限を設定することも可能です。詳細については、ゲームキーパッケージセクションを参照してください。
ゲームキーを販売する際、ユーザー認証は必須ではありません。キーは、ユーザーがチェックアウト時に指定したメールアドレス宛に送信されます。また、認証を設定することで、個人用設定、購入制限、エンタイトルメントシステムといった追加のシナリオを有効にすることも可能です。詳細については、ゲームキー販売時の認証設定方法セクションを参照してください。
ゲームキーの販売フロー：
- ゲームを作成するAPIコールを使用して、ゲームを作成します。
- 地域制限を設定します。
- コードをアップロードするAPIコールを使用してゲームキーパッケージにキーをアップロードし、購入可能な状態にします。
- ゲームリストを取得するAPIコールを使用して、ユーザーの地域に応じた価格とともにゲームカタログを表示します。
- 注文を作成します。素早く購入できるようにするには、ゲームキーのSKUを渡し、現在のカート内の全アイテムを含む注文を作成するAPIコールを使用できます。レスポンスとして、決済UIを開くためのトークンが返されます。
- 注文の支払いを行うために、決済UIを開く処理を実装します。
決済完了の通知をタイムリーに受け取り、ユーザーにアイテムを付与するには、たとえば、ウェブフックを使用して注文ステータスのトラッキングを設定してください。キーは、ユーザーがチェックアウト時に指定したメールアドレス宛に送信され、注文ステータスはdoneに移行します。
概要
バンドルとは、複数のアイテムを1つの単位としてセット販売するものです。バンドルには、仮想アイテム、仮想通貨、仮想通貨パッケージ、ゲームキー、および他のバンドルを含めることができます。バンドルを活用することで、スターターパック、季節限定オファー、特別セールなどを作成できます。
バンドルを操作するには、以下のAPIコールグループを使用します：
- バンドルの作成、更新、削除、およびそれらの公開状態を管理するには、管理者サブセクションのAPIコールを使用します。
- バンドルの情報取得には、カタログサブセクションのAPIコールを使用します。
購入制限は、バンドルの作成または更新時にlimitsオブジェクトを介して設定します。詳細については、制限の概要を参照してください。また、特定の国でアイテムを販売するために、地域制限を設定することも可能です。
バンドル管理のシナリオ：
- バンドルを作成する APIコールを使用して、バンドルを作成します。作成したバンドルを検証するには、バンドルを取得するAPIコールを使用します。プロジェクト内のすべてのバンドルを取得するには、バンドルリストを取得するAPIコールを使用します。
- 必要に応じて、バンドルを更新するAPIコールを使用し、バンドルの内容や設定を変更します。
- バンドルリストを取得する、指定したバンドルを取得する、または指定したグループのバンドルリストを取得するAPIコールを使用して、ストアフロントにバンドルの表示ロジックを実装します。
- カートと決済セクションを使用して注文を作成します。たとえば、素早く購入できるようにするには、バンドルのSKUを渡し、指定したアイテムを含む注文を作成するAPIコールを使用できます。応答には、決済UIを開くためのトークンが含まれています。
- 注文の支払いを行うために、決済UIを開く処理を実装します。
- 決済が完了したアイテムのデータをタイムリーに受け取り、ユーザーにそれらを付与するために、たとえばウェブフックを使用して注文ステータスのトラッキングを設定します。
概要
カートは、複数のアイテムを1つの注文にまとめることができる購入メカニズムです。ユーザーは、任意のタイプのアイテムを任意の数量で実際通貨で購入でき、プロモーションコードも使用できます。
カートはエクソーラ側で保存されます。セッションをまたいでカートを保存できるかどうかは、ユーザーが認証されているかによって異なります。
認証されたユーザーの場合、カートは特定のユーザーに紐付けられ、同じユーザーとしてリクエストが送信される限り、セッションをまたいで保存されます。
未認証ユーザーの場合、カートの保存は
x-unauthorized-idヘッダーの成否に依存します。未認証ユーザーのカートをセッション間で保持するには、すべてのリクエストで同じx-unauthorized-idを渡してください。なお、このオプションはゲームキーの販売時のみ利用可能です。
カートを特定する方法は2つあります。ユーザーのJWTによる自動特定、またはカートID（cart_id）による特定です。
カート管理は、クライアント側とサーバー側の両方で利用可能です。
サーバー側では、ユーザーセッションを復元する場合などに、カートにアイテムを入れることができます。クライアント側では、以下の操作が利用可能です：
- 現在のユーザーのカートまたはIDによるカートを取得する
- カートにアイテムを追加する
- カート内のアイテムを更新する
- カートからアイテムを削除する
カートからアイテムを購入するには、注文作成のためのクライアントとサーバーのコールが使用されます。
カートの有効期限（TTL）は、デフォルトで72時間です。新しいアイテムが追加されるなど、カートの内容が変更されると、TTLは延長されます。
決済が成功した後も、カートは自動的にはクリアされません。カートをクリアするには、クライアントサイドの以下のAPIコールを使用してください：
カートIDによるカートアイテムを削除するおよび 現在のカートからのカートアイテムを削除する：カート内の最後のアイテムを削除すると、カートはクリアされます。
カート使用シナリオ：
ユーザーがアイテムを選択するストアUIを実装します。
ユーザーがストアでアイテムを選択した際、たとえば カートへアイテムを追加するコールを使用してアイテムをカートに追加します。アイテム配列には、SKUと必要なアイテムの数量を渡す必要があります。
カート表示UIを実装します。ユーザーがカートに移動した際、現在のユーザーのカートを取得するコールを使用してカートの内容を表示します。応答には、割引や適用されたプロモーションを含むアイテムの最終価格に関する情報が返されます。
注文の支払いを行うために、決済UIを開く処理を実装します。たとえば、特定のカートの全アイテムを含む注文を作成するコールを使用できます。応答には、決済UIを開くためのトークンが返されます。
決済が完了したアイテムのデータをタイムリーに受け取り、ユーザーにそれらを付与するために、たとえばウェブフックを使用して注文状況の追跡を設定します。
注意
ゲーム内およびオンラインでのアイテム販売を実装するには、統合ガイドを参照してください。
注文のライフサイクル
注文のライフサイクルを理解することは、注文の追跡や、アイテムの付与といった購入後ロジックの正確な実装に役立ちます。
注文は以下のステータスを遷移します：
| ステータス | 説明 | 備考 |
new | 注文が作成されました。システムは支払い完了の確認を待っています。 | トランザクションステータスの説明は、ペイステーションAPIに関するドキュメントで確認できます。 |
paid | 注文の支払いが完了し（トランザクションがdoneステータスに移行）、ユーザーにアイテムを付与できる状態です | 支払いが確認されるまで、注文はnewステータスのままとなります。 |
done | アイテムがユーザーに付与されました。 | — |
canceled | 支払いが返金されました。 | トランザクションステータスがrefundedに変更されると、注文はこのステータスに移行します。 |
expired | 制限 付きアイテム、プロモーションコード、またはプロモーションに対して新しい注文を作成すると、そのアイテムを含む過去の未払いの注文はすべてexpiredステータスに移行します。支払いが可能なのは最新の注文のみです。 | ユーザーが有効期限切れの注文に対して支払いを試みた場合、支払いUIに 2002 エラーが表示され、決済は失敗します。 |
注意
ユーザーが支払いを完了する間に注文がexpiredステータスに移行した場合でも、決済自体が成功したときは、注文はexpiredからpaidステータスに移行します。ただし、これが適用されるのは、決済時にその注文アイテムの購入制限数を超えない場合に限られます。
無料アイテム
ユーザーに無料アイテムを付与するには、このセクションのコールを使用してください。
概要
購入制限を使用すると、単一のユーザーまたはすべてのユーザーが購入できるアイテム数量を制限できます。スケジュールされた制限リセットを設定することもできます。
制限はエクソーラ側に保存され、パブリッシャーアカウントで個々のアイテムレベルで設定されるか、以下のAPIコールのlimitsオブジェクトを介して設定されます：
制限情報は、アイテムカタログを取得するための以下のAPIコールでitems.limitsオブジェクトに返されます：
制限グループの管理サブセクションに属するAPIコールにより、制限の現在状態の取得、および指定したユーザーに対する制限値の更新が可能となります（例：クエスト完了時におけるカウンターのリセット、残存数量の手動調整など）。
共通地域
地域別の販売制限を使用すると、特定の国または国グループにおけるアイテムの可用性を管理できます。例えば、ライセンスの制約により、特定の国だけでゲームを販売するといったことが可能です。
制限の設定には「地域」を使用します。各地域は、1つ以上の国を単一のregion_idでまとめたものです。アイテムを1つ以上の地域に関連付けることができます。
アイテムの可用性は、以下のように判定されます：
- アイテムに地域の指定がない場合、すべての国で購入可能です。
- アイテムに地域が指定されており、ユーザーの国がそのいずれかに含まれている場合、そのユーザーはアイテムを購入できます。
- アイテムに地域が指定されており、ユーザーの国がどの地域にも含まれていない場合、そのユーザーはアイテムを購入できません。
ユーザーの国は、カタログセクションからのAPIコールを通じてカタログをリクエストする際、countryパラメータとして渡されます。このパラメータが渡されない場合は、ユーザーのIPアドレスに基づいて国が判定されます。
ユーザーの国とアイテムの地域との照合は、カタログのリクエスト時と注文作成時の2回行われます。購入不可のアイテムはカタログのレスポンスには含まれず、そのようなアイテムを含む注文が作成されることはありません。
地域の作成、更新、および削除には、共通地域グループのAPIコールを使用します。
地域別の販売制限のセットアップフロー：
- 地域を作成するAPIコールを使用して、対象となる国のリストを指定して地域を作成します。レスポンスには、次のステップで必要となる
region_idが返されます。 - アイテムを作成する際、または更新する際に、
regions配列にそのregion_idを渡すことで、仮想アイテムを地域に関連付けます。 - カタログセクションのAPIコール（例：仮想アイテムリストを取得するAPIコール）を使用して、ユーザーにカタログを表示します。ユーザーの国は
countryパラメータによって決定されます。このパラメータが提供されない場合は、ユーザーのIPアドレスに基づいて判定されます。ユーザーの国で利用不可のアイテムは、カタログの応答には含まれません。 - ユーザーがアイテムまたはカートの決済に進む際に、注文を作成します：
- アイテムをカートに追加している場合 — 特定のカートの全アイテムを対象とした注文を作成するまたは現在のカートの全アイテムを対象とした注文を作成するAPIコールを使用します。
- 単一アイテムの迅速な購入の場合 — アイテムのSKUを渡して指定したアイテムで注文を作成するAPIコールを使用します。
レスポンスには、決済UIを開くためのトークンが含まれています。
エクソーラは、ユーザーの国がアイテムに指定された地域に含まれているかを確認します。国がアイテムの地域に含まれていない場合、注文を作成することはできません。
- 注文を支払うための決済UIを開く処理を実装します。
