Xsolla-logo

Successful payment of the orderWebhook POST

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

  1. The user successfully paid for the order.
  2. 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.

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.

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_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"
          },
      },
      {
        "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": "gc_user@xsolla.com"
    }

}'
System statusAll services operational

Privacy Settings

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