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

令牌化

令牌化指一组允许在不打开支付UI或无需用户操作的情况下安全处理付款的API方法。该模块允许您:

  • 获取已保存付款帐户的列表,
  • 使用已保存的付款帐户进行支付,
  • 删除付款帐户。

令牌化支持以下支付方式:

  • 信用卡
  • PayPal
  • Amazon
  • Skrill
  • Yandex
  • Webmoney
  • Qiwi
  • Liqpay Privat Bank

集成指南

用户必须通过Pay Station UI进行首次支付。一旦完成支付,Pay Station将生成一个令牌(即一个已保存的付款帐户ID),以在未来使用而无需用户操作或打开UI。

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

  1. 注册Xsolla发布商帐户
  2. 创建新项目
  3. 获取令牌
  4. 配置支付UI的打开。
  5. 配置webhook处理。
  6. 测试支付流程。
  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.打开Payment Wall模块。

获取支付UI令牌

需要令牌才能集成到支付UI。 令牌是一个包含游戏/用户数据和支付设置的字符串。 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

可通过以下方式打开支付UI:

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

要以沙盒模式打开支付UI,请使用下列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 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处理器,请执行以下操作:

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

测试支付流程

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

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

  1. 以沙盒模式打开支付UI。
  2. 单击信用卡/借记卡
  3. 根据下表输入银行卡详细信息。输入剩余字段的值。您也可以指定不正确的细节(卡号、到期日、或CVV)以生成错误。

用于测试的银行卡列表

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

启动模块

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

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

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

操作已保存付款帐户的方法

用户通过支付UI进行首次支付后,其付款帐户将被保存,从而使未来的支付无需用户操作或打开UI即可完成。

获取已保存付款帐户的列表

请求范例

CURL
curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key

响应范例

CURL
[
    {
        "type": "card",
        "id":1,
        "name": "411111******1111",
        "payment_system":{
            "id":1380,
            "name": "Credit/Debit Cards"
        }
    }
]

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

使用已保存的付款帐户进行支付

请求范例

CURL
$ curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user":{
        "ip":"127.0.0.1",
        "name": "John Smith"
    },
    "purchase":{
        "virtual_currency":{
            "quantity": 100
        },
        "description":{
            "value": "Test Purchase"
        }
    },
    "settings":{
        "mode":"sandbox"
    }
}'

响应范例

CURL
{
    "transaction_id": 119478390
}

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

删除保存的付款帐户

请求范例

CURL
$ curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

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