RefundWebhook POST
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
5xxstatus 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
4xxstatus code was returned, or no response was received after all retry attempts, or a5xxstatus 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:
|
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 Body schema: application/json
| 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
- PHP
- HTTP
curl -v 'https://your.hostname/your/uri' \ -X POST \ -d '{ "notification_type": "refund", "settings": { "project_id": 18404, "merchant_id": 2340 }, "purchase": { "virtual_currency": { "name": "Coins", "quantity": 10, "currency": "USD", "amount": 100 }, "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 }, "virtual_items": { "items": [ { "sku": "com.xsolla.item1", "amount": 1 } ], "currency": "USD", "amount": 50 }, "total":{ "currency": "USD", "amount": 200 } }, "user": { "ip": "127.0.0.1", "phone": "18777976552", "email": "email@example.com", "id": "1234567", "name": "Xsolla User", "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 } } } }'
- 400
{- "error": {
- "code": "INVALID_USER",
- "message": "Invalid user"
}
}