Xsolla-logo

Successful payment for order (with payment and transaction details)Webhook POST

Xsolla sends the order_paid webhook to the specified URL when the user successfully pays for the order.

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

The order_paid webhook is not sent if the payment is 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

It is recommended that the processing time 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 refund functionality, the webhook processing logic on Xsolla’s side is as follows:

Response code Automatic payment refund is disabled (by default) Automatic payment refund 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, contact your Customer Success Managers or email to csm@xsolla.com.

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

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

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.

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. Refer to the FAQs for detailed information.

payment_date
string

Date of payment.

payment_method
integer

Payment method ID.

payment_method_name
string

Payment method name.

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.

product_id
string

Product ID (if sent in the access token).

tags
Array of strings

Plan tags.

date_create
string

Subscription creation date. Date and time per ISO 8601.

date_next_charge
string

Next billing 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

Gift details (object).

giver_id
string

Giver ID.

receiver_id
string

Gift recipient ID.

receiver_email
string

Gift recipient email.

message
string

Message from the giver.

hide_giver_from_receiver
string

Whether to hide the giver identity from the recipient.

Array of objects

Promotions applied to this transaction.

Array
technical_name
string

Technical name of the promotion.

id
integer

Promotion ID.

object

Coupon details (object; if a coupon was used when creating the subscription).

coupon_code
string

Coupon code.

campaign_code
string

Campaign code.

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": "com.xsolla.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.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": "gc_user@xsolla.com"
    },
    "billing": {
      "notification_type": "payment",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "purchase": {
          "subscription": {
              "plan_id": "b5dac9c8",
              "subscription_id": "10",
              "product_id": "Demo Product",
              "date_create": "2014-09-22T19:25:25+04:00",
              "date_next_charge": "2014-10-22T19:25:25+04:00",
              "currency": "USD",
              "amount": 9.99
          },
          "total": {
              "currency": "USD",
              "amount": 200
          },
          "promotions": [{
              "technical_name": "Demo Promotion",
              "id": 853
          }],
          "coupon": {
              "coupon_code": "ICvj45S4FUOyy",
              "campaign_code": "1507"
          },
      "transaction": {
          "id": 1,
          "external_id": 1,
          "payment_date": "2014-09-24T20:38:16+04:00",
          "payment_method": 1,
          "payment_method_name": "PayPal",
          "payment_method_order_id": 1234567890123456789,
          "dry_run": 1,
          "agreement": 1
      },
      "payment_details": {
          "payment": {
              "currency": "USD",
              "amount": 230
          },
          "vat": {
              "currency": "USD",
              "amount": 0,
              "percent": 20
          },
          "sales_tax": {
              "currency": "USD",
              "amount": 0,
              "percent": 0
          },
          "direct_wht": {
              "currency": "USD",
              "amount": 0,
              "percent": 0
          },
          "payout_currency_rate": "1",
          "payout": {
              "currency": "USD",
              "amount": 200
          },
          "country_wht": {
              "currency": "USD",
              "amount": 2,
              "percent": 10
          },
          "user_acquisition_fee": {
              "currency": "USD",
              "amount": 2,
              "percent": 1
          },
          "xsolla_fee": {
              "currency": "USD",
              "amount": 10
          },
          "payment_method_fee": {
              "currency": "USD",
              "amount": 20
          },
          "repatriation_commission": {
              "currency": "USD",
              "amount": 10
          }
      },
      "custom_parameters": {
          "parameter1": "value1",
          "parameter2": "value2"
          }
      }
   }
}'
System statusAll services operational

Privacy Settings

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