openapi: 3.1.0
info:
  description: >
    # Overview


    Webhooks allow you to receive instant notifications of configured events
    that happen on Xsolla’s side. You can use webhooks to automate back-end and
    supplementary functions of your application.


    Examples of events that you can be notified about:


    - payments, including purchases of virtual currency and items

    - recurring payments and actions with subscriptions

    - refunds


    When a configured event occurs, Xsolla notifies your system about it via
    webhooks. For example, you can do the following after receiving a webhook:


    - add to a user’s balance

    - unlock new items for a user

    - start subscription service

    - block user after fraud detection


    Below is an example of how a payment processing webhook works:


    ![Payment processing
    webhook](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)


    # Set up server side


    The following settings have to be applied for webhooks to work correctly:


    - Listen to webhooks at the following IP addresses: `185.30.20.0/24`,
    `185.30.21.0/24`, `185.30.23.0/24`.

    - Application database must not contain two successful transactions with the
    same ID.


    <div lang="en" class="notice">
      <p><strong>Notice</strong></p>
      <p>If your listener receives a webhook with an existing transaction ID, it must return the previous result for that transaction. It is not recommended to charge the user twice or create duplicate records in the database.</p>
    </div>


    - A created
    [signature](https://developers.xsolla.com/webhooks/overview/#section/Sign-requests)
    has to match the one passed in the HTTP header.

    - In case of an error, return [code
    400](https://developers.xsolla.com/webhooks/overview/#section/Errors) (e.g.,
    when a required parameter is missing or a recharge has failed). For
    temporary errors with your servers, use code 500.


    <div lang="en" class="note">
      <p><strong>Note</strong></p>
      <p>Xsolla API accepts conventional HTTP response codes for successful and failed requests. Code 204 indicates successful processing.</p>
    </div>


    As internet connections are not always 100% reliable, webhooks may be lost
    or delayed. To address this issue, Xsolla resends failed webhooks until your
    listener receives them. Webhook resends are sent within 12 hours after the
    previous one until your listener confirms receiving. The maximum number of
    retries is 12.


    <div lang="en" class="note">
      <p><strong>Note</strong></p>
      <p>Although connection problems may result in lost, delayed, or duplicate webhooks, the most common cause is incorrect logic on the listener side.</p>
    </div>


    # Sign requests


    Digital signatures enable secure data transmission. To generate a signature:


    1. Concatenate the request’s JSON body with your project’s secret key.

    2. Apply SHA-1 hashing to the resulting string.


    ```

    POST /your_uri HTTP/1.1

    host: your.host

    accept: application/json

    content-type: application/json

    content-length: 165

    authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

    {
      "notification_type":"user_validation",
      "user":{
          "ip":"127.0.0.1",
          "phone":"18777976552",
          "email":"email@example.com",
          "id":1234567,
          "name":"Xsolla User",
          "country":"US"
      }
    }

    ```


    ```

    curl -v 'https://your.hostname/your/uri' \

    -X POST \

    -H 'authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \

    -d '{
      "notification_type":
        "user_validation",
        "user":
          {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": 1234567,
            "name": "Xsolla User",
            "country": "US"
          }
        }'
    ```


    # Errors


    Error codes for HTTP code 400:


    <table>
      <thead>
        <tr>
            <th>Code</th>
            <th>Message</th>
        </tr>
      </thead>
      <tbody>
        <tr>
            <td>INVALID_USER</td>
            <td>Invalid user</td>
        </tr>
        <tr>
            <td>INVALID_PARAMETER</td>
            <td>Invalid parameter</td>
        </tr>
        <tr>
            <td>INVALID_SIGNATURE</td>
            <td>Invalid signature</td>
        </tr>
        <tr>
            <td>INCORRECT_AMOUNT</td>
            <td>Incorrect amount</td>
        </tr>
        <tr>
            <td>INCORRECT_INVOICE</td>
            <td>Incorrect invoice</td>
        </tr>
      </tbody>
    </table>


    ```

    HTTP/1.1 400 Bad Request

    {
        "error":{
            "code":"INVALID_USER",
            "message":"Invalid user"
        }
    }

    ```
  title: Webhooks
  version: '1.0'
servers:
  - url: https://api.xsolla.com/merchant/v2
tags:
  - name: webhooks
    x-displayName: Webhooks
webhooks:
  payment:
    post:
      summary: Payment
      description: Sent whenever a user completes a payment. Includes payment details.
      operationId: legacy-payment
      requestBody:
        content:
          application/json:
            schema:
              required:
                - notification_type
                - transaction
                - payment_details
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    country:
                      $ref: '#/components/schemas/user.country'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                purchase:
                  type: object
                  description: Purchase details (object).
                  required:
                    - total
                  properties:
                    virtual_currency:
                      deprecated: true
                      type: object
                      description: Virtual currency to purchase (object).
                      properties:
                        name:
                          deprecated: true
                          type: string
                          description: Virtual currency name.
                        sku:
                          deprecated: true
                          type: string
                          description: >-
                            Virtual currency package SKU (if set for the virtual
                            currency package).
                        quantity:
                          deprecated: true
                          type: number
                          format: float
                          description: Quantity.
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          $ref: '#/components/schemas/amount-float'
                    checkout:
                      type: object
                      description: Checkout details (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Purchase amount.
                    subscription:
                      type: object
                      description: Subscription details (object).
                      properties:
                        plan_id:
                          $ref: '#/components/schemas/subscription.plan_id'
                        subscription_id:
                          $ref: '#/components/schemas/subscription.subscription_id'
                        product_id:
                          type: string
                          description: Product ID (if sent in the access token).
                        tags:
                          $ref: '#/components/schemas/subscription.tags'
                        date_create:
                          $ref: '#/components/schemas/subscription.date_create'
                        date_next_charge:
                          type: string
                          description: >-
                            Next billing date. Date and time per [ISO
                            8601](https://en.wikipedia.org/wiki/ISO_8601).
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          $ref: '#/components/schemas/amount-float'
                    virtual_items:
                      deprecated: true
                      type: object
                      description: Virtual items in purchase (object).
                      properties:
                        items:
                          deprecated: true
                          type: array
                          items:
                            type: object
                            deprecated: true
                            properties:
                              sku:
                                deprecated: true
                                type: string
                                description: Item ID.
                              amount:
                                deprecated: true
                                type: number
                                format: float
                                description: Item quantity.
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          type: number
                          format: float
                          description: Purchase amount.
                    pin_codes:
                      deprecated: true
                      type: object
                      description: Game keys (array).
                      properties:
                        digital_content:
                          deprecated: true
                          type: string
                          description: Game SKU set in Publisher Account.
                        drm:
                          deprecated: true
                          type: string
                          description: >-
                            DRM platform used to distribute the game. Make sure
                            that you have configured the required DRM platforms
                            in your Publisher Account.
                          enum:
                            - steam
                            - playstation
                            - xbox
                            - uplay
                            - origin
                            - drmfree
                            - gog
                            - epicgames
                            - nintendo_eshop
                            - discord_game_store
                            - oculus
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          type: number
                          format: float
                          description: Price.
                        upgrade:
                          deprecated: true
                          type: object
                          description: Object with upgrade data.
                          properties:
                            digital_content_from:
                              deprecated: true
                              type: object
                              description: >-
                                Object with data on the package, from which the
                                user upgraded.
                              properties:
                                digital_content:
                                  deprecated: true
                                  type: string
                                  description: Game SKU set in Publisher Account.
                                DRM:
                                  deprecated: true
                                  type: string
                                  description: Game DRM platform.
                            digital_content_to:
                              deprecated: true
                              type: object
                              description: >-
                                Object with data on the package, to which the
                                user upgraded.
                              properties:
                                digital_content:
                                  deprecated: true
                                  type: string
                                  description: Game SKU set in Publisher Account.
                                DRM:
                                  deprecated: true
                                  type: string
                                  description: Game DRM platform.
                            currency:
                              deprecated: true
                              $ref: '#/components/schemas/currency'
                            amount:
                              deprecated: true
                              $ref: '#/components/schemas/amount-float'
                    gift:
                      type: object
                      description: Gift details (object).
                      properties:
                        giver_id:
                          type: string
                          description: Giver ID.
                        receiver_id:
                          type: string
                          description: Gift recipient ID.
                        receiver_email:
                          type: string
                          description: Gift recipient email.
                        message:
                          type: string
                          description: Message from the giver.
                        hide_giver_from_receiver:
                          type: string
                          description: >-
                            Whether to hide the giver identity from the
                            recipient.
                    total:
                      type: object
                      description: Total price of purchase (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Total payment amount.
                    promotions:
                      type: array
                      description: Promotions applied to this transaction.
                      items:
                        type: object
                        properties:
                          technical_name:
                            type: string
                            description: Technical name of the promotion.
                          id:
                            type: integer
                            description: Promotion ID.
                    coupon:
                      type: object
                      description: >-
                        Coupon details (object; if a coupon was used when
                        creating the subscription).
                      properties:
                        coupon_code:
                          type: string
                          description: Coupon code.
                        campaign_code:
                          type: string
                          description: Campaign code.
                    order:
                      type: object
                      description: >-
                        Object that contains information about an order. This
                        information is not passed in the webhook by default. To
                        enable this function, contact your Account Manager or
                        email to am@xsolla.com.
                      properties:
                        id:
                          type: integer
                          description: Order ID.
                        lineitems:
                          type: object
                          description: Object that contains information about an item.
                          properties:
                            sku:
                              type: string
                              description: Item SKU.
                            quantity:
                              type: integer
                              description: Item quantity.
                            price:
                              type: object
                              description: >-
                                Object that contains information about an item
                                price.
                              properties:
                                currency:
                                  type: string
                                  description: Currency of the item price.
                                amount:
                                  type: number
                                  format: float
                                  description: >-
                                    Total price of the item in the selected
                                    currency.
                transaction:
                  type: object
                  description: Transaction details (object).
                  properties:
                    id:
                      type: integer
                      description: Transaction ID.
                    external_id:
                      type: string
                      description: Transaction external ID.
                    payment_date:
                      type: string
                      description: Date of payment.
                    payment_method:
                      type: integer
                      description: Payment method ID.
                    payment_method_name:
                      type: string
                      description: Payment method name.
                    payment_method_order_id:
                      type: string
                      description: Payment ID in the payment system.
                    dry_run:
                      type: integer
                      description: >-
                        Test transaction. The parameter has the 1 value if it is
                        a test transaction, or is not sent if the transaction is
                        real.
                    agreement:
                      type: integer
                      description: Agreement ID.
                payment_details:
                  type: object
                  description: Payment details (object).
                  properties:
                    payment:
                      type: object
                      description: Amount paid by the user (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payment_method_sum:
                      type: object
                      description: Amount debited from the payment system.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    xsolla_balance_sum:
                      type: object
                      description: Amount debited from Xsolla balance.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payout:
                      type: object
                      description: Payout details (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    vat:
                      type: object
                      description: VAT details (object; EU only).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: VAT rate.
                    payout_currency_rate:
                      type: string
                      description: Exchange rate between payment and payout currencies.
                    xsolla_fee:
                      type: object
                      description: Xsolla fee (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payment_method_fee:
                      type: object
                      description: Payment system fee.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    sales_tax:
                      type: object
                      description: Sales tax (object; USA and Canada only).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: Sales tax rate.
                    direct_wht:
                      type: object
                      description: Direct withholding tax.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: Direct withholding tax rate.
                    repatriation_commission:
                      type: object
                      description: >-
                        Object with data on repatriation costs, imposed on
                        Xsolla by third parties.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                custom_parameters:
                  type: object
                  description: Your custom parameters.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400-payment'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: |
            curl -v 'https://your.hostname/your/uri' \
            -X POST \
            -d '{
                "notification_type": "payment",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase": {
                    "virtual_currency": {
                        "name": "Coins",
                        "sku": "com.xsolla.package1",
                        "quantity": 10,
                        "currency": "USD",
                        "amount": 100
                    },
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "date_next_charge": "2014-10-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
                    },
                    "promotions": [{
                        "technical_name": "Demo Promotion",
                        "id": "853"
                    }],
                    "coupon": {
                        "coupon_code": "ICvj45S4FUOyy",
                        "campaign_code": "1507"
                    },
                    "order": {
                      "id": 1234
                      "lineitems": [
                      {
                        "sku": "com.xsolla.item_1",
                        "quantity": 1,
                        "price": {
                          "currency": "EUR",
                          "amount": 6.5
                          }
                      }
                      ]
                      }
                },
                "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,
                    "payment_date": "2014-09-24T20:38:16+04:00",
                    "payment_method": 1,
                    "payment_method_name": "PayPal",
                    "payment_method_order_id": 1234567890123456789,
                    "dry_run": 1,
                    "agreement": 1
                },
                "payment_details": {
                    "payment": {
                        "currency": "USD",
                        "amount": 230
                    },
                    "vat": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 20
                    },
                    "sales_tax": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "direct_wht": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "payout_currency_rate": 1,
                    "payout": {
                        "currency": "USD",
                        "amount": 200
                    },
                    "xsolla_fee": {
                        "currency": "USD",
                        "amount": 10
                    },
                    "payment_method_fee": {
                        "currency": "USD",
                        "amount": 20
                    },
                    "repatriation_commission": {
                        "currency": "USD",
                        "amount": 10
                    }
                },
                "custom_parameters": {
                    "parameter1": "value1",
                    "parameter2": "value2"
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'payment',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'purchase' => array(
                    'virtual_currency' => array(
                        'name' => 'Coins',
                        'quantity' => 100,
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'total' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    )
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email' => 'email@example.com',
                    'id' => '1234567',
                    'country' => 'US'
                ),
                'transaction' => array(
                    'id' => 87654321,
                    'payment_date' => '2014-09-23T19:25:25+04:00',
                    'payment_method' => 1380,
                    'payment_method_name' => 'PayPal'
                    'payment_method_order_id' => 1234567890123456789,
                    'dry_run' => 1
                ),
                'payment_details' => array(
                    'payment' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'vat' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'sales_tax' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'direct_wht' => array(
                        'currency' => 'USD',
                        'amount' => 70
                    ),
                    'payout_currency_rate' => 1,
                    'payout' => array(
                        'currency' => 'USD',
                        'amount' => 9.49
                    ),
                    'xsolla_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.19
                    ),
                    'payment_method_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.31
                    ),
                    'repatriation_commission' => array(
                        'currency' => 'USD',
                        'amount' => 0.2
                    )
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1721
            authorization: Signature 34553d151e656110c656696c919f9a10e05de542

            {
                "notification_type": "payment",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase":{
                    "virtual_currency": {
                        "name": "Coins",
                        "sku": "com.xsolla.package1",
                        "quantity": 10,
                        "currency": "USD",
                        "amount": 100
                    },
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "date_next_charge": "2014-10-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
                    },
                    "promotions": [{
                        "technical_name": "Demo Promotion",
                        "id": "853"
                    }],
                    "coupon": {
                        "coupon_code": "ICvj45S4FUOyy",
                        "campaign_code": "1507"
                    },
                    "order": {
                      "id": 1234
                      "lineitems": [
                      {
                        "sku": "com.xsolla.item_1",
                        "quantity": 1,
                        "price": {
                          "currency": "EUR",
                          "amount": 6.5
                          }
                      }
                      ]
                      }
                },
                "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,
                    "payment_date": "2014-09-24T20:38:16+04:00",
                    "payment_method": 1,
                    "payment_method_name": "PayPal"
                    "payment_method_order_id": 1234567890123456789,
                    "dry_run": 1,
                    "agreement": 1
                },
                "payment_details": {
                    "payment": {
                        "currency": "USD",
                        "amount": 230
                    },
                    "vat": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 20
                    },
                    "sales_tax": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "direct_wht": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "payout_currency_rate": 1,
                    "payout": {
                        "currency": "USD",
                        "amount": 200
                    },
                    "xsolla_fee": {
                        "currency": "USD",
                        "amount": 10
                    },
                    "payment_method_fee": {
                        "currency": "USD",
                        "amount": 20
                    },
                    "repatriation_commission": {
                        "currency": "USD",
                        "amount": 10
                    }
                },
                "custom_parameters": {
                    "parameter1": "value1",
                    "parameter2": "value2"
                }
            }
  refund:
    post:
      summary: Refund
      description: >
        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 `5xx`
        status 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](/doc/pay-station/features/refund/).


        <div lang="en" class="notice">
          <p><strong>Notice</strong></p>
          <p>The payment will still be refunded to the user if all of the following conditions are met:<ul><li>The refund was initiated by Xsolla.</li><li>In response to a webhook, a <code>4xx</code> status code was returned, or no response was received after all retry attempts, or a <code>5xx</code> status code was returned.</li></ul></p>
        </div>


        When you save the webhook URL in <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Publisher
        Account</a>, you can also set up receiving additional information in
        webhooks.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Show info about transactions via saved payment methods</td>
                <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>
            </tr>
          </tbody>
        </table>


        Refund codes:


        <table>
            <thead>
            <tr>
                <th>Code</th>
                <th>Reason</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td>1</td>
                <td>Cancellation by the user request / the game request</td>
                <td>Cancellation initiated from Publisher Account.</td>
            </tr>
            <tr>
                <td>2</td>
                <td>Chargeback</td>
                <td>Transaction chargeback requested.</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Integration error</td>
                <td>Issues in integration between Xsolla and the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>4</td>
                <td>Potential fraud</td>
                <td>Fraud suspected.<br/><b>Recommendation: Add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>5</td>
                <td>Test payment</td>
                <td>Test transaction followed by cancellation.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>6</td>
                <td>User invoice expired</td>
                <td>Invoice overdue (used for postpaid model).</td>
            </tr>
            <tr>
                <td>7</td>
                <td>Fraud notification from PS</td>
                <td>Payment refused by payment system. Potential fraud detected by PS.<br/><b>Recommendation: Add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>8</td>
                <td>Cancellation by the PS request</td>
                <td>Cancellation requested by payment system.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>9</td>
                <td>Cancellation by the user request</td>
                <td>The user was not satisfied with the game or the purchase for any reason.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>10</td>
                <td>Cancellation by the game request</td>
                <td>Cancellation requested by the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>11</td>
                <td>Account holder called to report fraud</td>
                <td>The account owner states that they didn’t make the transaction.</td>
            </tr>
            <tr>
                <td>12</td>
                <td>Friendly fraud</td>
                <td>Friendly fraud reported.</td>
            </tr>
            <tr>
                <td>13</td>
                <td>Duplicate</td>
                <td>Duplicate transaction for the same invoice.</td>
            </tr>
            </tbody>
        </table>
      operationId: legacy-refund
      requestBody:
        content:
          application/json:
            schema:
              required:
                - notification_type
                - transaction
                - payment_details
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    country:
                      $ref: '#/components/schemas/user.country'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                purchase:
                  type: object
                  description: Purchase details (object).
                  required:
                    - total
                  properties:
                    virtual_currency:
                      type: object
                      deprecated: true
                      description: Virtual currency to purchase (object).
                      properties:
                        name:
                          deprecated: true
                          type: string
                          description: Virtual currency name.
                        quantity:
                          deprecated: true
                          type: number
                          format: float
                          description: Quantity.
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          $ref: '#/components/schemas/amount-float'
                    checkout:
                      type: object
                      description: Checkout details (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Purchase amount.
                    subscription:
                      type: object
                      description: Subscription details (object).
                      properties:
                        plan_id:
                          $ref: '#/components/schemas/subscription.plan_id'
                        subscription_id:
                          $ref: '#/components/schemas/subscription.subscription_id'
                        tags:
                          $ref: '#/components/schemas/subscription.tags'
                        date_create:
                          $ref: '#/components/schemas/subscription.date_create'
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          $ref: '#/components/schemas/amount-float'
                    virtual_items:
                      type: object
                      deprecated: true
                      description: Virtual items in purchase (object).
                      properties:
                        items:
                          deprecated: true
                          type: array
                          items:
                            type: object
                            properties:
                              sku:
                                deprecated: true
                                type: string
                                description: Item ID.
                              amount:
                                deprecated: true
                                type: number
                                format: float
                                description: Item quantity.
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          type: number
                          format: float
                          description: Purchase amount.
                    pin_codes:
                      type: object
                      deprecated: true
                      description: Game keys (array).
                      properties:
                        upgrade:
                          type: object
                          description: Object with upgrade data.
                          properties:
                            digital_content_from:
                              type: object
                              deprecated: true
                              description: >-
                                Object with data on the package, from which the
                                user upgraded.
                              properties:
                                digital_content:
                                  deprecated: true
                                  type: string
                                  description: Game SKU set in Publisher Account.
                                DRM:
                                  deprecated: true
                                  type: string
                                  description: Game DRM platform.
                            digital_content_to:
                              type: object
                              deprecated: true
                              description: >-
                                Object with data on the package, to which the
                                user upgraded.
                              properties:
                                digital_content:
                                  deprecated: true
                                  type: string
                                  description: Game SKU set in Publisher Account.
                                DRM:
                                  deprecated: true
                                  type: string
                                  description: Game DRM platform.
                            currency:
                              deprecated: true
                              $ref: '#/components/schemas/currency'
                            amount:
                              deprecated: true
                              $ref: '#/components/schemas/amount-float'
                    total:
                      type: object
                      description: Total price of purchase (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Total payment amount.
                transaction:
                  type: object
                  description: Transaction details (object).
                  properties:
                    id:
                      type: integer
                      description: Transaction ID.
                    external_id:
                      type: string
                      description: Transaction external ID.
                    payment_method_order_id:
                      type: string
                      description: Payment ID in the payment system.
                    dry_run:
                      type: integer
                      description: >-
                        Test transaction. The parameter has the 1 value if it is
                        a test transaction, or is not sent if the transaction is
                        real.
                    agreement:
                      type: integer
                      description: Agreement ID.
                refund_details:
                  type: object
                  description: Refund details (object).
                  properties:
                    code:
                      type: integer
                      description: Code ID.
                    reason:
                      type: string
                      description: Refund reason.
                    author:
                      type: string
                      description: >
                        Refund initiator. The field value is passed according to
                        the table:


                        <table>
                            <thead>
                            <tr>
                                <th>Refund initiator</th>
                                <th>Field value</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>Game (via API).</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (automatic refund).</td>
                                <td>User email</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>Xsolla (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                payment_details:
                  type: object
                  description: Payment details (object).
                  properties:
                    payment:
                      type: object
                      description: Amount paid by the user (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payment_method_sum:
                      type: object
                      description: Amount debited from the payment system.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    xsolla_balance_sum:
                      type: object
                      description: Amount debited from Xsolla balance.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payout:
                      type: object
                      description: Payout details (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    vat:
                      type: object
                      description: VAT details (object; EU only).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: VAT rate.
                    payout_currency_rate:
                      type: string
                      description: Exchange rate between payment and payout currencies.
                    xsolla_fee:
                      type: object
                      description: Xsolla fee (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payment_method_fee:
                      type: object
                      description: Payment system fee.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    sales_tax:
                      type: object
                      description: Sales tax (object; USA and Canada only).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: Sales tax rate.
                    direct_wht:
                      type: object
                      description: Direct withholding tax.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: Direct withholding tax rate.
                    repatriation_commission:
                      type: object
                      description: >-
                        Object with data on repatriation costs, imposed on
                        Xsolla by third parties.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                custom_parameters:
                  type: object
                  description: Your custom parameters.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: |
            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
                        }
                    }
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'refund',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'purchase' => array(
                    'virtual_currency' => array(
                        'name' => 'Coins',
                        'quantity' => 100,
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'total' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    )
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email' => 'email@example.com',
                    'id' => '1234567',
                    'country' => 'US'
                ),
                'transaction' => array(
                    'id' => 87654321,
                    'payment_date' => '2014-09-23T19:25:25+04:00',
                    'payment_method' => 1380,
                    'dry_run' => 1
                ),
                'refund_details' => array(
                        'code' => 4,
                        'reason' => 'Potential fraud'
                ),
                'payment_details' => array(
                    'payment' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'vat' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'sales_tax' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'direct_wht' => array(
                        'currency' => 'USD',
                        'amount' => 70
                    ),
                    'payout_currency_rate' => 1,
                    'payout' => array(
                        'currency' => 'USD',
                        'amount' => 9.49
                    ),
                    'xsolla_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.19
                    ),
                    'payment_method_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.31
                    ),
                    'repatriation_commission' => array(
                        'currency' => 'USD',
                        'amount' => 0.2
                    )
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1220
            authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

            {
                "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
                    }
                }
            }
  partial-refund:
    post:
      summary: Partial refund
      description: >
        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](/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow).


        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 <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Project
        settings &gt; Webhooks &gt; Advanced settings</a> section.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Show info about transactions via saved payment methods</td>
                <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>
            </tr>
          </tbody>
        </table>


        Refund codes:


        <table>
            <thead>
            <tr>
                <th>Code</th>
                <th>Reason</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td>1</td>
                <td>Cancellation by the user request / the game request</td>
                <td>Cancellation initiated from Publisher Account.</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Integration error</td>
                <td>Issues in integration between Xsolla and the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>5</td>
                <td>Test payment</td>
                <td>Test transaction followed by cancellation.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>7</td>
                <td>Fraud notification from PS</td>
                <td>Payment refused by payment system. Potential fraud detected by PS.<br/><b>Recommendation: Add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>9</td>
                <td>Cancellation by the user request</td>
                <td>The user was not satisfied with the game or the purchase for any reason.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>10</td>
                <td>Cancellation by the game request</td>
                <td>Cancellation requested by the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            </tbody>
        </table>
      operationId: legacy-partial-refund
      requestBody:
        content:
          application/json:
            schema:
              required:
                - notification_type
                - transaction
                - payment_details
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    country:
                      $ref: '#/components/schemas/user.country'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                purchase:
                  type: object
                  description: Purchase details (object).
                  required:
                    - total
                  properties:
                    virtual_currency:
                      type: object
                      deprecated: true
                      description: Virtual currency to purchase (object).
                      properties:
                        name:
                          deprecated: true
                          type: string
                          description: Virtual currency name.
                        quantity:
                          deprecated: true
                          type: number
                          format: float
                          description: Quantity.
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          $ref: '#/components/schemas/amount-float'
                    checkout:
                      type: object
                      description: Checkout details (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Purchase amount.
                    virtual_items:
                      type: object
                      deprecated: true
                      description: Virtual items in purchase (object).
                      properties:
                        items:
                          deprecated: true
                          type: array
                          items:
                            type: object
                            properties:
                              sku:
                                deprecated: true
                                type: string
                                description: Item ID.
                              amount:
                                deprecated: true
                                type: number
                                format: float
                                description: Item quantity.
                        currency:
                          deprecated: true
                          $ref: '#/components/schemas/currency'
                        amount:
                          deprecated: true
                          type: number
                          format: float
                          description: Purchase amount.
                    pin_codes:
                      type: object
                      deprecated: true
                      description: Game keys (array).
                      properties:
                        upgrade:
                          type: object
                          description: Object with upgrade data.
                          properties:
                            digital_content_from:
                              type: object
                              deprecated: true
                              description: >-
                                Object with data on the package, from which the
                                user upgraded.
                              properties:
                                digital_content:
                                  deprecated: true
                                  type: string
                                  description: Game SKU set in Publisher Account.
                                DRM:
                                  deprecated: true
                                  type: string
                                  description: Game DRM platform.
                            digital_content_to:
                              type: object
                              deprecated: true
                              description: >-
                                Object with data on the package, to which the
                                user upgraded.
                              properties:
                                digital_content:
                                  deprecated: true
                                  type: string
                                  description: Game SKU set in Publisher Account.
                                DRM:
                                  deprecated: true
                                  type: string
                                  description: Game DRM platform.
                            currency:
                              deprecated: true
                              $ref: '#/components/schemas/currency'
                            amount:
                              deprecated: true
                              $ref: '#/components/schemas/amount-float'
                    total:
                      type: object
                      description: Total price of purchase (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Partial refund payment amount.
                transaction:
                  type: object
                  description: Transaction details (object).
                  properties:
                    id:
                      type: integer
                      description: Transaction ID.
                    external_id:
                      type: string
                      description: Transaction external ID.
                    dry_run:
                      type: integer
                      description: >-
                        Test transaction. The parameter has the 1 value if it is
                        a test transaction, or is not sent if the transaction is
                        real.
                    agreement:
                      type: integer
                      description: Agreement ID.
                    date:
                      type: string
                      description: Date of transaction.
                refund_details:
                  type: object
                  description: Refund details (object).
                  properties:
                    code:
                      type: integer
                      description: Code ID.
                    reason:
                      type: string
                      description: Refund reason.
                    author:
                      type: string
                      description: >
                        Refund initiator. The field value is passed according to
                        the table:


                        <table>
                            <thead>
                            <tr>
                                <th>Refund initiator</th>
                                <th>Field value</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>Game (via API).</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (automatic refund).</td>
                                <td>User email</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>Xsolla (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                    date:
                      type: string
                      description: Date of refund.
                payment_details:
                  type: object
                  description: Payment details (object).
                  properties:
                    payment:
                      type: object
                      description: Amount paid by the user (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payment_method_sum:
                      type: object
                      description: Amount debited from the payment system.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    xsolla_balance_sum:
                      type: object
                      description: Amount debited from Xsolla balance.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payout:
                      type: object
                      description: Payout details (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    vat:
                      type: object
                      description: VAT details (object; EU only).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: VAT rate.
                    payout_currency_rate:
                      type: string
                      description: Exchange rate between payment and payout currencies.
                    xsolla_fee:
                      type: object
                      description: Xsolla fee (object).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    payment_method_fee:
                      type: object
                      description: Payment system fee.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                    sales_tax:
                      type: object
                      description: Sales tax (object; USA and Canada only).
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: Sales tax rate.
                    direct_wht:
                      type: object
                      description: Direct withholding tax.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                        percent:
                          type: number
                          format: float
                          description: Direct withholding tax rate.
                    repatriation_commission:
                      type: object
                      description: >-
                        Object with data on repatriation costs, imposed on
                        Xsolla by third parties.
                      properties:
                        currency:
                          $ref: '#/components/schemas/currency'
                        amount:
                          type: number
                          format: float
                          description: Amount.
                custom_parameters:
                  type: object
                  description: Your custom parameters.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: |
            curl -v 'https://your.hostname/your/uri' \
            -X POST \
            -d '{
                    "notification_type": "partial_refund",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "purchase": {
                        "virtual_currency": {
                            "name": "Coins",
                            "quantity": 10,
                            "currency": "USD",
                            "amount": 100
                        },
                        "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,
                        "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
                        }
                    }
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'partial_refund',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'purchase' => array(
                    'virtual_currency' => array(
                        'name' => 'Coins',
                        'quantity' => 100,
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'total' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    )
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email' => 'email@example.com',
                    'id' => '1234567',
                    'country' => 'US'
                ),
                'transaction' => array(
                    'id' => 87654321,
                    'payment_date' => '2014-09-23T19:25:25+04:00',
                    'payment_method' => 1380,
                    'dry_run' => 1,
                    'date' => '2022-03-31 10:53:15'
                ),
                'refund_details' => array(
                        'author' => 'email@example.com',
                        'date' => '2022-03-01 10:56:48'
                ),
                'payment_details' => array(
                    'payment' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'vat' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'sales_tax' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'direct_wht' => array(
                        'currency' => 'USD',
                        'amount' => 70
                    ),
                    'payout_currency_rate' => 1,
                    'payout' => array(
                        'currency' => 'USD',
                        'amount' => 9.49
                    ),
                    'xsolla_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.19
                    ),
                    'payment_method_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.31
                    ),
                    'repatriation_commission' => array(
                        'currency' => 'USD',
                        'amount' => 0.2
                    )
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1220
            authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

            {
                "notification_type": "partial_refund",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase": {
                    "virtual_currency": {
                        "name": "Coins",
                        "quantity": 10,
                        "currency": "USD",
                        "amount": 100
                    },
                    "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,
                    "date": "2022-03-31 10:53:15"
                },
                "refund_details": {
                    "author": "email@example.com",
                    "date": "2022-03-31 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
                    }
                }
            }
  get-game-keys:
    post:
      summary: Get game keys
      description: >-
        We will be making API calls to your server to obtain game activation
        codes after each successful payment.
      operationId: get-game-keys
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                pin_code:
                  type: object
                  description: Game keys details (object).
                  properties:
                    digital_content:
                      type: string
                      description: Game SKU.
                    DRM:
                      type: string
                      description: DRM platform used to distribute the game.
      responses:
        '200':
          description: Return the game key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pin_code:
                    type: string
              example:
                pin_code: AAA-BBB-CCC-DDD
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "notification_type": "get_pincode",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "user": {
                        "id": "1234567",
                        "name": "Xsolla User"
                    },
                    "pin_code": {
                        "digital_content": "Game SKU",
                        "DRM": "Steam"
                    }
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array (
                  'notification_type' => 'get_pincode',
                  'settings' => array(
                      'project_id' => 18404,
                      'merchant_id' => 2340
                  ),
                  'user' =>
                      array (
                          'id' => '1234567',
                          'name' => 'Xsolla User',
                      ),
                  'pin_code' =>
                      array (
                          'digital_content' => 'Game SKU',
                          'DRM' => 'Steam',
                      ),
              );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "get_pincode",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "id": "1234567",
                    "name": "Xsolla User"
                },
                "pin_code": {
                    "digital_content": "Game SKU",
                    "DRM": "Steam"
                }
            }
  activate-key:
    post:
      summary: Activate key
      description: >-
        When a user activates a key, Xsolla sends a notification to your webhook
        URL.
      operationId: activate-key
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                key:
                  type: string
                  description: Activation key.
                sku:
                  type: string
                  description: Unique key package ID.
                user_id:
                  $ref: '#/components/schemas/user.id'
                activation_date:
                  type: string
                  format: datetime
                  description: >-
                    Key activation date in the **YYYYMMDDHHMMSS** format per
                    [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
                user_country:
                  $ref: '#/components/schemas/user.country'
                restriction:
                  type: object
                  description: >-
                    Object with regional restriction cluster settings. The
                    cluster includes a restriction type and a list of countries,
                    servers and locales for which the game is available.
                  properties:
                    sku:
                      type: string
                      description: Unique cluster ID.
                    name:
                      type: string
                      description: Cluster name.
                    types:
                      type: array
                      items:
                        type: string
                      description: Array of restriction types.
                    countries:
                      type: array
                      items:
                        type: string
                      description: Array of countries in the cluster.
                    servers:
                      type: array
                      items:
                        type: string
                      description: Array of game servers.
                    locales:
                      type: array
                      items:
                        type: string
                      description: Array of locales.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
              "notification_type": "redeem_key",
              "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
              },
              "key": "wqdqwwddq9099022",
              "sku": "com.xsolla.key_123",
              "user_id": "sample_user",
              "activation_date": "2018-11-20T08:38:51+03:00",
              "user_country": "EN",
              "restriction": {
                  "name": "cls_1",
                  "types": [
                      "activation"
                    ],
                    "countries": [
                        "RU"
                    ]
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'redeem_key',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'key' => ‘wqdqwwddq9099022’,
                'sku' => com.xsolla.key_123,
                'user_id' => ‘sample_user’,
                'activation_date' => ‘2018-11-20T08:38:51+03:00’,
                'user_country' => ‘EN’,
                'restriction' =>
                      array(
                            'name' => ‘cls_1’,
                            'types' =>
                                    array(
                                        ‘activation’
                                    ),
                            'countries' =>
                                    array(
                                        ‘RU’
                                    ),
                        ),
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 165
            authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

            {
              "notification_type": "redeem_key",
              "settings": {
                "project_id": 18404,
                "merchant_id": 2340
              },
              "key": "wqdqwwddq9099022",
              "sku": "com.xsolla.key_123",
              "user_id": "sample_user",
              "activation_date": "2018-11-20T08:38:51+03:00",
              "user_country": "EN",
              "restriction": {
                  "name": "cls_1",
                  "types": [
                      "activation"
                    ],
                    "countries": [
                        "RU"
                    ]
              }
            }
  user-balance-payment:
    post:
      summary: 'User balance: Payment'
      description: Sent whenever a user makes a payment.
      operationId: user-balance-payment
      requestBody:
        content:
          application/json:
            schema:
              required:
                - transaction
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                operation_type:
                  type: string
                  description: Type of operation.
                id_operation:
                  type: integer
                  description: Operation ID in Xsolla database.
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    email:
                      $ref: '#/components/schemas/user.email'
                virtual_currency_balance:
                  type: object
                  description: User balance data (object).
                  properties:
                    old_value:
                      type: string
                      description: Balance before transaction.
                    new_value:
                      type: string
                      description: Balance after transaction.
                    diff:
                      type: string
                      description: Quantity of virtual currency in the purchase.
                transaction:
                  type: object
                  description: Transaction details (object).
                  properties:
                    id:
                      type: integer
                      description: Transaction ID.
                    date:
                      type: string
                      description: Date of transaction.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "virtual_currency_balance": {
                        "old_value": "0",
                        "new_value": "200",
                        "diff": "200"
                    },
                    "user": {
                        "name": "Xsolla User",
                        "id": "1234567",
                        "email": "email@example.com"
                    },
                    "transaction": {
                        "id": "123456789",
                        "date": "2015-05-19T15:54:40+03:00"
                    },
                    "operation_type": "payment",
                    "notification_type": "user_balance_operation",
                    "id_operation": "66989"
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'settings' => array(
                    'project_id' => 18404,
                    'merchant_id' => 2340
                ),
                'virtual_currency_balance' => array(
                    'old_value' => '0',
                    'new_value' => '200',
                    'diff' => '200'
                ),
                'user' => array(
                    'name' => 'Xsolla User',
                    'id' => '1234567',
                    'email' => 'email@example.com'
                ),
                'transaction' => array(
                    'id' => '123456789',
                    'date' => '2015-05-19T15:54:40+03:00'
                ),
                'operation_type' => 'payment',
                'notification_type' => 'user_balance_operation',
                'id_operation' => '66989'
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                },
                "virtual_currency_balance": {
                    "old_value": "0",
                    "new_value": "200",
                    "diff": "200"
                },
                "user": {
                    "name": "Xsolla User",
                    "id": "1234567",
                    "email": "email@example.com"
                },
                "transaction": {
                    "id": "123456789",
                    "date": "2015-05-19T15:54:40+03:00"
                },
                "operation_type": "payment",
                "notification_type": "user_balance_operation",
                "id_operation": "66989"
            }
  user-balance-purchase:
    post:
      summary: 'User balance: Purchase'
      description: >-
        Sent when a user purchases something inside the game. Specifies the
        change in the user’s balance.
      operationId: user-balance-purchase
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                operation_type:
                  type: string
                  description: Type of operation.
                id_operation:
                  type: integer
                  description: Operation ID in Xsolla database.
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    email:
                      $ref: '#/components/schemas/user.email'
                virtual_currency_balance:
                  type: object
                  description: User balance data (object).
                  properties:
                    old_value:
                      type: string
                      description: Balance before transaction.
                    new_value:
                      type: string
                      description: Balance after transaction.
                    diff:
                      type: string
                      description: Quantity of virtual currency in the purchase.
                items_operation_type:
                  type: string
                  description: Type of operation made with virtual items.
                items:
                  type: array
                  description: Virtual items within the purchase.
                  items:
                    type: object
                    properties:
                      sku:
                        type: string
                        description: Item ID.
                      amount:
                        type: integer
                        description: Item quantity.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "settings": {
                        "project_id": 18404,
                        "merchant_id": 2340
                    },
                    "virtual_currency_balance": {
                        "old_value": "0",
                        "new_value": "200",
                        "diff": "200"
                    },
                    "user": {
                        "name": "Xsolla User",
                        "id": "1234567",
                        "email": "email@example.com"
                    },
                    "operation_type": "inGamePurchase",
                    "notification_type": "user_balance_operation",
                    "items_operation_type": "add",
                        "items": [{
                        "sku": "com.xsolla.item_1468",
                        "amount": "2"
                        }],
                    "id_operation": "66989"
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'settings' => array(
                        'project_id' => 18404,
                        'merchant_id' => 2340
                ),
                'virtual_currency_balance' => array(
                        'old_value' => '0',
                        'new_value' => '200',
                        'diff' => '200'
                ),
                'user' => array(
                    'name' => 'Xsolla User',
                    'id' => '1234567',
                    'email' => 'email@example.com'
                ),
                'operation_type' => 'inGamePurchase',
                'notification_type' => 'user_balance_operation',
                'items_operation_type' =>  'add',
                    'items' =>  array(
                        'sku' =>  'com.xsolla.item_1468',
                        'amount' =>  '2'
                    ),
                'id_operation' => '66989'
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                },
                "virtual_currency_balance": {
                    "old_value": "0",
                    "new_value": "200",
                    "diff": "200"
                },
                "user": {
                    "name": "Xsolla User",
                    "id": "1234567",
                    "email": "email@example.com"
                },
                "operation_type": "inGamePurchase",
                "notification_type": "user_balance_operation",
                "items_operation_type": "add",
                    "items": [{
                    "sku": "com.xsolla.item_1468",
                    "amount": "2"
                    }],
                "id_operation": "66989"
            }
  user-balance-redeem-coupon:
    post:
      summary: 'User balance: Redeem coupon'
      description: >-
        Sent when a user redeems a coupon to receive virtual items or virtual
        currency.
      operationId: user-balance-redeem-coupon
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                operation_type:
                  type: string
                  description: Type of operation.
                id_operation:
                  type: integer
                  description: Operation ID in Xsolla database.
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    email:
                      $ref: '#/components/schemas/user.email'
                virtual_currency_balance:
                  type: object
                  description: User balance data (object).
                  properties:
                    old_value:
                      type: string
                      description: Balance before transaction.
                    new_value:
                      type: string
                      description: Balance after transaction.
                    diff:
                      type: string
                      description: Quantity of virtual currency in the purchase.
                items_operation_type:
                  type: string
                  description: Type of operation made with virtual items.
                items:
                  type: array
                  description: Virtual items within the purchase.
                  items:
                    type: object
                  properties:
                    sku:
                      type: string
                      description: Item ID.
                    amount:
                      type: integer
                      description: Item quantity.
                coupon:
                  type: object
                  description: Coupon details (object).
                  properties:
                    coupon_code:
                      type: string
                      description: Coupon code.
                    campaign_code:
                      type: string
                      description: Campaign code.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "settings": {
                        "project_id": 18404,
                        "merchant_id": 2340
                    },
                    "virtual_currency_balance": {
                        "old_value": "0",
                        "new_value": "0",
                        "diff": "0"
                    },
                    "user": {
                        "name": "Xsolla User",
                        "id": "1234567",
                        "email": "email@example.com"
                    },
                    "operation_type": "coupon",
                    "notification_type": "user_balance_operation",
                    "items_operation_type": "add",
                        "items": [{
                            "sku": "com.xsolla.item_1468",
                            "amount": "2"
                        }],
                    "id_operation": "66989",
                    "coupon": {
                        "coupon_code": "test123",
                        "campaign_code": "Xsolla Campaign"
                    }
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'settings' => array(
                    'project_id' => 18404,
                    'merchant_id' => 2340
                ),
                'virtual_currency_balance' => array(
                    'old_value' => '0',
                    'new_value' => '0',
                    'diff' => '0'
                ),
                'user' => array(
                    'name' => 'Xsolla User',
                    'id' => '1234567',
                    'email' => 'email@example.com'
                ),
                'operation_type' => 'coupon',
                'notification_type' => 'user_balance_operation',
                'items_operation_type' =>  'add',
                    'items' =>  array(
                        'sku' =>  'com.xsolla.item_1468',
                        'amount' =>  '2'
                    ),
                'id_operation' => '66989',
                'coupon' =>  array(
                    'coupon_code' =>  'test123',
                    'campaign_code' =>  'Xsolla Campaign'
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                },
                "virtual_currency_balance": {
                    "old_value": "0",
                    "new_value": "0",
                    "diff": "0"
                },
                "user": {
                    "name": "Xsolla User",
                    "id": "1234567",
                    "email": "email@example.com"
                },
                "operation_type": "coupon",
                "notification_type": "user_balance_operation",
                "items_operation_type": "add",
                    "items": [{
                        "sku": "com.xsolla.item_1468",
                        "amount": "2"
                    }],
                "id_operation": "66989",
                "coupon": {
                    "coupon_code": "test123",
                    "campaign_code": "Xsolla Campaign"
                }
            }
  user-balance-manual-update:
    post:
      summary: 'User balance: Manual update'
      description: Sent when a user’s balance is changed manually.
      operationId: user-balance-manual-update
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                operation_type:
                  type: string
                  description: Type of operation.
                id_operation:
                  type: integer
                  description: Operation ID in Xsolla database.
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    email:
                      $ref: '#/components/schemas/user.email'
                virtual_currency_balance:
                  type: object
                  description: User balance data (object).
                  properties:
                    old_value:
                      type: string
                      description: Balance before transaction.
                    new_value:
                      type: string
                      description: Balance after transaction.
                    diff:
                      type: string
                      description: Quantity of virtual currency in the purchase.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "virtual_currency_balance": {
                        "old_value": "0",
                        "new_value": "100",
                        "diff": "100"
                    },
                    "user": {
                        "name": "Xsolla User",
                        "id": "1234567",
                        "email": "email@example.com"
                    },
                    "operation_type": "internal",
                    "notification_type": "user_balance_operation",
                    "id_operation": "67002"
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'settings' => array(
                    'project_id' => 18404,
                    'merchant_id' => 2340
                ),
                'virtual_currency_balance' => array(
                    'old_value' => '0',
                    'new_value' => '100',
                    'diff' => '100'
                ),
                'user' => array(
                    'name' => 'Xsolla User',
                    'id' => '1234567',
                    'email' => 'email@example.com'
                ),
                'operation_type' => 'internal',
                'notification_type' => 'user_balance_operation',
                'id_operation' => '67002'
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                },
                "virtual_currency_balance": {
                    "old_value": "0",
                    "new_value": "100",
                    "diff": "100"
                },
                "user": {
                    "name": "Xsolla User",
                    "id": "1234567",
                    "email": "email@example.com"
                },
                "operation_type": "internal",
                "notification_type": "user_balance_operation",
                "id_operation": "67002"
            }
  user-balance-refund:
    post:
      summary: 'User balance: Refund'
      description: >-
        Sent when a user cancels a payment. Specifies the change in the user’s
        balance.
      operationId: user-balance-refund
      requestBody:
        content:
          application/json:
            schema:
              required:
                - transaction
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  type: object
                  description: Custom project settings (object).
                  properties:
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                operation_type:
                  type: string
                  description: Type of operation.
                id_operation:
                  type: integer
                  description: Operation ID in Xsolla database.
                user:
                  type: object
                  description: User details (object).
                  required:
                    - id
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    email:
                      $ref: '#/components/schemas/user.email'
                virtual_currency_balance:
                  type: object
                  description: User balance data (object).
                  properties:
                    old_value:
                      type: string
                      description: Balance before transaction.
                    new_value:
                      type: string
                      description: Balance after transaction.
                    diff:
                      type: string
                      description: Quantity of virtual currency in the purchase.
                transaction:
                  type: object
                  description: Transaction details (object).
                  properties:
                    id:
                      type: integer
                      description: Transaction ID.
                    date:
                      type: string
                      description: Date of transaction.
                items_operation_type:
                  type: string
                  description: Type of operation made with virtual items.
                items:
                  type: array
                  description: Virtual items within the purchase.
                  items:
                    type: object
                    properties:
                      sku:
                        type: string
                        description: Item ID.
                      amount:
                        type: integer
                        description: Item quantity.
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CURL
          source: >
            curl -v 'https://your.hostname/your/uri' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "virtual_currency_balance": {
                        "old_value": "0",
                        "new_value": "0",
                        "diff": "0"
                    },
                    "user": {
                        "name": "Xsolla User",
                        "id": "1234567",
                        "email": "email@example.com"
                    },
                    "transaction": {
                        "id": "123456789",
                        "date": "2015-05-19T15:54:40+03:00"
                    },
                    "operation_type": "cancellation",
                    "notification_type": "user_balance_operation",
                    "items_operation_type": "remove",
                        "items": [{
                            "sku": "com.xsolla.item_1468",
                            "amount": "2"
                        }],
                    "id_operation": "66989"
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'settings' => array(
                    'project_id' => 18404,
                    'merchant_id' => 2340
                ),
                'virtual_currency_balance' => array(
                    'old_value' => '0',
                    'new_value' => '0',
                    'diff' => '0'
                ),
                'user' => array(
                    'name' => 'Xsolla User',
                    'id' => '1234567',
                    'email' => 'email@example.com'
                ),
                'transaction' => array(
                    'id' => '123456789',
                    'date' => '2015-05-19T15:54:40+03:00'
                ),
                'operation_type' => 'cancellation',
                'notification_type' => 'user_balance_operation',
                'items_operation_type' =>  'remove',
                    'items' =>  array(
                        'sku' =>  'com.xsolla.item_1468',
                        'amount' =>  '2'
                    ),
                'id_operation' => '66989'
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                },
                "virtual_currency_balance": {
                    "old_value": "0",
                    "new_value": "0",
                    "diff": "0"
                },
                "user": {
                    "name": "Xsolla User",
                    "id": "1234567",
                    "email": "email@example.com"
                },
                "transaction": {
                    "id": "123456789",
                    "date": "2015-05-19T15:54:40+03:00"
                },
                "operation_type": "cancellation",
                "notification_type": "user_balance_operation",
                "items_operation_type": "remove",
                    "items": [{
                        "sku": "com.xsolla.item_1468",
                        "amount": "2"
                    }],
                "id_operation": "66989"
            }
components:
  schemas:
    notification_type:
      type: string
      description: Notification type.
    settings.project_id:
      type: integer
      description: >-
        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:
      type: integer
      description: Merchant ID.
    user.ip:
      type: string
      description: User IP.
    user.phone:
      type: string
      description: User phone.
    user.email:
      type: string
      description: User email.
    user.id:
      type: string
      description: User ID.
    user.name:
      type: string
      description: Username.
    user.country:
      type: string
      description: >-
        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:
      type: string
      description: User’s ZIP or postal code.
    currency:
      type: string
      description: >-
        Currency. Three-letter currency code per [ISO
        4217](https://en.wikipedia.org/wiki/ISO_4217).
    amount-float:
      type: number
      format: float
      description: Price in real currency.
    subscription.plan_id:
      type: string
      description: Plan ID (external if the plan was created via API).
    subscription.subscription_id:
      type: integer
      description: Subscription ID in Xsolla database.
    subscription.tags:
      type: array
      items:
        type: string
      description: Plan tags.
    subscription.date_create:
      type: string
      description: >-
        Subscription creation date. Date and time per [ISO
        8601](https://en.wikipedia.org/wiki/ISO_8601).
  responses:
    '204':
      description: Return to indicate successful processing.
    '400':
      description: >-
        Return in case of an error in the provided information (e.g., a required
        parameter missing, failed authorization, etc.).
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
      x-examples:
        application/json:
          INVALID_USER:
            summary: Invalid user
            value:
              error:
                code: INVALID_USER
                message: Invalid user
          INVALID_PARAMETER:
            summary: Invalid parameter
            value:
              error:
                code: INVALID_PARAMETER
                message: Invalid parameter
          INVALID_SIGNATURE:
            summary: Invalid signature
            value:
              error:
                code: INVALID_SIGNATURE
                message: Invalid signature
          INCORRECT_AMOUNT:
            summary: Incorrect amount
            value:
              error:
                code: INCORRECT_AMOUNT
                message: Incorrect amount
          INCORRECT_INVOICE:
            summary: Incorrect invoice
            value:
              error:
                code: INCORRECT_INVOICE
                message: Incorrect invoice
    '500':
      description: Return to indicate temporary errors with your servers.
    400-payment:
      description: >-
        Return in case of an error in the provided information (e.g., a required
        parameter missing, failed authorization, etc.). In this case, the user’s
        money is debited, but the purchase fails. To make a refund, contact
        Xsolla customer support at support@xsolla.com.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
      x-examples:
        application/json:
          INVALID_USER:
            summary: Invalid user
            value:
              error:
                code: INVALID_USER
                message: Invalid user
          INVALID_PARAMETER:
            summary: Invalid parameter
            value:
              error:
                code: INVALID_PARAMETER
                message: Invalid parameter
          INVALID_SIGNATURE:
            summary: Invalid signature
            value:
              error:
                code: INVALID_SIGNATURE
                message: Invalid signature
          INCORRECT_AMOUNT:
            summary: Incorrect amount
            value:
              error:
                code: INCORRECT_AMOUNT
                message: Incorrect amount
          INCORRECT_INVOICE:
            summary: Incorrect invoice
            value:
              error:
                code: INCORRECT_INVOICE
                message: Incorrect invoice
