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 — 定期支付
Add order object to 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
integer <float>

金额。

currency
string

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

percent
integer <float>

直接预扣税税率。

object

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

amount
integer <float>

金额。

currency
string

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

object

支付系统佣金的大小。

amount
integer <float>

金额。

currency
string

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

object

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

amount
integer <float>

金额。

currency
string

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

object

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

amount
integer <float>

金额。

currency
string

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

payout_currency_rate
string <float>

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

object

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

amount
integer <float>

金额。

currency
string

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

object

销售税(对象;仅适用于美国和加拿大)。

amount
integer <float>

金额。

currency
string

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

percent
integer <float>

销售税税率。

object

增值税大小(仅适用于欧盟)。

amount
integer <float>

金额。

currency
string

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

percent
integer <float>

VAT税率。

object

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

amount
integer <float>

金额。

currency
string

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

object

艾克索拉费用(对象)。

amount
integer <float>

金额。

currency
string

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

custom_parameters
object

您的自定义参数。

object

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

required
object

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

amount
integer <float>

总购买金额。

currency
string

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

object

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

amount
integer <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

Object that contains information about an order. To receive this information, set the Add order object to webhook toggle to On in Publisher Account in the Project settings > Webhooks > Advanced settings section.

id
integer

订单ID。

object

包含商品信息的对象。

object

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

amount
float

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

currency
string

商品价格的货币单位。

quantity
integer

物品数量。

sku
string

商品SKU。

Array of objects

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

Array
id
integer

促销活动 ID。

technical_name
string

促销活动的技术名称。

object

订阅详情(对象)。

amount
integer <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
        },
        "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": {
    }
}