Xsolla-logo
  • 文档
  • 创建帐户

Successful payment for order (with payment and transaction details)Webhook POST

当用户订单支付成功时艾克索拉发送order_paid webhook到指定的URL。

order_paid webhook包含所购商品、付款数据和交易详细信息。

如果付款不成功，则不会发送order_paid webhook，例如：

  • 打开了支付表单，但用户没有为订单付款
  • 打开了支付表单，但付款过程中出现错误

建议order_paid webhook的处理时间小于3秒。

响应部分描述了预期的回答。您可以使用其他响应代码。根据响应码和自动退款功能的连接，艾克索拉侧的webhook处理逻辑如下：

响应代码 禁用了自动退款（默认） 启用了自动退款
400、401、402、403、404、409、422、415 无操作 自动退款给用户
200、201、204 无操作 无操作
不同代码或对webhook无响应 在指定的时间间隔内发送多个webhook：2次间隔5分钟的尝试，7次间隔15分钟的尝试，10次间隔60分钟的尝试。 在指定的时间间隔内发送多个webhook：2次间隔5分钟的尝试，7次间隔15分钟的尝试，10次间隔60分钟的尝试。如果发送了所有webhook后仍未收到成功响应，则会向用户自动退款。

要连接自动退款功能，请联系您的客户成功经理或发送电子邮件至csm@xsolla.com。

Request
Request Body schema: application/json
notification_type
required
string

通知类型。

required
Array of version = 1 (object) or version = 2 (object)

用户所购商品的列表。

The set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: is_free, is_bonus, and is_bundle_content. To switch the version, pass its number in the version parameter in the Update information about webhook settings API call.

Array
One of:
sku
required
string

项目的唯一ID。对于game_key类型的商品，使用sku_drm格式的值。

type
required
string

商品类型。它可以具有以下值：virtual_good、virtual_currency、game_key、bundle。对于bundle类型的商品（包括虚拟货币套餐），商品数组将显示：

  • 捆绑包或虚拟货币套餐的参数
  • 捆绑包中包含的商品或套餐中包含的货币
Enum: "virtual_good" "virtual_currency" "game_key" "bundle"
quantity
required
integer

商品数量。

amount
required
string

根据商品数量计算的总费用。

required
Array of objects

应用促销。如果未应用促销，则会在参数中传递一个空数组。

Array
amount_with_discount
string

应用折扣后商品总价。

amount_without_discount
string

不应用折扣的商品总价。

sequence
integer

应用促销活动的顺序。

is_pre_order
required
boolean

如果为true，则该商品为预订商品。

custom_attributes
object

包含商品属性和值的JSON对象。

required
object

订单信息。

id
required
integer

艾克索拉侧用户订单的唯一标识符。

mode
required
string

付款模式。对于真实支付，使用default；对于测试性支付，使用sandbox。

Enum: "default" "sandbox"
currency_type
required
string

支付货币类型。对于免费订单，则值指定为unknown。

Enum: Description
real

对于真实货币

unknown

对于免费订单

virtual

对于虚拟货币

currency
required
string

订单货币。虚拟货币使用SKU，真实货币使用三个字母的ISO 4217代码。

amount
required
string

基于所选货币的购物车总价。

status
required
string

订单状态。

platform
required
string or null

支付平台。 xsolla值用于通过艾克索拉进行的支付。其他支付使用与游戏发布平台名称对应的值。

Enum: "xsolla" "playstation_network" "xbox_live" "pc_standalone" "nintendo_shop" "google_play" "app_store_ios" "android_standalone" "ios_standalone" "android_other" "ios_other" "pc_other"
comment
required
string or null

用户对订单的备注。

invoice_id
required
string or null

实际货币付款发票ID。虚拟货币付款或免费商品的值为null。

required
Array of objects

应用促销。如果未应用促销，则会在参数中传递一个空数组。

Array
amount_with_discount
string

应用折扣后商品总价。

amount_without_discount
string

不应用折扣的商品总价。

sequence
integer

应用促销活动的顺序。

Array of objects

应用的优惠券。如未应用优惠券，则不会返回该数组。

Array
code
string

应用的优惠券的券码。

external_id
string

外部ID。

Array of objects

应用的促销码。如未应用促销码，则不会返回该数组。

Array
code
string

应用的促销码的代码。

external_id
string

外部ID。

required
object

用户信息。

external_id
required
string

用户ID。

email
required
string

用户邮箱地址。

object

交易和付款详细信息。

notification_type
required
string

通知类型。

required
object

交易ID。

agreement
integer

协议ID。

dry_run
integer

测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。

external_id
string

交易外部ID。详细信息请参阅常见问答。

id
integer

交易ID。

payment_date
string

付款日期。

payment_method
integer

付款方式ID。

payment_method_name
string

付款方式名称。

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的三字母货币代码。

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>

用户获取费费率(%)。

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的三字母货币代码。

object

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

required
object

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

amount
number <float>

总购买金额。

currency
string

货币。符合ISO 4217的三字母货币代码。

object

带有优惠券相关数据的对象（如果此交易使用了优惠券）。

campaign_code
string

优惠券营销活动的代码。

coupon_code
string

优惠券代码。

object

礼物详情（对象）。

giver_id
string

送礼人ID。

hide_giver_from_receiver
string

是否对收礼人隐藏送礼人的身份信息。

message
string

送礼人留言。

receiver_email
string

收礼人邮箱。

receiver_id
string

收礼人ID。

Array of objects

应用于此交易的促销活动。

Array
id
integer

促销活动 ID。

technical_name
string

促销活动的技术名称。

object

订阅详情（对象）。

amount
number <float>

以实际货币表示的价格。

currency
string

货币。符合ISO 4217的三字母货币代码。

date_create
string

订阅的创建日期。符合 ISO 8601标准规定的日期与时间。

date_next_charge
string

下次收费的日期。符合ISO 8601标准规定的日期与时间。

plan_id
string

计划ID（如果计划通过API创建，则为外部ID）。

product_id
string

产品ID（如果在访问令牌中发送）。

subscription_id
integer

艾克索拉数据库的订阅ID。

tags
Array of strings

计划标签。

object

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

merchant_id
integer

商户ID。

project_id
integer

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

custom_parameters
object

附加信息。

Responses
200

返回以指示处理成功。

400

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

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "order_paid",
    "items": [
      {
        "sku": "com.xsolla.item_1",
        "type": "virtual_good",
        "is_pre_order": false,
        "quantity": 3,
        "amount": "1000",
        "promotions": [
          {
            "amount_without_discount": "6000",
            "amount_with_discount": "5000",
            "sequence": 1
          },
          {
            "amount_without_discount": "5000",
            "amount_with_discount": "4000",
            "sequence": 2
          }
        ],
        "custom_attributes":
          {
            "purchased": 0,
            "attr": "value"
          }
      },
      {
        "sku": "com.xsolla.item_new_1",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "1000",
        "promotions": []
      },
      {
        "sku": "com.xsolla.gold_1",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 1500,
        "amount": "[null]",
        "promotions": []
      }
    ],
    "order": {
      "id": 1,
      "mode": "default",
      "currency_type": "virtual",
      "currency": "sku_currency",
      "amount": "2000",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": "1",
      "promotions": [
        {
          "amount_without_discount": "4000",
          "amount_with_discount": "2000",
          "sequence": 1
        }
      ],
      "promocodes": [
        {
          "code": "promocode_some_code",
          "external_id": "promocode_sku"
        }
      ],
      "coupons": [
        {
          "code": "WINTER2021",
          "external_id": "coupon_sku"
        }
      ]
    },
    "user": {
      "external_id": "id_xsolla_login_1",
      "email": "gc_user@xsolla.com"
    },
    "billing": {
      "notification_type": "payment",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "purchase": {
          "subscription": {
              "plan_id": "b5dac9c8",
              "subscription_id": "10",
              "product_id": "Demo Product",
              "date_create": "2014-09-22T19:25:25+04:00",
              "date_next_charge": "2014-10-22T19:25:25+04:00",
              "currency": "USD",
              "amount": 9.99
          },
          "total": {
              "currency": "USD",
              "amount": 200
          },
          "promotions": [{
              "technical_name": "Demo Promotion",
              "id": 853
          }],
          "coupon": {
              "coupon_code": "ICvj45S4FUOyy",
              "campaign_code": "1507"
          },
      "transaction": {
          "id": 1,
          "external_id": 1,
          "payment_date": "2014-09-24T20:38:16+04:00",
          "payment_method": 1,
          "payment_method_name": "PayPal",
          "payment_method_order_id": 1234567890123456789,
          "dry_run": 1,
          "agreement": 1
      },
      "payment_details": {
          "payment": {
              "currency": "USD",
              "amount": 230
          },
          "vat": {
              "currency": "USD",
              "amount": 0,
              "percent": 20
          },
          "sales_tax": {
              "currency": "USD",
              "amount": 0,
              "percent": 0
          },
          "direct_wht": {
              "currency": "USD",
              "amount": 0,
              "percent": 0
          },
          "payout_currency_rate": "1",
          "payout": {
              "currency": "USD",
              "amount": 200
          },
          "country_wht": {
              "currency": "USD",
              "amount": 2,
              "percent": 10
          },
          "user_acquisition_fee": {
              "currency": "USD",
              "amount": 2,
              "percent": 1
          },
          "xsolla_fee": {
              "currency": "USD",
              "amount": 10
          },
          "payment_method_fee": {
              "currency": "USD",
              "amount": 20
          },
          "repatriation_commission": {
              "currency": "USD",
              "amount": 10
          }
      },
      "custom_parameters": {
          "parameter1": "value1",
          "parameter2": "value2"
          }
      }
   }
}'
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.