Xsolla-logo

Partial refundWebhook POST

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

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:

  • 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.
3 Integration error Issues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist.
5 Test payment Test transaction followed by cancellation.
Recommendation: Do not add the user to blocklist.
7 Fraud notification from PS Payment refused by payment system. Potential fraud detected by PS.
Recommendation: 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.
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.

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.

date
string

Date of transaction.

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

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>

Partial refund payment amount.

object

Checkout details (object).

currency
string

Currency. Three-letter currency code per ISO 4217.

amount
number <float>

Purchase amount.

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
date
string

Date of refund.

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": "partial_refund",
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "purchase": {
            "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,
            "date": "2022-03-01 10:53:15"
        },
        "refund_details": {
            "author": "email@example.com",
            "date": "2022-03-01 10:56:48"
        },
        "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–2024 Xsolla Inc.