# Partial refund

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.

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 used1 —  the payment method was saved when making the current payment2 — the previously saved payment method is usedpayment_type:1 — one-time payment2 — 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 rejected because the payment system detected potential fraud.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.

Endpoint: POST partial-refund
Version: 1.0

## Request fields (application/json):

  - `notification_type` (string, required)
    Notification type.

  - `settings` (object)
    Custom project settings (object).

  - `settings.project_id` (integer)
    Project ID. You can find this parameter in your [Publisher Account](https://publisher.xsolla.com/) next to the name of the project.

  - `settings.merchant_id` (integer)
    Merchant ID.

  - `user` (object)
    User details (object).

  - `user.ip` (string)
    User IP.

  - `user.phone` (string)
    User phone.

  - `user.email` (string)
    User email.

  - `user.id` (string, required)
    User ID.

  - `user.name` (string)
    Username.

  - `user.country` (string)
    User’s country. Two-letter uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.

  - `user.zip` (string)
    User’s ZIP or postal code.

  - `purchase` (object)
    Purchase details (object).

  - `purchase.checkout` (object)
    Checkout details (object).

  - `purchase.checkout.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `purchase.checkout.amount` (number)
    Purchase amount.

  - `purchase.total` (object, required)
    Total price of purchase (object).

  - `purchase.total.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `purchase.total.amount` (number)
    Partial refund payment amount.

  - `transaction` (object, required)
    Transaction details (object).

  - `transaction.id` (integer)
    Transaction ID.

  - `transaction.external_id` (string)
    Transaction external ID.

  - `transaction.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.

  - `transaction.agreement` (integer)
    Agreement ID.

  - `transaction.date` (string)
    Date of transaction.

  - `refund_details` (object)
    Refund details (object).

  - `refund_details.code` (integer)
    Code ID.

  - `refund_details.reason` (string)
    Refund reason.

  - `refund_details.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

  - `refund_details.date` (string)
    Date of refund.

  - `payment_details` (object, required)
    Payment details (object).

  - `payment_details.payment` (object)
    Amount paid by the user (object).

  - `payment_details.payment.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.payment.amount` (number)
    Amount.

  - `payment_details.payment_method_sum` (object)
    Amount debited from the payment system.

  - `payment_details.payment_method_sum.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.payment_method_sum.amount` (number)
    Amount.

  - `payment_details.xsolla_balance_sum` (object)
    Amount debited from Xsolla balance.

  - `payment_details.xsolla_balance_sum.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.xsolla_balance_sum.amount` (number)
    Amount.

  - `payment_details.payout` (object)
    Payout details (object).

  - `payment_details.payout.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.payout.amount` (number)
    Amount.

  - `payment_details.vat` (object)
    VAT details (object; EU only).

  - `payment_details.vat.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.vat.amount` (number)
    Amount.

  - `payment_details.vat.percent` (number)
    VAT rate.

  - `payment_details.payout_currency_rate` (string)
    Exchange rate between payment and payout currencies.

  - `payment_details.xsolla_fee` (object)
    Xsolla fee (object).

  - `payment_details.xsolla_fee.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.xsolla_fee.amount` (number)
    Amount.

  - `payment_details.payment_method_fee` (object)
    Payment system fee.

  - `payment_details.payment_method_fee.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.payment_method_fee.amount` (number)
    Amount.

  - `payment_details.sales_tax` (object)
    Sales tax (object; USA and Canada only).

  - `payment_details.sales_tax.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.sales_tax.amount` (number)
    Amount.

  - `payment_details.sales_tax.percent` (number)
    Sales tax rate.

  - `payment_details.direct_wht` (object)
    Direct withholding tax.

  - `payment_details.direct_wht.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.direct_wht.amount` (number)
    Amount.

  - `payment_details.direct_wht.percent` (number)
    Direct withholding tax rate.

  - `payment_details.repatriation_commission` (object)
    Object with data on repatriation costs, imposed on Xsolla by third parties.

  - `payment_details.repatriation_commission.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `payment_details.repatriation_commission.amount` (number)
    Amount.

  - `custom_parameters` (object)
    Your custom parameters.

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (string)

  - `error.message` (string)


## Response 204 fields

## Response 500 fields