Xsolla-logoXsolla Developers
or
To Publisher Account

RefundWebhook POST

When a payment is canceled, Xsolla sends details of canceled transaction in a webhook with the refund type to the webhook URL. Learn more about the refund process in these instructions.

If a response with a 5xx code is received, Xsolla resends a webhook with an increased time interval until your listener confirms receiving. The maximum number of retries is 12.

Notice

If Xsolla initiates a refund and a response with a 5xx code is received for the webhook, the payment will still be refunded.

When you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the following toggle to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.

Note

If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Project 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 used
    • 1 — the payment method was saved when making the current payment
    • 2 — the previously saved payment method is used
  • payment_type:
    • 1 — one-time payment
    • 2 — 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.
Request
Request Body schema: application/json
notification_type
required
string

Notification type.

required
object

Transaction details (object).

id
integer

Transaction ID.

external_id
string

Transaction external ID.

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

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 ISO 3166-1 alpha-2 country code.

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
number <float>

Total payment amount.

object

Checkout details (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

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

tags
Array of strings

Plan tags.

date_create
string

Subscription creation 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

Refund details (object).

code
integer

Code ID.

reason
string

Refund reason.

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

500

Return to indicate temporary errors with your servers.

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "refund",
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "purchase": {
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "total":{
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1
        },
        "refund_details": {
            "code": 4,
            "reason": "Potential fraud"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": 10
            }
        }
    }
}'
Response samples
application/json
{
  • "error": {
    }
}
System statusAll services operational

Privacy Settings

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