# Refund When a payment is canceled, Xsolla sends details of the canceled transaction in a webhook with the refund type to the webhook URL. The webhook retry mechanism depends on who initiated the refund: * If the refund was initiated on your side, the webhook isn’t resent. The payment is refunded to the user regardless of the response to a webhook. * If the refund was initiated by a third party — e.g., a payment system or Xsolla Customer Support team — and in response to a webhook, a 5xx status code was returned, the webhook is resent at increasing intervals. The maximum number of retries is 12 within 48 hours from the first attempt. For detailed information about the refund process, refer to the instructions. Notice The payment will still be refunded to the user if all of the following conditions are met:The refund was initiated by Xsolla.In response to a webhook, a 4xx status code was returned, or no response was received after all retry attempts, or a 5xx status code was returned. When you save the webhook URL in Publisher Account, you can also set up receiving additional information in webhooks. Note If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the Settings > Webhooks > Testing > Payments > Advanced settings section. Toggle Description Show info about transactions via saved payment methods Information is passed in the following custom parameters of the webhook:saved_payment_method:0 — the saved payment method was not used1 — the payment method was saved when making the current payment2 — the previously saved payment method is usedpayment_type:1 — one-time payment2 — recurring payment Refund codes: Code Reason Description 1 Cancellation by the user request / the game request Cancellation initiated from Publisher Account. 2 Chargeback Transaction chargeback requested. 3 Integration error Issues in integration between Xsolla and the game.Recommendation: Do not add the user to blocklist. 4 Potential fraud Fraud suspected.Recommendation: Add the user to blocklist. 5 Test payment Test transaction followed by cancellation.Recommendation: Do not add the user to blocklist. 6 User invoice expired Invoice overdue (used for postpaid model). 7 Fraud notification from PS Payment refused by payment system. Potential fraud detected by PS.Recommendation: Add the user to blocklist. 8 Cancellation by the PS request Cancellation requested by payment system.Recommendation: Do not add the user to blocklist. 9 Cancellation by the user request The user was not satisfied with the game or the purchase for any reason.Recommendation: Do not add the user to blocklist. 10 Cancellation by the game request Cancellation requested by the game.Recommendation: Do not add the user to blocklist. 11 Account holder called to report fraud The account owner states that they didn’t make the transaction. 12 Friendly fraud Friendly fraud reported. 13 Duplicate Duplicate transaction for the same invoice. Endpoint: POST refund Version: 1.0 ## Request fields (application/json): - `notification_type` (string, required) Notification type. - `settings` (object) Custom project settings (object). - `settings.project_id` (integer) Project ID. You can find this parameter in your [Publisher Account](https://publisher.xsolla.com/) next to the name of the project. - `settings.merchant_id` (integer) Merchant ID. - `user` (object) User details (object). - `user.ip` (string) User IP. - `user.phone` (string) User phone. - `user.email` (string) User email. - `user.id` (string, required) User ID. - `user.name` (string) Username. - `user.country` (string) User’s country. Two-letter uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. - `user.zip` (string) User’s ZIP or postal code. - `purchase` (object) Purchase details (object). - `purchase.checkout` (object) Checkout details (object). - `purchase.checkout.currency` (string) Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217). - `purchase.checkout.amount` (number) Purchase amount. - `purchase.subscription` (object) Subscription details (object). - `purchase.subscription.plan_id` (string) Plan ID (external if the plan was created via API). - `purchase.subscription.subscription_id` (integer) Subscription ID in Xsolla database. - `purchase.subscription.tags` (array) Plan tags. - `purchase.subscription.date_create` (string) Subscription creation date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). - `purchase.subscription.amount` (number) Price in real currency. - `purchase.total` (object, required) Total price of purchase (object). - `purchase.total.amount` (number) Total payment amount. - `transaction` (object, required) Transaction details (object). - `transaction.id` (integer) Transaction ID. - `transaction.external_id` (string) Transaction external ID. - `transaction.payment_method_order_id` (string) Payment ID in the payment system. - `transaction.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. - `transaction.agreement` (integer) Agreement ID. - `refund_details` (object) Refund details (object). - `refund_details.code` (integer) Code ID. - `refund_details.reason` (string) Refund reason. - `refund_details.author` (string) Refund initiator. The field value is passed according to the table: Refund initiator Field value Game (via API). API Publisher Account user (automatic refund). User email Publisher Account user (with assistance from Xsolla customer support). support@xsolla.com Xsolla (with assistance from Xsolla customer support). support@xsolla.com - `payment_details` (object, required) Payment details (object). - `payment_details.payment` (object) Amount paid by the user (object). - `payment_details.payment.amount` (number) Amount. - `payment_details.payment_method_sum` (object) Amount debited from the payment system. - `payment_details.xsolla_balance_sum` (object) Amount debited from Xsolla balance. - `payment_details.payout` (object) Payout details (object). - `payment_details.vat` (object) VAT details (object; EU only). - `payment_details.vat.percent` (number) VAT rate. - `payment_details.payout_currency_rate` (string) Exchange rate between payment and payout currencies. - `payment_details.country_wht` (object) Withholding tax applied in specific countries due to cross-border transactions (object). - `payment_details.country_wht.percent` (number) Country withholding tax rate, %. - `payment_details.user_acquisition_fee` (object) Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object). - `payment_details.user_acquisition_fee.percent` (number) User acquisition fee rate, %. - `payment_details.xsolla_fee` (object) Xsolla fee (object). - `payment_details.payment_method_fee` (object) Payment system fee. - `payment_details.sales_tax` (object) Sales tax (object; USA and Canada only). - `payment_details.sales_tax.percent` (number) Sales tax rate. - `payment_details.direct_wht` (object) Direct withholding tax. - `payment_details.direct_wht.percent` (number) Direct withholding tax rate. - `payment_details.repatriation_commission` (object) Object with data on repatriation costs, imposed on Xsolla by third parties. - `custom_parameters` (object) Your custom parameters. ## Response 400 fields (application/json): - `error` (object) - `error.code` (string) - `error.message` (string) ## Response 204 fields ## Response 500 fields