Xsolla-logo
  • 文档
  • 创建帐户

支付Webhook POST

当用户完成付款时,艾克索拉会向Webhook URL发送一个包含付款详细信息的payment类型的Webhook。

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

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

开关 描述
显示保存的支付帐户的信息 有关保存的支付方式的信息在payment_account自定义对象中传递。
显示通过保存的支付方式进行的交易的信息

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

  • saved_payment_method:
    • 0 — 未使用保存的支付方式
    • 1 — 进行当前付款时保存了支付方式
    • 2 — 使用了之前保存的支付方式
  • payment_type:
    • 1 — 一次性支付
    • 2 — 定期支付
将订单对象添加到Webhook 有关订单的信息在支付Webhook的order对象中传递。
仅发送不含敏感数据的必要用户参数

Webhook中仅传递用户的以下信息:

  • ID
  • 国家/地区
显示银行卡BIN和后缀码

Webhook中传递以下银行卡号的信息:

  • card_bin参数中的前6位数字
  • card_suffix中的后4位数字
显示银行卡品牌 用于付款的银行卡的品牌。例如,Mastercard或Visa。
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_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的三字母货币代码。

custom_parameters
object

您的自定义参数。

object

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

required
object

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

amount
number <float>

总购买金额。

currency
string

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

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。

object

包含订单信息的对象。要接收此信息,请在发布商帐户项目设置 >Webhooks > 高级设置部分中将将订单对象添加到Webhook开关设置为

id
integer

订单ID。

object

包含商品信息的对象。

object

包含商品价格信息的对象。

amount
number <float>

商品在所选货币下的总价。

currency
string

商品价格的货币单位。

quantity
integer

物品数量。

sku
string

商品SKU。

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

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

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

提供的信息有错误(例如,缺少必需的参数、授权失败等)时返回。在这种情况下,用户的钱已扣,但是购买失败。要退款,请发送邮件至support@xsolla.com联系艾克索拉客户支持。

500

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

Request samples
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "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
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": 853
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        },
        "order": {
          "id": 1234
          "lineitems": [
          {
            "sku": "test_1",
            "quantity": 1,
            "price": {
              "currency": "EUR",
              "amount": 6.5
              }
          }
          ]
          }
    },
    "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,
        "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"
    }
}'
Response samples
application/json
{
  • "error": {
    }
}