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 following toggle to On in Publisher Account in the Project settings > Webhooks > Advanced settings section:
Toggle | Description |
---|---|
Show info about transactions via saved payment methods | Information is passed in the following custom parameters of the webhook:
|
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. |
notification_type required | string Notification type. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
required | object Transaction details (object). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
required | object Payment details (object). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Custom project settings (object). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object User details (object). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Purchase details (object). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Refund details (object). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_parameters | object Your custom parameters. |
Return to indicate successful processing.
Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.).
Return to indicate temporary errors with your servers.
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 } } } }'
{- "error": {
- "code": "INVALID_USER",
- "message": "Invalid user"
}
}