Xsolla-logoXsolla Developers
or
To Publisher Account

Order cancellation (with payment and transaction details)Webhook POST

Xsolla sends the order_canceled webhook to the specified URL when the payment is canceled by the user, partner, or automatically. The webhook contains information about returned items, payment data and details of the canceled order.

The webhook is not sent if the payment is not successful, for example:

  • the payment UI was opened but the user did not pay for the order
  • the payment UI was opened but there were errors during the payment

The recommended webhook processing time is within 3 seconds.

Request
Request Body schema: application/json
notification_type
required
string

Notification type.

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

List of items purchased by the user.

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

Unique ID of the item. For items with the game_key type, a value in sku_drm format is used.

type
required
string

Items type. For bundle type items, including virtual currency packages, the items array will display:

  • parameters of the bundle or virtual currency package
  • items included in the bundle or currencies included in the package

The value_point type is used in loyalty points operations – when points are spent or awarded.

Enum: "virtual_good" "virtual_currency" "game_key" "bundle" "value_point"
quantity
required
integer

Quantity of items.

amount
required
string

Total cost of items based on their quantity.

required
Array of objects

Applied promotions for specific items in the order. The array is returned in the following cases:

  • A discount promotion is configured for a specific item.
  • A promo code with the Discount on selected items setting is applied.

If no item-level promotions are applied, an empty array is returned.

Array
amount_without_discount
string

Total cost of items without a discount.

amount_with_discount
string

Total cost of items with a discount.

sequence
integer

Order of promotions application.

is_pre_order
required
boolean

If true, the item is pre-order.

custom_attributes
object

A JSON object containing item attributes and values.

required
object

Information about the order.

id
required
integer

Unique identifier of the user's order on the Xsolla’s side.

mode
required
string

Payment mode. default is used for real payments; sandbox for test payments.

Enum: "default" "sandbox"
currency_type
required
string

Payment currency type. For a free order, unknown value is specified.

Enum: Description
real

real currency

virtual

virtual currency

unknown

free order

loyalty_point

loyalty points

currency
required
string

Currency of order. Virtual currency uses the SKU and real currency uses a three-letter ISO 4217 code.

amount
required
string

The total cost of a cart based on the chosen currency.

status
required
string

Order status.

platform
required
string or null

Payment platform. The xsolla value is used for payments via Xsolla. For other payments, the value corresponding to the name of the game publishing platform is used: playstation_network, xbox_live, pc_standalone, nintendo_shop, google_play, app_store_ios, android_standalone, ios_standalone, android_other, ios_other, pc_other.

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

User’s commentary to the order.

invoice_id
required
string or null

Real currency payments invoice ID. Virtual currency payments or free items have a null value.

required
Array of objects

Applied promotions for the entire order. The array is returned in the following cases:

  • A promotion affects the total purchase amount, such as a promo code with the Discount on purchase setting.
  • No discount is applied to the purchase, but bonus items are added to the order. In this case, the values for the cost with discount (amount_with_discount) and without discount (amount_without_discount) are returned and identical, since no discount is applied.

If no order-level promotions are applied, an empty array is returned.

Array
amount_without_discount
string

Total cost of items without a discount.

amount_with_discount
string

Total cost of items with a discount.

sequence
integer

Order of promotions application.

Array of objects

Applied coupons. If the coupon isn’t applied, the array doesn’t return.

Array
code
string

The code of an applied coupon.

external_id
string

External ID.

Array of objects

Applied promocodes. If the promocode isn’t applied, the array doesn’t return.

Array
code
string

The code of an applied promocode.

external_id
string

External ID.

required
object

User information.

external_id
required
string

User ID.

email
required
string

User email address.

country
string

User’s country. Two-letter uppercase ISO 3166-1 alpha-2 country code.

object

Transaction and payment details.

notification_type
required
string

Notification type.

required
object

Transaction details (object).

id
integer

Transaction ID.

external_id
string

Transaction external ID.

payment_method_order_id
string

Payment ID in the payment system.

dry_run
integer

Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.

agreement
integer

Agreement ID.

required
object

Payment details (object).

object

Amount paid by the user (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

Amount debited from the payment system.

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

Amount debited from Xsolla balance.

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

Payout details (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

VAT details (object; EU only).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

percent
number <float>

VAT rate.

payout_currency_rate
string

Exchange rate between payment and payout currencies.

object

Withholding tax applied in specific countries due to cross-border transactions (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

percent
number <float>

Country withholding tax rate, %.

object

Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

percent
number <float>

User acquisition fee rate, %.

object

Xsolla fee (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

Payment system fee.

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

Sales tax (object; USA and Canada only).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

percent
number <float>

Sales tax rate.

object

Direct withholding tax.

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

percent
number <float>

Direct withholding tax rate.

object

Object with data on repatriation costs, imposed on Xsolla by third parties.

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Amount.

object

Custom project settings (object).

project_id
integer

Project ID. You can find this parameter in your Publisher Account next to the name of the project.

merchant_id
integer

Merchant ID.

object

Purchase details (object).

required
object

Total price of purchase (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Total payment amount.

object

Subscription details (object).

plan_id
string

Plan ID (external if the plan was created via API).

subscription_id
integer

Subscription ID in Xsolla database.

tags
Array of strings

Plan tags.

date_create
string

Subscription creation date. Date and time per ISO 8601.

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Price in real currency.

object

Refund details (object).

code
integer

Code ID.

reason
string

Refund reason.

author
string

Refund initiator. The field value is passed according to the table:

Refund initiator Field value
Game (via API). API
Publisher Account user (automatic refund). User email
Publisher Account user (with assistance from Xsolla customer support). support@xsolla.com
Xsolla (with assistance from Xsolla customer support). support@xsolla.com
custom_parameters
object

Additional information.

Responses
200

Return to indicate successful processing.

400

Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.).

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_canceled",
    "items": [
      {
        "sku": "com.xsolla.v.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.v.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": "email@example.com",
      "country": "US"
    },
    "billing": {
      "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
              },
              "total":{
                  "currency": "USD",
                  "amount": 200
              }
          },
      "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
              }
          }
    }
}
System statusAll services operational

Privacy Settings

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