Payment

PaymentWebhook POST

Sent whenever a user completes a payment. Includes payment details.

Request

Request Body schema: application/json

notification_type

required

string

Type of notification.

required

object

Transaction details (object).

id	integer Transaction ID.
external_id	string Transaction external ID.
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	integer <float> Amount.

object

Amount debited from the payment system.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.

object

Amount debited from Xsolla balance.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.

object

Payout details (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.

object

VAT details (object; EU only).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.
percent	integer <float> VAT rate.

payout_currency_rate

integer <float>

Exchange rate between payment and payout currencies.

object

Xsolla fee (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.

object

Payment system fee.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.

object

Sales tax (object; USA and Canada only).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.
percent	integer <float> Sales tax rate.

object

Direct withholding tax.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Amount.
percent	integer <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	integer <float> Amount.

object

Custom project settings (object).

project_id	integer Game’s Xsolla ID. Can be found in Publisher Account.
merchant_id	integer Merchant ID.

object

User details (object).

id required	string User ID.
ip	string User IP.
phone	string User phone.
email	string User email.
name	string Username
country	string User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
zip	string User’s ZIP or postal code.

object

Purchase details (object).

required

object

Total price of purchase (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Total payment amount.

object

Deprecated

Virtual currency to purchase (object).

name	string Deprecated Virtual currency name.
sku	string Deprecated Virtual currency package SKU (if set for the virtual currency package).
quantity	integer <float> Deprecated Quantity.
currency	string Deprecated Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Deprecated Price in real currency.

object

Checkout details (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	integer <float> Purchase 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	integer <float> Price in real currency.

object

Deprecated

Virtual items in purchase (object).

Array of objects

Deprecated

Array

sku	string Deprecated Item ID.
amount	integer <float> Deprecated Item quantity.

currency

string

Deprecated

Currency. Three-letter currency code per ISO 4217.

amount

integer <float>

Deprecated

Purchase amount.

object

Deprecated

Game keys (array).

digital_content

string

Deprecated

Game SKU set in Publisher Account.

drm

string

Deprecated

DRM platform used to distribute the game. Make sure that you have configured the required DRM platforms in your Publisher Account.

Enum: "steam" "playstation" "xbox" "uplay" "origin" "drmfree" "gog" "epicgames" "nintendo_eshop" "discord_game_store" "oculus"

currency

string

Deprecated

Currency. Three-letter currency code per ISO 4217.

amount

integer <float>

Deprecated

Price.

object

Deprecated

Object with upgrade data.

object

Deprecated

Object with data on the package, from which the user upgraded.

digital_content	string Deprecated Game SKU set in Publisher Account.
DRM	string Deprecated Game DRM platform.

object

Deprecated

Object with data on the package, to which the user upgraded.

digital_content	string Deprecated Game SKU set in Publisher Account.
DRM	string Deprecated Game DRM platform.

currency

string

Deprecated

Currency. Three-letter currency code per ISO 4217.

amount

integer <float>

Deprecated

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

Your custom parameters.

Responses

204

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.). In this case, the user’s money is debited, but the purchase fails. To make a refund, contact Xsolla customer support at support@xsolla.com.

500

Return to indicate temporary errors with your servers.

Request samples

Payload
CURL
PHP
HTTP

application/json

{"notification_type": "string",
"settings": {"project_id": 0,
"merchant_id": 0
},
"user": {"ip": "string",
"phone": "string",
"email": "string",
"id": "string",
"name": "string",
"country": "string",
"zip": "string"
},
"purchase": {"virtual_currency": {"name": "string",
"sku": "string",
"quantity": 0,
"currency": "string",
"amount": 0
},
"checkout": {"currency": "string",
"amount": 0
},
"subscription": {"plan_id": "string",
"subscription_id": 0,
"product_id": "string",
"tags": ["string"
],
"date_create": "string",
"date_next_charge": "string",
"currency": "string",
"amount": 0
},
"virtual_items": {"items": [{"sku": "string",
"amount": 0
}
],
"currency": "string",
"amount": 0
},
"pin_codes": {"digital_content": "string",
"drm": "steam",
"currency": "string",
"amount": 0,
"upgrade": {"digital_content_from": {"digital_content": "string",
"DRM": "string"
},
"digital_content_to": {"digital_content": "string",
"DRM": "string"
},
"currency": "string",
"amount": 0
}
},
"gift": {"giver_id": "string",
"receiver_id": "string",
"receiver_email": "string",
"message": "string",
"hide_giver_from_receiver": "string"
},
"total": {"currency": "string",
"amount": 0
},
"promotions": [{"technical_name": "string",
"id": 0
}
],
"coupon": {"coupon_code": "string",
"campaign_code": "string"
}
},
"transaction": {"id": 0,
"external_id": "string",
"payment_date": "string",
"payment_method": 0,
"payment_method_name": "string",
"payment_method_order_id": "string",
"dry_run": 0,
"agreement": 0
},
"payment_details": {"payment": {"currency": "string",
"amount": 0
},
"payment_method_sum": {"currency": "string",
"amount": 0
},
"xsolla_balance_sum": {"currency": "string",
"amount": 0
},
"payout": {"currency": "string",
"amount": 0
},
"vat": {"currency": "string",
"amount": 0,
"percent": 0
},
"payout_currency_rate": 0,
"xsolla_fee": {"currency": "string",
"amount": 0
},
"payment_method_fee": {"currency": "string",
"amount": 0
},
"sales_tax": {"currency": "string",
"amount": 0,
"percent": 0
},
"direct_wht": {"currency": "string",
"amount": 0,
"percent": 0
},
"repatriation_commission": {"currency": "string",
"amount": 0
}
},
"custom_parameters": { }
}

Response samples

application/json

{"error": {"code": "INVALID_USER",
"message": "Invalid user"
}
}