Order cancellation

Order cancellationWebhook POST

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

The payment was canceled by the user, partner, or automatically.
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.

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
HTTP

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"
    }

}'