支付中心API v2.0

概览

此部分介绍用于支付中心的方法。请使用基本认证来调用方法。要打开支付UI并启用安全支付,需先获取令牌

端点路径:https://api.xsolla.com

支付 UI

打开支付中心

支付中心是一个完整的支付UI,允许用户在您的网站上购买游戏和商品。要轻松在网站上实现该支付UI,请从我们的CDN下载以下脚本:链接。请使用该URL将脚本集成到您的网站。如需更多信息,请访问我们的GitHub存储库

用于脚本初始化的参数列表:

参数 类型 描述
access_token
string 令牌,由 API 接收。 必需
沙盒
boolean 设置为 true 以测试支付流程,将使用 sandbox-secure.xsolla.com 而不是 secure.xsolla.com
lightbox
object 带有选项列表的对象,可用于打开 lightbox(桌面版本)。
lightbox.width
string Lightbox 框架的宽度。如果为null,则取决于支付中心的宽度。默认值为null。
lightbox.height
string lightbox 框架的高度。如果为null,则取决于支付中心的高度。默认值为'100%'。
lightbox.zIndex
integer 控制垂直堆叠顺序的属性,默认值为 1000。
lightbox.overlayOpacity
integer 叠加的不透明度(从 0 到 1),默认值为'0.6'。
lightbox.overlayBackground
string 叠加的背景,默认值为'#000000'。
lightbox.modal
boolean lightbox 框架不可关闭,默认值为'false'。
lightbox.closeByClick
boolean 切换单击叠加关闭 lightbox,默认值为'true'。
lightbox.closeByKeyboard
boolean 切换按ESC键关闭 lightbox,默认值为'true'。
lightbox.contentBackground
string 框架的背景,默认值为'#ffffff'。
lightbox.contentMargin
string 框架页边,默认值为'10px'。
lightbox.spinner
string 加载过程显示控件的动画类型。可为'xsolla'或'round'。默认值为'xsolla'。
lightbox.spinnerColor
string 旋转加载动画的颜色,非默认设置。
childWindow
object 支付中心UI所在子窗口的选项。适用于移动版本。
childWindow.target
string 指定打开支付中心窗口的位置,可以是'_blank'、'_self'、'_parent',默认值为'_blank'。

脚本使您可以跟踪支付UI发生的事件。根据事件的类型,可以在网页上执行各种操作。

事件列表:

参数 描述
init 小部件初始化事件。
open 打开小部件时的事件。
load 已加载支付UI(支付中心)。
close 已关闭支付UI(支付中心)。
status 用户在状态页面上移动时的事件。
status-invoice 用户在状态页面上移动但支付尚未完成时的事件。
status-delivering 用户在状态页面上移动,支付完成以及我们正在发送支付通知时的事件。
status-done 用户在状态页面上移动且支付已成功完成时的事件。
status-troubled 用户在状态页面上移动但支付失败时的事件。

如果您想要自行初始化打开支付 UI,使用链接 https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN 即可。

如用于测试,请使用以下URL:https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN

Notice: 参数 access_token 包含隐私用户数据。请确保获取该参数时使用服务器对服务器通信。
Copy
Full screen
php
  • php
  • html
通过回调进行异步脚本加载的示例
<html>
<head lang="en">
    <meta charset="UTF-8">
</head>
<body>
    <button data-xpaystation-widget-open>Buy Credits</button>

    <?php \Xsolla\SDK\API\PaymentUI\PaymentUIScriptRenderer::send($paymentUIToken, $isSandbox = true); ?>
</body>
</html>
<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890'
    };
    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(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

<button data-xpaystation-widget-open>Buy Credits</button>

测试卡片列表

在沙盒中,您可以使用下列信用卡模拟成功的支付:

卡片 3-D Secure
卡号: 4111111111111111
过期日期日期: 12/20
CVV2: 123
卡片类型: VISA
没有
卡号: 5555555555554444
过期日期日期: 11/19
CVV2: 321
卡片类型: MasterCard
没有
卡号: 4000000000000010
过期日期日期: 12/20
CVV2: 123
卡片类型: VISA
卡号: 5200000000000114
过期日期日期: 11/19
CVV2: 321
卡片类型: MasterCard
卡号: 6759649826438453
过期日期日期: 12/25
CVV2: 321
卡片类型: Maestro

此外,您还可以使用下列数据模拟被拒绝的交易:

卡片 3-D Secure 描述
卡号: 4000000000000002
过期日期日期: 12/20
CVV2: 123
卡片类型: VISA
没有 资金不足
卡号: 5200000000000007
过期日期日期: 11/19
CVV2: 321
卡片类型: MasterCard
没有 资金不足
卡号: 4000000000000036
过期日期日期: 12/20
CVV2: 123
卡片类型: VISA
拒绝
卡号: 5200000000000031
过期日期日期: 11/19
CVV2: 321
卡片类型: MasterCard
拒绝

错误列表

代码 描述
0004-0001 令牌过期或者不正确。
0004-0008 错误的 URL(尝试以secure.xsolla.com访问沙盒模式或者以sandbox-secure.xsolla.com访问实时模式)。
0002-0004 未签署协议。
0004-0010 已禁止无令牌集成。
0010-0001 未找到套餐。
0010-0003 套餐未配置数字版权管理(DRM)。
1000-0003 该项目没有启用模块。

直接支付

列示已保存的支付帐户

列示已保存的用户支付帐户。

HTTP请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts

参数 类型 描述
project_id
integer 项目ID。
user_id
integer 用户ID。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$response = $xsollaClient->ListPaymentAccounts(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key
响应
<?php

// example response
$response = array (
    array (
        'type' => 'card',
        'id' => 1,
        'name' => '4111110000001111',
        'payment_system' =>
            array (
                'id' => 1380,
                'name' => 'Credit/Debit Cards',
            ),
    ),
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "type": "card",
        "id": 1,
        "name": "4111110000001111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]
[
    {
        "type": "card",
        "id": 1,
        "name": "4111110000001111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]

通过已保存的帐户收费

使用已保存的支付帐户收费。

HTTP请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

参数 类型 描述
project_id
integer 项目ID。 必需
user_id
integer 用户ID。 必需
type
string 支付帐户类型:卡片/paypal。 必需
account_id
integer 艾克索拉数据库中已保存的帐户的ID。 必需
user
object 带用户相关数据的对象。
user.ip
string 用户 IP。 必需
user.name
string 用户名。
purchase
object 带有购买相关数据的对象。
purchase.virtual_currency
object 带有虚拟货币相关数据的对象。
purchase.virtual_currency.quantity
float 使用虚拟货币购买的数量。
purchase.checkout
object 带有结账参数相关数据的对象。
purchase.checkout.currency
string 购买币种。参照ISO 4217标准的三字母货币代码。
purchase.checkout.amount
float 购买金额。
settings
object 带有购买设置相关数据的对象。
settings.mode
string 设置'沙盒'值以测试支付流程。对于真实支付,应移除此参数。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$response = $xsollaClient->ChargePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID,
    'request' => array (
         'user' =>
             array (
                 'ip' => '127.0.0.1',
                 'name' => 'John Smith',
             ),
         'purchase' =>
             array (
                 'virtual_currency' =>
                     array (
                         'quantity' => 100,
                     ),
                 'description' =>
                     array (
                         'value' => 'Test Purchase',
                     ),
             ),
         'settings' =>
             array (
                 'mode' => 'sandbox',
             ),
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/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"
    }
}'
响应
<?php

// example response
$response = array (
    'transaction_id' => 119478390
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "transaction_id": 119478390
}
{
    "transaction_id": 119478390
}

删除已保存的支付帐户

删除已保存的支付帐户。

HTTP请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

参数 类型 描述
project_id
integer 项目ID。
user_id
integer 用户ID。
type
string 支付帐户类型:卡片/paypal。
account_id
integer 艾克索拉数据库中已保存的帐户的ID。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$response = $xsollaClient->DeletePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID
));
DELETE /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
响应
<?php

// example response
$response = null;
HTTP/1.1 204 No Content