Pay2Play

Pay2Play模块允许游戏开发者直接从游戏网站销售PIN码。用户可使用Pay2Play小组件来访问商店。该模块提供多种集成选项，允许开发者：

选择不同DRM平台，
针对不同DRM平台设置不同价格，
配置小组件大小和颜色主题，以及
向开发者打赏。

用户流程

集成选项

您可以选择高级模式或简单模式来集成模块。

基本集成

基本集成：

可快速执行，
无需生成令牌或服务器执行，且
适用于不要求用户预先授权的游戏。

高级集成

高级集成：

允许您安全传输用户和订单数据以便在游戏侧进行进一步链接，且
要求服务器侧执行。

基本集成指南

要实现基本集成，请执行以下操作

注册Xsolla发布商帐户。
创建项目。
配置模块。
测试支付流程。
将Pay2Play小组件添加到游戏页面。
签署协议。

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

项目ID — 查看项目设置时将显示在发布商帐户URL中：https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/。

创建项目

转到项目，然后单击创建新项目。
在设置模式中：
- 将Webhooks设置为关。
- 将无服务器集成设置为开。
- 启用Pay2Play模块。

配置模块

转到Pay2Play模块设置，为游戏配置以下参数：
- 名称。
- 描述。
- 系统要求。
- SKU — 唯一标识符。
- 发布日期。
- 图像。
- DRM平台。
- 所选DRM平台支持的操作系统/游戏控制台版本。
单击下一步。
为所选DRM平台配置价格。单击下一步。
将已上传PIN码设置为开。
为所选DRM平台上传PIN码。

测试支付流程

Xsolla Sandbox是一个独立环境，支持除真实付款外实时环境的所有功能。您可通过以下方式访问Sandbox：在access_data对象中发送"settings.mode" = "sandbox"。access_data中的JSON结构和参数与令牌请求中的一样。

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

在沙盒模式中打开商店。
选择要购买的物品。
选择信用卡/借记卡支付方式组别。
输入银行卡详细信息。输入其他字段中的值。您也可以指定不正确的细节（卡号、到期日、或CVV）以生成错误。

用于测试的银行卡列表

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

集成Pay2Play小组件

Pay2Play小组件将以灯箱模式（桌面屏幕上）或在新窗口（手机或平板电脑屏幕上）中打开您的商店。该小组件会自动确定设备类型。要获得小组件代码，请在您的发布商帐户中打开模块设置，然后转到发布选项卡。复制所需小组件的代码并添加到您的游戏网站。我们推荐使用异步加载。

异步加载范例

HTML

 <script>
     var access_data = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
     var target_element = "#widget-example-element";
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
     s.addEventListener('load', function (e) {
         var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

您可在API参考中找到小组件初始化参数的完整列表，并可在GitHub上找到其安装说明。

高级集成指南

要实现高级集成，请执行以下操作：

注册Xsolla发布商帐户。
创建项目。
配置模块。
获取令牌。
设置webhook处理。
测试支付流程。
将Pay2Play小组件添加到游戏页面并签署协议。

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

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

创建项目

转到项目，然后单击创建新项目。
在项目设置中：
- 将Webhooks设置为开。
- 指定webhook URL。
- 生成用来签名项目webhook的秘钥。
- 将无服务器集成设置为关。
- 启用Pay2Play模块。

配置模块

转到Pay2Play模块设置，为游戏配置以下参数：
- 名称。
- 描述。
- 系统要求。
- SKU — 唯一标识符。
- 发布日期。
- 图像。
- DRM平台。
- 所选DRM平台支持的操作系统/游戏控制台版本。
单击下一步。
为所选DRM平台配置价格。单击下一步。
将已上传PIN码设置为开。
为所选DRM平台上传PIN码。

获取商店令牌

需要令牌才能集成到商店。令牌是一个包含游戏/用户数据和支付设置的字符串。 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参考中找到参数的完整列表。

设置Webhooks

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

用户验证
支付
退款

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

创建签名

要创建电子签名，我们将：

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

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

用户验证

Xsolla服务器会向项目的webhook URL发送请求以验证用户在游戏中是否存在。

请求范例

PHP

CURL

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

curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"user_validation",
    "user":{
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":"1234567",
        "country":"US"
    }
}'

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

支付

用户完成支付后，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参考中找到参数的完整列表。

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参考中找到参数的完整列表。

测试webhook

若要测试webhook处理器，请执行以下操作：

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

测试支付流程

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

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

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

用于测试的银行卡列表

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

集成Pay2Play小组件

异步加载范例

HTML

 <script>
     var access_data = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
     var target_element = "#widget-example-element";
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
     s.addEventListener('load', function (e) {
         var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

您可在API参考中找到小组件初始化参数的完整列表，并可在GitHub上找到其安装说明。

其他功能

开发者打赏

用户购买时可对项目进行打赏。要启用该选项，请打开Pay2Play价格设置，然后将在Pay2Play小组件中使用小费设置为开。对于添加的每种货币，系统提供三个预定义的打赏金额。

用户可以在进入商店前选择打赏金额。打赏金额将添加到购买价。

通过API交付PIN码

您可以在每次购买后发送PIN码，而无需在一个文件中上传PIN码列表。若要启用该功能，请执行以下操作：

执行获取PIN码webhook。
在Pay2Play设置中，转到上传PIN码，将根据需求设置为开，并将已上传PIN码设置为关。

限制PIN码销售数量

您可以限制项目可销售的PIN码的数量。您将收到两个电子邮件通知：一个在剩余PIN码小于等于100个时发送，另一个在全部售空时发送。如果超出数量限制，用户将无法付款。

限制销售区域

Pay2Play模块允许配置PIN码销售的区域限制：具体如下：

为单个国家/地区或国家/地区组设置不同价格；
禁止在某些国家/地区销售。

正确完成项目配置后，如果用户试图在受限国家/地区购买PIN码，将显示相应的警告。对于禁止销售PIN码的国家/地区，付款将无法完成。

若要启用该功能，请联系您的帐户管理员。对于要实施区域限制的每个平台，请提供以下信息：

限制类型：
- 激活：PIN码只能在某些国家/地区激活。
- 启动：PIN码可以在任何国家/地区激活，但是游戏只能在某些国家/地区中启动；
- 激活和启动：只能在某些国家/地区激活PIN码和启动游戏。
实施不同PIN码价格的国家/地区组列表。
每组国家/地区的设置：
- 组名称。
- SKU — 唯一组标识符。
- 不同币种的价格列表。务必包含模块设置中设定的默认货币的价格。
- 每组内的国家/地区列表。
禁用PIN码的国家/地区列表（如有）。

对于任何单一平台，一个国家/地区要么属于不同价格组，要么属于预订被禁用组。如果某个国家/地区不属于任何组，则PIN码的销售不受任何限制，价格为默认模块设置中的价格。

重要事项！如果是您或DRM平台来负责PIN码激活和游戏启动，则请确保发布之日已配置好区域限制，并上传PIN码。