openapi: 3.0.0
info:
  description: >
    # Overview


    * **Version:** 2.0.0

    * **Servers**:
        * `https://getupdate.xsolla.com/`

    The Xsolla Event API is an alternative to using
    [webhooks](/webhooks/overview/#section/Overview). It allows you to receive
    information about payment events directly from your application's client via
    requests to Xsolla’s server. This approach eliminates the need to set up and
    maintain your own server for handling webhooks.


    **Interaction between your application and Xsolla:**


    ![Interaction between app and
    Xsolla](https://cdn.xsolla.net/developers/current/images/api_docs/event-api-scheme.svg)


    # Limitations

    When you use the Event API:

    * You **can’t** reject operations, e.g., payments — all events are
    automatically considered approved.

    * You **can’t** use webhooks — the Event API and webhooks are incompatible
    integration options.


    **Comparison of the main features:**


    <table>
      <tr>
        <th>Feature</th>
        <th>Webhooks</th>
        <th>Event API</th>
      </tr>
      <tr>
        <td>Request initiator</td>
        <td>Xsolla’s server.</td>
        <td>Your application’s client.</td>
      </tr>
      <tr>
        <td>Infrastructure</td>
        <td>You need your own server.</td>
        <td>You don’t need your own server.</td>
      </tr>
      <tr>
        <td>Event handling</td>
        <td>On your server.</td>
        <td>On your application’s client.</td>
      </tr>
      <tr>
        <td>Operation rejection</td>
        <td>Supported.</td>
        <td>Not supported (all events are automatically considered approved).</td>
      </tr>
    </table>


    # How to set it up


    <div class="note">
      <p><strong>Note</strong></p><p>To enable Event API in your project, contact your Customer Success Manager or email at csm@xsolla.com or integration@xsolla.com.</p>
    </div>


    1. In your project in Publisher Account, go to the [Settings > Integration
    settings](https://publisher.xsolla.com/0/projects/0/edit/advanced) section.

    2. Click **Use API**.

    3. In the modal window that opens, enter the project ID and click **Use
    API**.


    <div class="notice">
      <p><strong>Notice</strong></p><p>Switching to the events API will automatically disable previously configured webhooks, and they will no longer be sent to your server.</p>
    </div>


    ![Set up in Publisher
    Account](https://cdn.xsolla.net/developers/current/images/api_docs/event-api-publisher.png)


    <div class="note">
      <p><strong>Note</strong></p><p>The Xsolla Event API support is also available in the following Xsolla SDKs:<ul><li><a href="/sdk/mobile/mobile/sdk/configuration/android/#events">SDK for Android</a></li><li><a href="/sdk/mobile/mobile/sdk/configuration/ios/#using-xsolla-events-api-for-restoration">SDK for iOS</a></li><li><a href="/sdk/mobile/unity/sdk/configuration/#events">SDK for Unity</a></li></ul></p>
    </div>
  title: Xsolla event API
  version: '2.0'
servers:
  - url: https://getupdate.xsolla.com
tags:
  - name: events
    x-displayName: API calls
paths:
  /events:
    get:
      summary: Get unprocessed event list for user
      tags:
        - events
      operationId: get-event-list
      security:
        - XsollaLoginUserJWT: []
      parameters:
        - name: after_id
          in: query
          schema:
            type: integer
          description: Event ID after which the list is retrieved.
        - name: types
          in: query
          schema:
            type: array
            items:
              type: string
          description: Array of event types to filter.
        - name: token
          in: query
          schema:
            type: string
          description: |
            [Payment token](/api/pay-station/operation/create-token/).
            Used if you didn’t pass the user JWT token.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    description: Array containing event data.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Event ID.
                        status:
                          type: integer
                          description: Event status.
                        created_at:
                          type: string
                          format: date-time
                          description: Event date per ISO 8601.
                        data:
                          type: object
                          description: >-
                            Event body in the same format as the <a
                            href="/webhooks/operation/payment/">Payment</a>
                            webhook.
        '400':
          description: Data error.
        '401':
          description: Authorization error.
  /events/{event_id}/processed:
    post:
      summary: Mark event as processed
      tags:
        - events
      operationId: mark-event-processed
      security:
        - XsollaLoginUserJWT: []
      parameters:
        - name: event_id
          in: path
          schema:
            type: integer
          description: >-
            Value of the `events.id` parameter received in the **Get unprocessed
            event list for user** API call.
      responses:
        '200':
          description: OK.
        '400':
          description: Data error.
        '401':
          description: Authorization error.
        '404':
          description: Event not found.
components:
  securitySchemes:
    XsollaLoginUserJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        To authenticate requests, you can use the [user JWT
        token](/api/login/overview/#section/Authentication/Getting-a-user-token)
        obtained during authentication via Xsolla Login. The logic for
        identifying the user during a purchase depends on the calls used:

        * If you use client-side API calls, such as [Create order with specified
        item](/api/shop-builder/operation/create-order-with-item/), the user is
        automatically identified by the ID in the `sub` field of the JWT token.

        * If you use server-side API calls, such as [Create
        token](/api/pay-station/operation/create-token/), you need to pass the
        value of the `sub` field from the JWT token to the `user.id.value`
        parameter.


        Alternatively, to authenticate the request, you can pass the [payment
        token](/api/pay-station/operation/create-token/) to the `token` `GET`
        parameter.
