Successful payment of the order

Successful payment of the orderWebhook POST

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

The user successfully paid for the order.
Xsolla received a response about the successful processing of payment webhook.

The order_paid webhook contains information about the purchased items and transaction details.

The order_paid 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 payment webhook has not been received.

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

The expected answers are described in the Responses section. You can use other response codes. Depending on the response code and the connection of the automatic payment return functionality, the webhook processing logic on Xsolla’s side is as follows:

Response code	Automatic payment return is disabled (by default)	Automatic payment return is enabled
`400`, `401`, `402`, `403`, `404`, `409`, `422`, `415`	No actions	Automatic refund to the user
`200`, `201`, `204`	No actions	No actions
Different code or no response to webhook	Multiple webhooks are sent within a specified time interval: 2 attempts with a 5-minute interval, 7 attempts with a 15-minute interval, 10 attempts with a 60-minute interval.	Multiple webhooks are sent within a specified time interval: 2 attempts with a 5-minute interval, 7 attempts with a 15-minute interval, 10 attempts with a 60-minute interval. If all webhooks are sent but a successful response is not received, an automatic refund is issued to the user.

To connect the automatic refund functionality, please contact the project account manager or write to am@xsolla.com.

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.

is_free

required

boolean

If true, the item is free or belongs to a bundle.

is_bonus

required

boolean

If true, the item is a bonus.

is_bundle_content

required

boolean

If true, the item belongs to a bundle.

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.

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_paid",
    "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"
          },
        "is_free": false,
        "is_bonus": false,
        "is_bundle_content": false
      },
      {
        "sku": "virtual-good-item_test_test_new",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "1000",
        "promotions": [],
        "is_free": false,
        "is_bonus": false,
        "is_bundle_content": false
      },
      {
        "sku": "gold",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 1500,
        "amount": "[null]",
        "promotions": [],
        "is_free": true,
        "is_bonus": false,
        "is_bundle_content": true
      }
    ],
    "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": "gc_user@xsolla.com"
    }

}'