The following documentation was deprecated. Current version is available at developers.xsolla.com

订阅

订阅模块允许您向用户销售订阅服务,使其在特定时间段内可访问您的服务。具体如下:

  • 让用户可在仪表板中管理其订阅。他们可看到详细的订阅信息、查看付款历史、变更计划及暂停/恢复/取消订阅。
  • 您可使用Xsolla发布商帐户管理用户订阅。您可为每种货币创建并配置计划、设置试用期、配置宽限期、查看订阅的用户及更改特定用户的订阅状态。
  • 启用保存的付款帐户自动续订。
  • 手动续订。

订阅状态

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

  • Active。主要状态。订阅会在首次成功付款后创建并激活。只有活动订阅才可能进行未来扣款。
  • Canceled。订阅已由于以下原因之一被立即取消:

    • 通过API方法或从Xsolla发布商帐户中取消。
    • 用户已取消。
    • 订阅已到期(如果参数中设置了到期日期)。
    • 超过最大扣费尝试次数(默认为3次;如要更改该值,请联系帐户经理)。
    • 无法在游戏中找到该用户。
    • 用户帐户已删除。
  • Non renewing。已取消续订。状态更改为Canceled前,订阅将持续到当前付款周期结束。以下任一原因均可导致续订被取消:

    • 通过API方法或从Xsolla发布商帐户中取消。
    • 用户通过邮件链接进行了取消。
    • 用户帐户已删除。

集成指南

若要集成模块,请执行以下操作:

  1. 注册Xsolla发布商帐户
  2. 创建新项目
  3. 配置模块
  4. 获取令牌
  5. 配置商店UI的打开。
  6. 配置webhook处理。
  7. 测试支付流程。
  8. 启动模块和签署协议。

您需要提供以下参数来进行集成:

  • 商户ID — 显示在发布商帐户URL中:https://publisher.xsolla.com/{merchant_id}/
  • API秘钥 — 在发布商帐户 > 设置 > 公司中生成。
  • 项目ID — 查看项目设置时将显示在发布商帐户URL中:https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/
  • 项目秘钥 — 在项目设置中生成。

创建项目

  1. 转到项目,然后单击创建新项目
  2. 在设置模式中:
    a.指定webhook URL。
    b.生成用来签名项目webhook的秘钥。
    c.启用订阅 模块。

配置模块

  1. 转到订阅模块设置,然后单击创建新计划。指定以下参数:
    • 名称。
    • 付款周期。
  2. 单击创建
  3. 单击返回计划列表返回基本模块设置并创建所需的其他计划。

重要事项! 一个计划只能用一种货币。您必须为每种项目货币创建单独的计划。

获取商店令牌

需要令牌才能集成到商店。 令牌是一个包含游戏/用户数据和支付设置的字符串。 Xsolla API使用基本HTTP身份验证。请指定您的商户ID作为用户名,API秘钥作为密码。

要启用沙盒模式,请设置"mode" = "sandbox"。

获取令牌的URL:

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

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

以下是使用PHP和Xsolla PHP SDK获取令牌的示例。如果使用的是其他语言,请参阅基于CURL的示例(单击CURL)。

PHP
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')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
    curl -v https://api.xsolla.com/merchant/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参考中找到参数的完整列表。

打开商店UI

可通过以下方式打开商店:

  • 使用Pay Station嵌入脚本,
  • 在新窗口打开,或
  • 在iframe中打开。

要以沙盒模式打开商店,请使用下列URL:https://sandbox-secure.xsolla.com/

Pay Station Embed

Pay Station嵌入脚本将确定设备类型并以灯箱模式(桌面屏幕)或在新窗口(手机或平板电脑屏幕)中打开商店UI。我们推荐使用异步脚本加载。

异步加载范例

 <script>
     var options = {
         access_token:'ACCESS_TOKEN', //TODO 使用上一步中接收到的访问令牌
         沙盒: true //TODO 请发布时记得删除该设置
     };
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
     s.addEventListener('load', function (e) {
         XPayStationWidget.init(选项);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

<button data-xpaystation-widget-open>购买信用</button>

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

新建窗口

若要在新窗口中打开支付UI,请使用下列链接:https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN,其中ACCESS_TOKEN是在上一步中获得的令牌。

Iframe

若要在iframe中打开商店UI,您必须实施下列机制:

  • 检查设备类型(桌面或移动设备) 并将其包含在令牌的settings.ui.version参数内发送;
  • 通过 postMessage从支付UI接收事件。

若要在新窗口中打开支付UI,请使用下列链接:https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN,其中ACCESS_TOKEN是在上一步中获得的令牌。

配置Webhook

Xsolla将向您的项目发送以下webhook:

  • 支付
  • 订阅已创建
  • 订阅已更新/续期
  • 退款
  • 订阅已取消

通过发送不带消息正文的HTTP代码204来确认收到webhook。您可在API参考中查看关于webhook处理的更多信息和示例。

创建签名

要创建电子签名,我们将:

  1. 连接Xsolla服务器请求中发送的数据和项目秘钥(在项目设置中生成)。
  2. 使用SHA1算法对字符串进行散列。
  3. 发送签名标头中的签名。

处理webhook时,请确保收到的签名与签名标头中设置的签名相符。

支付

用户完成支付后,Xsolla服务器将发送一个包含支付详情的webhook。

请求范例

PHP
CURL
$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_items' => array(
            'items' => array(
                0 => array(
                    'sku' => 'test_item1',
                    'amount' => 1,
                    ),
                1 => array(
                    'sku' => 'test_item2',
                    'amount' => 1,
                    ),
                2 => array(
                    'sku' => 'test_item3',
                    'amount' => 1,
                    ),
            )
        ),
        '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
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 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
        )
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"payment",
    "purchase":{
        "virtual_items":{
            "items":[
                {
                    "sku":"test_item1",
                    "amount": 1
                },
                {
                    "sku":"test_item2",
                    "amount": 1
                },
                {
                    "sku":"test_item3",
                    "amount": 2
                },
            ]
        },
        "total":{
            "currency":"USD",
            "amount": 9.99
        }
    },
    "user":{
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":"1234567",
        "country":"US"
    },
    "transaction":{
        "id":87654321,
        "payment_date":"2014-09-23T19:25:25+04:00",
        "payment_method":1380,
        "dry_run": 1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount": 9.99
        },
        "vat":{
            "currency":"USD",
            "amount": 0
        },
        "payout_currency_rate":1,
        "payout":{
            "currency":"USD",
            "amount": 9.49
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount": 0.19
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount": 0.31
        }
    }
}'

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

订阅已创建

用户创建订阅后,Xsolla服务器将发送一个包含订阅详情的webhook。

PHP
CURL
<?php
$request = array(
    'notification_type' => 'create_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla 用户'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => '展示品',
        '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",
        "user":{
            "id":"1234567",
            "name":"Xsolla 用户"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"展示品",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge":"2015-01-22T19:25:25+04:00",
            "trial":{
                    "value":90,
                    "type":"day"
                }
        }
    }'

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

Subscription Updated/Extended

用户更改订阅计划、续订、或下个账单日期发生更改时,Xsolla服务器将发送一个webhook。

请求范例

PHP
CURL
<?php
$request = array(
    'notification_type' => 'update_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla 用户'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => '展示品',
        '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",
        "user":{
            "id":"1234567",
            "name":"Xsolla 用户"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"展示品",
            "date_next_charge":"2015-01-22T19:25:25+04:00"
        }
    }'

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

Refund

用户取消付款后,Xsolla服务器将发送一个包含支付详情的webhook。

请求范例

PHP
CURL
$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => '金币',
            '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' => (
            'code' => 1,
            'reason' => '欺诈'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 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
        )
    )
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"refund",
    "purchase":{
        "virtual_currency":{
            "name":"金币",
            "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 用户",
        "country":"US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":1,
        "reason":"欺诈"
    },
    "payment_details":{
        "xsolla_fee":{
            "currency":"USD",
            "amount":"10"
        },
        "payout":{
            "currency":"USD",
            "amount":"200"
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":"20"
        },
        "payment":{
            "currency":"USD",
           "amount":"230"
        }
    }
}'

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

Subscription Canceled

订阅被取消时,Xsolla服务器将发送一个webhook。

请求范例

PHP
CURL
<?php
$request = array(
    'notification_type' => 'cancel_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla 用户'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => '展示品',
        '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",
        "user":{
            "id":"1234567",
            "name":"Xsolla 用户"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"展示品",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_end":"2015-01-22T19:25:25+04:00"
        }
    }'

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

测试webhook

若要测试webhook处理器,请执行以下操作:

  1. 在您的发布商帐户中打开模块设置。
  2. 转到测试选项卡。
  3. 输入测试数据,然后单击测试。Xsolla服务器将发送所有可能的webhook。
  4. 响应有效时,测试标记为绿色,发生错误时标记为红色。

测试支付流程

Xsolla Sandbox是一个独立环境,支持除真实付款外实时环境的所有功能。您可以通过在获得令牌时发送"mode" = "sandbox"来访问沙盒。

若要测试银行卡支付,请执行以下操作:

  1. 在沙盒模式中打开商店。
  2. 选择要购买的物品。
  3. 单击信用卡/借记卡
  4. 根据下表输入银行卡详细信息。输入剩余字段的值。您也可以指定不正确的细节(卡号、到期日、或CVV)以生成错误。

用于测试的银行卡列表

重要事项!沙盒模式下银行卡支付只能使用美元、欧元、卢布或英镑。

启动模块

若要在测试成功后启动模块,请在发布商帐户中打开其设置,转到启动选项卡,然后单击

重要事项!您需要完成以下操作后才能接受真实付款:

  1. 删除"sandbox"模式。
  2. 签署协议。

使用游戏参数防欺诈

您可以使用在令牌中传递的custom_parameters对象来发送用户的游戏数据并检测可疑活动。例如,玩游戏时间很少但等级却很高的玩家较为可疑,其创建帐户的目的可能是使用偷来的银行卡使角色获得较高等级后出售该帐户。

可用参数列表

请将您想要传递的参数以及这些参数的触发值告知您的帐户经理。我们将使用这些信息配置您的反欺诈筛选器。

使用所选方式付款

打开商店后,您可以在settings.payment_method参数中发送支付方式ID。在该情况下,用户将被立即重定向到所选支付方式的支付表单。

请求范例

CURL
    curl -v https://api.xsolla.com/merchant/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"
            },
        },
        "settings":{
            "project_id":14004,
            "payment_method": 24
        }
    }'

您可以在发布商帐户 >付款系统中获取支付方式ID列表,或使用列出付款系统API方法获取。

购买所选计划

打开商店后,您可以在purchase.subscription.plan_id参数中发送计划ID。在该情况下,用户将被立即重定向到支付UI。

请求范例

CURL
    curl -v https://api.xsolla.com/merchant/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"
            },
        },
        "settings":{
            "project_id": 14004
        },
        "purchase": {
            "subscription": {
                "plan_id": 123
                },
        }
    }'

订阅被取消时取消上一笔付款

如果订阅被取消,您可同时取消上一笔付款。要进行该操作,请在更新订阅方法中使用cancel_subscription_payment参数。您也可以让用户选择在已取消订阅的情况下获得上一笔付款的退款。若要启用该功能,请联系您的帐户经理。

更改计划

您可以使用更新计划方法更改订阅计划。新计划将于下一周期开始生效。

下列情况下无法更改计划:

  • 用户处于该计划的活动订阅状态,
  • 订阅状态为CanceledNon renewing,或者
  • 该计划为试用订阅。

如果更改计划失败,则将取消订阅。

每月续订

默认情况下,系统使用用户保存的付款详细信息自动进行续订。您可以允许用户使用无法保存的支付方式手动进行续订且不支持自动扣费。要在付款周期结束时续订,用户需点击邮件通知中的链接进行操作。若要启用该功能,请联系您的帐户经理。

使用产品

如果要在数个订阅中使用相同的计划,则可将这些订阅作为产品的一部分销售。产品是用户可订阅且属于同一组的计划的集合。您可以为不同的产品使用相同的计划。

请使用以下API方法配置产品:创建/更新/删除 产品;列出 产品。

奖励

订阅模块允许您使用游戏货币或游戏物品对续订的用户进行奖励。要启用该功能,请先启用虚拟货币和/或虚拟物品模块。如有任何问题,请联系您的帐户经理。