Refund

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.

You can give permissions to receive detailed information in webhooks. To do that, you can set the Show info about transactions via saved payment methods toggle On in Publisher Account in the Project settings > Webhooks > Advanced settings section.

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	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 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	integer <float> Total payment amount.

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.
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	integer <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
PHP
HTTP

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": {"code": "INVALID_USER",
"message": "Invalid user"
}
}