退款

退款Webhook POST

付款被取消后，艾克索拉向Webhook URL发送一个refund类型的Webhook并在其中包含已取消交易的详细信息。有关退款流程的详细信息请参阅这些说明。

如果收到带有5xx代码的响应，艾克索拉将以更长的时间间隔重新发送Webhook，直到侦听器确认接收。最大重试次数为12次。

注意

如果艾克索拉发起退款并收到Webhook包含5xx代码的响应，则付款仍将被退还。

您可以授予在Webhook中接收详细信息的权限。为此，您可以在发布商帐户的项目设置 > Webhooks > 高级设置 部分将以下开关切换为开：

开关描述

显示通过保存的支付方式进行的交易的信息

开关	描述
显示通过保存的支付方式进行的交易的信息	信息在Webhook的以下自定义参数中传递： `saved_payment_method`: `0` — 未使用保存的支付方式 `1` — 进行当前付款时保存了支付方式 `2` — 使用了之前保存的支付方式 `payment_type`: `1` — 一次性支付 `2` — 定期支付

信息在Webhook的以下自定义参数中传递：

saved_payment_method:
- 0 — 未使用保存的支付方式
- 1 — 进行当前付款时保存了支付方式
- 2 — 使用了之前保存的支付方式
payment_type:
- 1 — 一次性支付
- 2 — 定期支付

退款代码：

代码	退款理由	描述
1	Cancellation by the user request / the game request	用于在发布商帐户中发起取消的情况。
2	Chargeback	交易存在退单的情况。
3	Integration error	用于艾克索拉与游戏之间存在集成问题的情况。这种情况下，我们不建议将用户列入黑名单。
4	Potential fraud	存在欺诈嫌疑。建议：将该用户添加到黑名单。
5	Test payment	用于测试交易然后取消的情况。这种情况下，我们不建议将用户列入黑名单。
6	User invoice expired	用于通过用后付费模式的支付系统进行交易的情况。
7	Fraud notification from PS	支付被支付系统拒绝。支付系统检测到潜在欺诈行为。建议：将该用户添加到黑名单。
8	Cancellation by the PS request	用于支付系统请求取消的情况。这种情况下，我们不建议将用户列入黑名单。
9	Cancellation by the user request	用于用户请求取消的情况。可能出于某些原因导致用户对游戏或购买产生不满的情况下发生。这种情况下，我们不建议将用户列入黑名单。
10	Cancellation by the game request	用于游戏请求取消的情况。这种情况下，我们不建议将用户列入黑名单。
11	Account holder called to report fraud	用于账户持有人通知我们其未进行此交易的情况。
12	Friendly fraud	用于接收到友好型欺诈相关消息的情况。
13	Duplicate	有同一张发票的重复交易。

Request

Request Body schema: application/json

notification_type

required

string

通知类型。

required

object

交易ID。

agreement	integer 协议ID。
dry_run	integer 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
external_id	string 交易外部ID。
id	integer 交易ID。
payment_method_order_id	string 支付系统中的付款ID。

required

object

带有支付详细信息的对象。

object

直接预扣税。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。
percent	number <float> 直接预扣税税率。

object

带有用户支付相关数据的对象。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

支付系统佣金的大小。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

带有通过支付方式收费的金额相关数据的对象。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

带有支出详细信息的对象。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

payout_currency_rate

string

从支付币种到支出币种的汇率。

object

包含汇回本国费用数据的对象，该费用是第三方对艾克索拉收取的费用。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

销售税（对象；仅适用于美国和加拿大）。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。
percent	number <float> 销售税税率。

object

增值税大小（仅适用于欧盟）。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。
percent	number <float> VAT税率。

object

计入艾克索拉余额的金额。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

艾克索拉费用（对象）。

amount	number <float> 金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

custom_parameters

object

您的自定义参数。

object

带有购买相关数据的对象。

required

object

带有总购买价格相关数据的对象。

amount	number <float> 总购买金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

带有结账参数相关数据的对象。

amount	number <float> 购买金额。
currency	string 货币。符合ISO 4217的三字母货币代码。

object

订阅详情（对象）。

amount	number <float> 以实际货币表示的价格。
currency	string 货币。符合ISO 4217的三字母货币代码。
date_create	string 订阅的创建日期。符合 ISO 8601标准规定的日期与时间。
plan_id	string 计划ID（如果计划通过API创建，则为外部ID）。
subscription_id	integer 艾克索拉数据库的订阅ID。
tags	Array of strings 计划标签。

object

退款详情（对象）。

author

string

退款发起人。根据下表传入字段值：

退款发起人	字段值
游戏（通过API）。	API
发布商帐户用户（自动退款）。	用户邮箱
发布商帐户用户（通过艾克索拉客户支持的帮助）。	support@xsolla.com
艾克索拉（通过艾克索拉客户支持的帮助）。	support@xsolla.com

code

integer

代码ID。

reason

string

退款原因。

object

带有自定义项目设置的对象。

merchant_id	integer 商户ID。
project_id	integer 项目编号。您可以在您的发布商帐户项目名称旁边。

object

用户详情（对象）。

id required	string 用户ID。
country	string 用户所在国家/地区。使用ISO 3166-1 alpha-2 标准规定的2字母组合表示国家/地区。
email	string 用户电子邮件。
ip	string 用户 IP 地址。
name	string 用户名。
phone	string 用户电话号码（采用国际格式）。
zip	string 邮编。

Responses

204

返回以指示处理成功。

400

提供的信息出错时返回（例如，缺少必需的参数、授权失败等）。

500

返回以指示您的服务器存在的暂时性错误。

Request samples

CURL
PHP
HTTP

curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "refund",
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "purchase": {
            "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
            },
            "total":{
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1
        },
        "refund_details": {
            "code": 4,
            "reason": "Potential fraud"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": 10
            }
        }
    }
}'

Response samples

application/json

{"error": {"code": "INCORRECT_AMOUNT",
"message": "Incorrect amount"
}
}