订阅

订阅解决方案允许用户在指定条件下获得某个服务套餐的访问权限。主要功能：

• 定义基于订阅的产品。
• 定义计划。可为每种货币创建和配置计划、设置试用期、配置宽限期、查看订阅用户以及更改指定用户的订阅状态。
• 让用户在仪表板中管理其订阅。他们可以查看详细的订阅信息、浏览付款历史、更改计划以及暂停/续订/取消订阅。
• 在您的发布商帐户中管理用户订阅：为每种货币创建和配置计划、设置试用期、配置宽限期、查看订阅用户以及更改指定用户的订阅状态。
• 启用通过保存的付款帐户自动续订的功能。
• 允许用户手动续订订阅计划。

词汇表

订阅计划

订阅计划 — 用户获得服务访问权限的一系列账单条件（账单金额、付款货币及扣款频率）。

基于订阅的产品

基于订阅的产品 — 用户购买订阅后向其提供的一个或一组服务。

订阅

订阅 — 产品与所选计划的组合。用户选择订阅计划后即获得订阅并收到相应服务的访问权限。用户同时可拥有的订阅数取决于项目中的产品数。

示例1

产品：游戏的访问权限

• 订阅计划Silver：10美元1月
• 订阅计划Gold：100美元1年

用户可以选择以下订阅之一：

• 订阅1：通过10美元/月的订阅计划访问游戏
• 订阅2：通过100美元/年的订阅计划访问游戏

示例2

产品1：游戏1的访问权限

产品2：游戏2的访问权限

• 订阅计划：10美元1月

用户可以同时拥有两个订阅：

• 订阅1：通过10美元/月的订阅计划访问游戏1
• 订阅2：通过10美元/月的订阅计划访问游戏2

运行机制

步骤1

步骤2

步骤3

用户流程

订阅状态

一个订阅应处于以下状态之一：

• 活动。 主要状态。订阅会在首次成功付款后创建并激活。只有活动订阅才可能进行未来扣款。

• 已取消 。订阅已由于以下原因之一被立即取消：
  • 通过API方法或在艾克索拉发布商帐户中更改了状态。
  • 已被用户取消。
  • 已到期（如果参数中设置了到期日）。
  • 超过最大扣款尝试次数。默认为三次，如需更改默认值，请联系帐户经理。
  • 无法在游戏中找到该用户。
  • 用户帐户已删除。

• 未续订 。已取消续订。状态更改为“已取消”前，订阅将持续到当前付款周期结束。以下任一原因均可导致续订被取消：
  • 通过API方法或在发布商帐户中更改了状态。
  • 用户通过邮件链接进行了取消。
  • 用户帐户已删除。

集成过程

要集成订阅，请执行以下操作：

1. 注册艾克索拉发布商帐户。
2. 创建项目。
3. 设置订阅计划。
4. 设置Webhook。
5. 获取令牌。
6. 配置UI打开过程。
7. 设置产品。

创建项目

1. 转到 项目 ，然后单击 创建新项目 。
2. 在设置模式下：
   1. 指定webhook URL。
   2. 生成用于项目webhook签名的密钥。

设置订阅计划

1. 前往订阅设置：项目 > 商店 > 订阅。
2. 指定以下参数：
   • 名称
   • 账单周期

设置Webhook

需为订阅实现以下Webhook：

• 付款
• 创建了订阅
• 更新了订阅
• 退款
• 取消了订阅

通过发送不带消息正文的HTTP代码204来确认收到Webhook。关于Webhook的详细信息及示例，请参阅API参考。

如要测试Webhook处理程序，请打开 项目设置 > Webhook 部分。

获取令牌

需要令牌才能与订阅集成。令牌是一个包含游戏/用户数据和支付设置的字符串。

艾克索拉API使用基本认证。请指定您的商户ID作为用户名，API密钥作为密码。

获取令牌的URL：

https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

请求令牌

可通过包含要向订阅UI传递的参数来更改HTTP POST请求。请求和响应均为JSON格式。

以下为通过艾克索拉PHP SDK获得PHP令牌的范例代码。如使用其他编程语言，请单击CURL选项卡查看 CURL 示例。

<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME');

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
-X POST \
-u your_merchant_id:merchant_api_key \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-d '
{
    "user": {
        "id": {
            "value": "1234567"
        },
        "email": {
            "value": "email@example.com"
        }
    },
    "settings": {
        "project_id": 14004,
        "mode": "sandbox"
    }
}'

您可以在API参考中找到参数的完整列表。

测试支付流程

要测试付款过程，可：

• 使用沙盒
• 进行真实付款，然后通过发布商帐户发起退款

艾克索拉沙盒是一个独立环境，支持除真实付款外实时环境的所有功能。获得令牌后，您可以通过发送 "mode":"sandbox" 来访问沙盒。

要测试银行卡支付，请执行以下操作：

1. 在沙盒模式中打开订阅UI。
2. 选择要购买的物品。
3. 选择 信用卡/借记卡 付款方式组。
4. 输入银行卡详细信息。在其余字段中输入任意值。您也可以指定不正确的细节（卡号、到期日、或CVV）以生成错误。

用于测试的银行卡列表

如要通过进行真实付款来测试付款过程，同样建议使用银行卡：

1. 打开订阅UI。
2. 选择要购买的物品。
3. 选择信用卡/借记卡付款方式组。
4. 输入有效的银行卡详细信息。
5. 付款完成后，前往发布商帐户中的交易搜索部分。
6. 选择该测试交易，然后单击退款（交易状态必须为已完成）。

打开订阅UI

如要在新窗口中打开订阅UI，请使用下列链接：https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN，其中 ACCESS_TOKEN 是在上一步中获得的令牌。对于测试，请使用此URL：https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN。

设置产品

API方法用于管理基于订阅的产品。

促销选项

优惠券

优惠券功能允许合作伙伴创建优惠券活动，优惠码可由合作伙伴上传或在发布商帐户中生成。用户通过优惠券可获得虚拟货币、虚拟物品或订阅计划的试用权限。您可自定义优惠券兑换数量及有效期（如有）。

请参阅高级诀窍

奖励

奖励功能可设置当用户购买了某个订阅时向用户发放奖励。

请参阅高级诀窍

高级诀窍

以下高级诀窍可帮助您使用订阅的一些高级功能：

• 订阅被取消时取消上一笔付款
• 更改订阅计划
• 手动续订
• 高级反欺诈功能
• 奖励
• 优惠券