Xsolla-logo

Order cancellationWebhook POST

Xsolla sends the order_canceled webhook to the specified URL when the following conditions are fulfilled:

  1. The payment was canceled by the user, partner, or automatically.
  2. Xsolla received a response about the successful processing of refund webhook.

The order_canceled webhook contains information about returned items and details of the canceled transaction.

The order_canceled webhook will not be sent if:

  • The payment was not successful, for example:
    • the payment form was opened, but the user did not pay for the order
    • the payment form was opened, but there were errors during the payment
  • The response about the successful processing of the refund webhook has not been received.

It is recommended that the processing speed of the order_canceled webhook is less than 3 seconds.

Request
Request Body schema: application/json
notification_type
required
string

Notification type.

required
Array of objects

List of items purchased by the user.

Array
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. It can have the following values: virtual_good, virtual_currency, game_key, bundle. 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
Enum: "virtual_good" "virtual_currency" "game_key" "bundle"
quantity
required
integer

Quantity of items.

amount
required
string

Total cost of items based on their quantity. May differ from the item’s price due to currency rates and commission.

required
Array of objects

Applied promotions. If a promotion wasn’t applied, an empty array is passed in the parameter.

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 <json>

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

for real currency

virtual

for virtual currency

unknown

for a free order

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. If a promotion wasn’t applied, an empty array is passed in the parameter.

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.

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": "virtual-good-item_test",
        "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": "virtual-good-item_test_test_new",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "1000",
        "promotions": []
      },
      {
        "sku": "gold",
        "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"
    }

}'