openapi: 3.0.0
info:
  description: >
    # Overview


    * **Version:** 2.0.0

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

    Pay Station allows partners to monetize their products by providing users
    with a convenient UI to pay for in-game purchases in the game store. To set
    up opening the payment UI, refer to these
    [instructions](/doc/pay-station/how-to/how-to-open-payment-ui/).


    The Pay Station API provides the following groups of calls:

    - Token — includes the API call to generate a token with arbitrary user
    parameters for further payment processing via the payment UI.

    - [Tokenization](/doc/pay-station/features/tokenization/) —  includes API
    calls to securely process payments without opening the payment UI or
    involving the user.

    - Reports —  includes API calls to return data on user transactions,
    generate reports, and get payouts breakdown by currency.

    - Refund —  includes API calls to request full and partial refunds.

    - Testing —  includes the API call to test the chargeback process.


    You can find detailed information about configuring the payment UI in the
    [Payments solution integration
    guide](/solutions/payments/integration-guide/integration-flow/).


    <div class="note">
      <p><strong>Note</strong></p><p>You can also refer to the <b>Xsolla Base API</b> section in the <a href="https://github.com/xsolla/xsolla-postman">Postman collection</a> to test API calls used for integration.</p>
    </div>
  title: Pay Station API
  version: '2.0'
servers:
  - url: https://api.xsolla.com/merchant/v2
tags:
  - name: token
    x-displayName: Token
  - name: tokenization
    x-displayName: Tokenization
  - name: reports
    x-displayName: Reports
  - name: refund
    x-displayName: Refund
  - name: testing
    x-displayName: Testing
paths:
  /merchants/{merchant_id}/token:
    post:
      summary: Create token
      description: >
        You can create a token with arbitrary user parameters. You send these

        parameters when obtaining the token and receive them back after a
        successful

        payment. A token can only contain parameters either described in this

        document or predefined by you.


        If any parameter is sent in the wrong format or has the wrong type, no
        token

        will be issued. You will receive a 422 HTTP code with the error
        description

        in the JSON body. In `extended_message` you will receive an information
        what

        exact parameters have been sent incorrectly.


        By default, the token lifetime is 24 hours. If you want to change this
        value, contact your Customer Success Manager or send an email to <a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>. The new value will be
        enabled for all your company’s projects created in <a
        href="https://publisher.xsolla.com/">Publisher Account</a>.


        <div class="notice">
          <p><strong>Notice</strong></p><p>The token you obtain after calling this API method can be used only for authorizing other requests. You can use this token to open the payment UI only if you integrated the <a href="https://developers.xsolla.com/doc/subscriptions/">Subscriptions</a> product.</p><p>To open the payment UI in a new window, use the following link: <code>https://secure.xsolla.com/paystation4/?token={token}</code>, where <code>{token}</code> is the received token.</p><p>For testing purposes, use this URL: <code>https://sandbox-secure.xsolla.com/paystation4/?token={token}</code>.</p>
        </div>


        <p></p>


        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - token
      operationId: create-token
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token'
      responses:
        '200':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
              example:
                token: eop57k1boA7nnYPtewZ6KEXJyJADEwRT
        '422':
          description: Unprocessable Entity.
          content:
            application/json:
              schema:
                type: object
                properties:
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  extended_message:
                    type: object
                    properties:
                      global_errors:
                        type: array
                        items:
                          type: string
                      property_errors:
                        type: object
                        description: >-
                          Object contains parameter names with error
                          descriptions.
                  request_id:
                    type: string
              example:
                http_status_code: 422
                message: >-
                  JSON is not valid against json schema, please check
                  documentation
                  https://developers.xsolla.com/api/v2/getting-started/#api_token_ui
                extended_message:
                  global_errors: []
                  property_errors:
                    purchase.checkout.amount:
                      - String value found, but a number is required
                request_id: cd72633
  /projects/{project_id}/users/{user_id}/payment_accounts:
    get:
      summary: Get saved accounts
      description: |
        Lists saved payment accounts of a given user.

        <div class="note">
          <p><strong>Note</strong></p><p>In sandbox mode, this API call works only with <a href="https://developers.xsolla.com/doc/pay-station/testing/test-cards/">test cards</a> that have no 3-D Secure function.</p>
        </div>
      tags:
        - tokenization
      operationId: get-saved-accounts
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/project-id-path-param'
        - $ref: '#/components/parameters/user-id-path-param'
        - $ref: '#/components/parameters/mode'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              example:
                - id: 4612345
                  name: PP_saved_account
                  payment_system:
                    id: 24
                    name: PayPal
                  type: paypal
  /projects/{project_id}/users/{user_id}/payments/{type}/{account_id}:
    post:
      summary: Charge with saved account
      description: |
        Charges a user via a saved payment account.

        <div class="note">
          <p><strong>Note</strong></p><p>In sandbox mode, this API call works only with <a href="https://developers.xsolla.com/doc/pay-station/testing/test-cards/">test cards</a> that have no 3-D Secure function.</p>
        </div>

        <p></p>

        <div class="notice">
          <p><strong>Notice</strong></p><p>For the API call to work correctly, configure a timeout of 2 minutes.</p>
        </div>
      tags:
        - tokenization
      operationId: charge-with-saved-account
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/project-id-path-param'
        - $ref: '#/components/parameters/user-id-path-param'
        - $ref: '#/components/parameters/type-path-param'
        - $ref: '#/components/parameters/account-id-path-param'
      requestBody:
        $ref: '#/components/requestBodies/charge-with-saved-account'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction_id:
                    type: integer
              example:
                transaction_id: 123458390
        '422':
          description: Unprocessable Entity.
  /projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}:
    delete:
      summary: Delete saved account
      description: |
        Deletes a saved payment account.

        <div class="note">
          <p><strong>Note</strong></p><p>In sandbox mode, this API call works only with <a href="https://developers.xsolla.com/doc/pay-station/testing/test-cards/">test cards</a> that have no 3-D Secure function.</p>
        </div>

        <p></p>

        <div class="note">
          <p><strong>Note</strong></p><p>You can call this API method in sandbox mode. To do this, pass the test payment account data in the request. Refer to the <a href="https://developers.xsolla.com/doc/pay-station/testing/test-saved-cards-in-sandbox/#pay_station_testing_tokenization_sandbox_delete_saved_card">instruction</a> for more information about sandbox mode access and testing scenarios.</p>
        </div>
      tags:
        - tokenization
      operationId: delete-saved-account
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/project-id-path-param'
        - $ref: '#/components/parameters/user-id-path-param'
        - $ref: '#/components/parameters/type-path-param'
        - $ref: '#/components/parameters/account-id-path-param'
      responses:
        '204':
          description: No Content.
  /merchants/{merchant_id}/reports/transactions/search.{format}:
    get:
      summary: Find transactions
      description: >
        Returns a list of transactions based on specific search parameters. In
        response, you get data about all payments made in your game, even if
        they were not completed successfully. You can specify not only the
        transaction period, but also other parameters, e.g., to search for
        transactions made by a particular user or in a particular payment
        status. You can get the list in JSON or CSV format.


        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: find-transactions
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/datetime-from'
        - $ref: '#/components/parameters/datetime-to'
        - $ref: '#/components/parameters/project-id-query-param'
        - $ref: '#/components/parameters/transaction-id'
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/phone'
        - $ref: '#/components/parameters/user-id-query-param'
        - $ref: '#/components/parameters/user-name'
        - $ref: '#/components/parameters/user-custom'
        - $ref: '#/components/parameters/email'
        - $ref: '#/components/parameters/external-id'
        - $ref: '#/components/parameters/order-id'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/status'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              example:
                - transaction:
                    project:
                      id: 123456
                      name: Example
                    payment_method:
                      id: 1
                      name: PayPal
                    transfer_date: '2021-10-20'
                    id: 123456789
                    refund_reason: null
                    status: done
                    external_id: example-external-id
                    order_id: 1234
                    create_date: '2021-10-20'
                    dry_run: 0
                    is_refund_allowed: 0
                  user:
                    id: example-id
                    name: Example
                    custom: null
                    email: email@example.com
                    phone: null
                    country: RU
                  payment_details:
                    payment:
                      currency: RUB
                      amount: 7.96
                      amount_from_ps: 7.96
                    sales_tax:
                      percent: 0
                      amount: 0
                  purchase:
                    virtual_currency:
                      amount: 0
                      name: null
                    virtual_items: null
                    simple_checkout:
                      amount: 7.96
                      currency: RUB
                    pin_codes:
                      amount: null
                      currency: null
                      content: null
                    subscription:
                      name: null
                  payment_system:
                    decline_reason: null
  /merchants/{merchant_id}/reports/transactions/simple_search:
    get:
      summary: Find transactions (fast search)
      description: >
        Gets a list of transactions based on specific search parameters within a
        few seconds. This is an alternative to the [Find
        transactions](/api/pay-station/operation/find-transactions/) API call
        that returns data in JSON, CSV, or XLS format.


        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: find-transactions-fast
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - name: transaction_id
          in: query
          description: >-
            Transaction ID. Either this or `external_id` must be provided, but
            not both.
          schema:
            type: integer
        - name: external_id
          in: query
          description: >-
            Transaction ID in the game. It is unique for each payment. Either
            this or `transaction_id` must be provided, but not both.
          schema:
            type: string
      responses:
        '200':
          description: The list of transactions was successfully returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    user:
                      type: object
                      description: User details.
                      properties:
                        id:
                          type: string
                          description: User ID.
                        name:
                          type: string
                          description: User name.
                        email:
                          type: string
                          description: User email.
                        country:
                          type: string
                          description: >-
                            Two-letter uppercase country code per [ISO 3166-1
                            alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
                    transaction:
                      type: object
                      description: Transaction details.
                      properties:
                        project:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: Project ID. Can be found in Publisher Account.
                            name:
                              type: string
                              description: Project name.
                        id:
                          type: integer
                          description: Transaction ID.
                        external_id:
                          type: string
                          description: >-
                            Transaction ID in the game. It is unique for each
                            user payment.
                        status:
                          description: Transaction status.
                          $ref: '#/components/schemas/status.enum'
                        payment_date:
                          type: string
                          description: Date of the payment in YY-MM-DD format.
                        refund_reason:
                          type: string
                          description: Refund reason.
                    payment_details:
                      type: object
                      description: Payment details.
                      properties:
                        payment:
                          type: object
                          properties:
                            amount:
                              description: Payment amount.
                              type: number
                              format: float
                            currency:
                              type: string
                              description: >-
                                Payment currency. Three-letter currency code per
                                [ISO
                                4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/).
              example:
                - transaction:
                    id: 123456
                    project:
                      id: 123456
                      name: Test
                    payment_date: '2023-02-11 15:32:46'
                    external_id: example_external_id_123
                    status: done
                  user:
                    id: '123456'
                    name: John Smith
                    email: email@example.com
                    country: BR
                  payment_details:
                    payment:
                      currency: BRL
                      amount: 7.96
        '403':
          description: Access Denied.
        '404':
          description: Transaction Not Found.
        '422':
          description: >-
            Unprocessable Entity (You must pass either `transaction_id` or
            `external_id`).
  /merchants/{merchant_id}/reports/transactions/{transaction_id}/details:
    get:
      summary: Get transaction
      description: |
        Gets full transaction info by ID.

        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: get-transaction
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/transaction-id-path-param'
      responses:
        '200':
          description: The transaction information was successfully returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    customer_details:
                      type: object
                      properties:
                        billing_address:
                          type: string
                        bin:
                          type: string
                        browser_language:
                          type: string
                        country:
                          type: string
                        ip:
                          type: string
                        paystation_country:
                          type: string
                        phone:
                          type: string
                          nullable: true
                        timezone:
                          type: string
                        user_id:
                          type: string
                        user_name:
                          type: string
                    finance_details:
                      type: object
                      properties:
                        payment:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        payment_method_fee:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        payment_method_sum:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        payout:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        payout_currency_rate:
                          type: number
                          format: float
                        repatriation_commission:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        dispute_fee:
                          type: object
                          properties:
                            currency:
                              type: string
                              description: >-
                                Payment currency. Three-letter currency code per
                                [ISO
                                4217](/doc/pay-station/references/supported-currencies/).
                            amount:
                              type: number
                              format: float
                              description: The dispute fee amount in the payment currency.
                            date:
                              type: string
                              description: Date of the dispute opening.
                        sales_tax:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        direct_wht:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        vat:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        xsolla_balance_sum:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        xsolla_fee:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                    payment_details:
                      type: object
                      properties:
                        card_holdername:
                          type: string
                          nullable: true
                        card_issuer:
                          type: string
                        card_month:
                          type: integer
                        card_number:
                          type: integer
                        card_scheme:
                          type: string
                        card_year:
                          type: integer
                        customer_firstname:
                          type: string
                        customer_lastname:
                          type: string
                        enrollment:
                          type: boolean
                        ps_account:
                          type: string
                        zip_code:
                          type: string
                    subscription_details:
                      type: object
                      properties:
                        is_payment_from_subscription:
                          type: boolean
                        is_subscription_created:
                          type: boolean
                    transaction_details:
                      type: object
                      properties:
                        amount:
                          type: number
                          format: float
                        cancellation_date:
                          type: string
                          nullable: true
                        country:
                          type: string
                        currency:
                          type: string
                        custom_parameters:
                          type: string
                          nullable: true
                        foreign_invoice:
                          type: string
                          nullable: true
                        gift_recipient_email:
                          type: string
                          nullable: true
                        gift_recipient_id:
                          type: string
                          nullable: true
                        payment_date:
                          type: string
                        payment_method:
                          type: string
                        payment_method_name:
                          type: string
                        project:
                          type: integer
                        project_name:
                          type: string
                        purchase:
                          type: object
                          properties:
                            checkout:
                              type: object
                              properties:
                                amount:
                                  type: number
                                  format: float
                                currency:
                                  type: string
                            pin_codes:
                              type: object
                              properties:
                                amount:
                                  type: number
                                  format: float
                                content:
                                  type: string
                                  nullable: true
                                currency:
                                  type: string
                                  nullable: true
                            total:
                              type: object
                              properties:
                                amount:
                                  type: number
                                  format: float
                                currency:
                                  type: string
                            virtual_currency:
                              type: object
                              properties:
                                amount:
                                  type: number
                                  format: float
                                currency:
                                  type: string
                                name:
                                  type: string
                                quantity:
                                  type: string
                            virtual_items:
                              type: object
                              properties:
                                amount:
                                  type: number
                                  format: float
                                content:
                                  type: string
                                currency:
                                  type: string
                              nullable: true
                        refund_comment:
                          type: string
                          nullable: true
                        refund_reason:
                          type: string
                          nullable: true
                        status:
                          type: string
                        user_id:
                          type: string
              example:
                - customer_details:
                    billing_address: ''
                    bin: ''
                    browser_language: ''
                    country: US
                    ip: 209.11.22.33
                    paystation_country: ''
                    phone: null
                    timezone: ''
                    user_id: user1
                    user_name: John Smith
                  finance_details:
                    payment:
                      amount: 0.04
                      currency: USD
                    payment_method_fee:
                      amount: 0.01
                      currency: USD
                    payment_method_sum:
                      amount: 0.04
                      currency: USD
                    payout:
                      amount: 1.25
                      currency: RUB
                    payout_currency_rate: 62
                    repatriation_commission:
                      amount: 0
                      currency: USD
                    dispute_fee:
                      currency: USD
                      amount: 70
                      date: '2019-04-20 16:15:37'
                    sales_tax:
                      amount: 0
                      currency: USD
                    direct_wht:
                      amount: 0
                      currency: USD
                    vat:
                      amount: 0.01
                      currency: USD
                    xsolla_balance_sum:
                      amount: 0
                      currency: USD
                    xsolla_fee:
                      amount: 0
                      currency: USD
                  payment_details:
                    card_holdername: null
                    card_issuer: TEST BANK
                    card_month: 1
                    card_number: 1234123412341234
                    card_scheme: MASTERCARD
                    card_year: 2020
                    customer_firstname: ''
                    customer_lastname: ''
                    enrollment: false
                    ps_account: 1234test4321
                    zip_code: ''
                  subscription_details:
                    is_payment_from_subscription: false
                    is_subscription_created: true
                  transaction_details:
                    amount: 0.04
                    cancellation_date: null
                    country: US
                    currency: USD
                    custom_parameters: null
                    foreign_invoice: null
                    gift_recipient_email: null
                    gift_recipient_id: null
                    payment_date: '2019-03-21 16:15:37'
                    payment_method: '1380'
                    payment_method_name: Credit/Debit Cards
                    project: 21092
                    project_name: Test Project
                    purchase:
                      checkout:
                        amount: 0
                        currency: USD
                      pin_codes:
                        amount: 0
                        content: null
                        currency: null
                      total:
                        amount: 0.03
                        currency: USD
                      virtual_currency:
                        amount: 0.03
                        currency: USD
                        name: Gold coins
                        quantity: '2'
                      virtual_items: null
                    refund_comment: null
                    refund_reason: null
                    status: done
                    user_id: user1
  /merchants/{merchant_id}/reports/transactions/registry.{format}:
    servers:
      - url: https://api.xsolla.com/merchant/v3
    get:
      summary: Get transactions
      description: >
        Returns the list of detailed information about successful and canceled
        transactions for a specified period. In response, you get information
        about payments, including data on fees, taxes, as well as order and
        user. You can get the list in JSON or CSV format. You can use this API
        call to perform financial reconciliation.


        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: get-transactions
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/datetime-from-req'
        - $ref: '#/components/parameters/datetime-to-req'
        - $ref: '#/components/parameters/in-transfer-currency'
        - $ref: '#/components/parameters/show-total'
        - $ref: '#/components/parameters/merchant-of-records'
        - $ref: '#/components/parameters/project-id-query-param'
        - $ref: '#/components/parameters/show-dry-run'
        - $ref: '#/components/parameters/transfer-id'
        - $ref: '#/components/parameters/report-id'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit-req'
        - $ref: '#/components/parameters/transaction-status'
      responses:
        '200':
          description: The list of transactions was successfully returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    user:
                      type: object
                      description: User details.
                      properties:
                        id:
                          type: string
                          description: User ID.
                        email:
                          type: string
                          description: User email.
                        name:
                          type: string
                          description: User screen name.
                        phone:
                          type: string
                          description: User phone number.
                          nullable: true
                        country:
                          type: string
                          description: >-
                            Two-letter uppercase country code per [ISO 3166-1
                            alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
                        custom:
                          type: string
                          nullable: true
                        marketplace:
                          type: string
                        ip:
                          type: string
                    user_balance:
                      type: object
                      description: User balance.
                      properties:
                        payment_currency:
                          type: object
                          description: Preferred payment currency.
                          properties:
                            deduction_amount:
                              type: number
                              format: float
                            payout_amount_from_balance:
                              type: number
                              format: float
                            purchase_amount_from_balance:
                              type: number
                              format: float
                    transaction:
                      type: object
                      description: Transaction data.
                      properties:
                        custom_parameters:
                          type: object
                          nullable: true
                        direct_account:
                          type: integer
                        dry_run:
                          type: integer
                        external_id:
                          type: string
                          nullable: true
                        id:
                          type: integer
                        payment_method:
                          type: object
                          properties:
                            class:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                        project:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                        refund_reason:
                          type: string
                          nullable: true
                        refund_reason_comment:
                          type: string
                          nullable: true
                        status:
                          type: string
                          enum:
                            - created
                            - processing
                            - done
                            - canceled
                            - error
                            - refunded
                            - partiallyRefunded
                            - awaitingRefund
                            - disputeFee
                        transfer_date:
                          type: string
                          format: datetime
                    purchase:
                      type: object
                      description: Purchase details.
                      properties:
                        friend:
                          type: object
                          properties:
                            email:
                              type: string
                              nullable: true
                            user_id:
                              type: string
                              nullable: true
                        items_amount:
                          type: integer
                        pin_codes:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                              nullable: true
                            content:
                              type: string
                              nullable: true
                            currency:
                              type: string
                              nullable: true
                        purchase_amount:
                          type: number
                          format: float
                        simple_checkout:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                              nullable: true
                            currency:
                              type: string
                              nullable: true
                        subscription:
                          type: object
                          properties:
                            name:
                              type: string
                              nullable: true
                            plan_id:
                              type: integer
                              nullable: true
                            product_id:
                              type: string
                              nullable: true
                            product_name:
                              type: string
                              nullable: true
                            subscription_id:
                              type: integer
                              nullable: true
                        virtual_currency:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            currency:
                              type: string
                        virtual_currency_amount:
                          type: integer
                        virtual_items:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                              nullable: true
                            content:
                              type: string
                              nullable: true
                            currency:
                              type: string
                              nullable: true
                    payment_details:
                      type: object
                      description: Payment details.
                      properties:
                        chargebackPenalty:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                        commission_agent:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        commission_agent_fixed:
                          type: integer
                        commission_ps:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            fixed_amount:
                              type: integer
                            percent:
                              type: number
                              format: float
                        commission_ps_from_vat:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                        commission_user:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        commission_xsolla:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            fixed_amount:
                              type: integer
                            percent:
                              type: number
                              format: float
                        cpa_network_commission:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        payment:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            amount_from_ps:
                              type: integer
                            currency:
                              type: string
                        payout:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            amount_from_ps:
                              type: number
                              format: float
                            currency:
                              type: string
                            fx_rate:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        direct_wht:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        refundPenalty:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                        repatriation_costs:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        sales_tax:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                        vat:
                          type: object
                          properties:
                            amount:
                              type: number
                              format: float
                            percent:
                              type: number
                              format: float
                            user_amount:
                              type: integer
                            user_percent:
                              type: integer
              example:
                - payment_details:
                    chargebackPenalty:
                      amount: 0
                    commission_agent:
                      amount: 0
                      percent: 0
                    commission_agent_fixed: 0
                    commission_ps:
                      amount: 0
                      fixed_amount: 0
                      percent: 0
                    commission_ps_from_vat:
                      amount: 0
                    commission_user:
                      amount: 0.01
                      percent: 33.33
                    commission_xsolla:
                      amount: 0
                      fixed_amount: 0
                      percent: 5
                    cpa_network_commission:
                      amount: 0
                      percent: 0
                    payment:
                      amount: 0.03
                      amount_from_ps: 0
                      currency: USD
                    payout:
                      amount: 0.02
                      amount_from_ps: 0
                      currency: RUB
                      fx_rate: 64.1386407767
                      percent: 100
                    direct_wht:
                      amount: 0
                      percent: 0
                    refundPenalty:
                      amount: 0
                    repatriation_costs:
                      amount: 0
                      percent: 0
                    sales_tax:
                      amount: 0
                      percent: 0
                    vat:
                      amount: 0
                      percent: 0
                      user_amount: 0
                      user_percent: 0
                  purchase:
                    friend:
                      email: null
                      user_id: null
                    items_amount: 1
                    pin_codes:
                      amount: null
                      content: null
                      currency: null
                    purchase_amount: 0.02
                    simple_checkout:
                      amount: null
                      currency: null
                    subscription:
                      name: null
                      plan_id: null
                      product_id: null
                      product_name: null
                      subscription_id: null
                    virtual_currency:
                      amount: 0.02
                      currency: USD
                    virtual_currency_amount: 1
                    virtual_items:
                      amount: null
                      content: null
                      currency: null
                  transaction:
                    custom_parameters: null
                    direct_account: 0
                    dry_run: 0
                    external_id: null
                    id: 418756634
                    payment_method:
                      class: Digital Payment Methods
                      id: 2760
                      name: Your Balance
                    project:
                      id: 21092
                      name: Smith
                    refund_reason: null
                    refund_reason_comment: null
                    status: done
                    transfer_date: '2019-02-11T13:32:00+03:00'
                  user:
                    country: US
                    custom: null
                    email: email@example.com
                    id: smith123
                    marketplace: Pay Station
                    name: Tom
                    phone: null
                    ip: 209.11.22.33
                  user_balance:
                    payment_currency:
                      deduction_amount: 0
                      payout_amount_from_balance: 0.02
                      purchase_amount_from_balance: 0.02
  /merchants/{merchant_id}/reports/transfers:
    get:
      summary: Get payouts
      description: |
        Lists all payouts for a period.

        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: get-payouts
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/datetime-from'
        - $ref: '#/components/parameters/datetime-to'
        - $ref: '#/components/parameters/legal-entity-id'
        - $ref: '#/components/parameters/payout-status'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              example:
                - payout:
                    id: 1
                    date: '2014-01-03T00:00:00+04:00'
                    note: 12/05/2013 - 01/04/2014
                    currency: USD
                  transfer:
                    date: '2014-01-05T00:00:00+04:00'
                    note: '004357'
                    currency: USD
                  rate: 1
                  canceled: 0
  /merchants/{merchant_id}/reports/transactions/summary/transfer:
    get:
      summary: Get payouts breakdown in currency
      description: |
        Gets payouts breakdown in currency.

        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: get-payouts-breakdown
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/datetime-from'
        - $ref: '#/components/parameters/datetime-to'
        - $ref: '#/components/parameters/legal-entity-id'
        - $ref: '#/components/parameters/transaction-status'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              example:
                - IsoCurrency: RUB
                  PaymentsAmount: 223679.84
                  SumCommissionAgent: 11329.58
                  SumCommissionUserTaxes: 153.67
                  SumItems: 571325.13
                  SumNominalSum: 214792.98
                  SumOutProject: 551096.13
                  SumPayoutSum: 193316.71
                  TaxesOfPayments: 171.56
                  DirectTaxesOfPayments: 0.46
                - IsoCurrency: USD
                  PaymentsAmount: 482.58
                  SumCommissionAgent: 77.51
                  SumCommissionUserTaxes: 0.07
                  SumItems: 243777.62
                  SumNominalSum: 493.09
                  SumOutProject: 241787.62
                  SumPayoutSum: 462.62
                  TaxesOfPayments: 0.14
                  DirectTaxesOfPayments: 0.14
                - IsoCurrency: EUR
                  PaymentsAmount: 608.2
                  SumCommissionAgent: 55.71
                  SumCommissionUserTaxes: 90.94
                  SumItems: 156238.62
                  SumNominalSum: 607.26
                  SumOutProject: 156158.62
                  SumPayoutSum: 460.8
                  TaxesOfPayments: 90.94
                  DirectTaxesOfPayments: 0.07
  /merchants/{merchant_id}/reports:
    get:
      summary: Get reports
      description: |
        Gets the list of financial reports over a specified period.

        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - reports
      operationId: get-reports
      x-server: true
      x-admin: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/datetime-from-req'
        - $ref: '#/components/parameters/datetime-to-req'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              example:
                - agreement_document_id: Organization Inc_RUB
                  currency: RUB
                  is_direct_payout: false
                  is_draft_by_agreement: true
                  month: January
                  report_id: 57613
                  year: 2019
                - agreement_document_id: Organization Inc_EUR
                  currency: USD
                  is_direct_payout: false
                  is_draft_by_agreement: true
                  month: January
                  report_id: 57619
                  year: 2019
  /merchants/{merchant_id}/reports/transactions/{transaction_id}/refund:
    put:
      summary: Request refund
      description: >
        Sends a refund request to return a payment to a user. Read about the
        [Refund

        feature](https://developers.xsolla.com/doc/pay-station/features/refund/)
        to

        learn more about the process.


        <div class="note">
          <p><strong>Note</strong></p><p>You can call this API method in sandbox mode. To do this, pass the test payment data in the request. Refer to the <a href="https://developers.xsolla.com/doc/pay-station/testing/test-one-time-purchase-in-sandbox/#pay_station_testing_sandbox_bank_card_refund">instruction</a> for more information about sandbox mode access and testing scenarios.</p>
        </div>


        <p></p>


        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - refund
      operationId: request-refund
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/transaction-id-path-param'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - description
              properties:
                description:
                  type: string
                  maxLength: 4000
                  description: Reason for a refund.
                email:
                  type: string
                  maxLength: 100
                  description: User email.
            example:
              description: test refund request
      responses:
        '200':
          description: OK (No error).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >
                      Can return one of the following messages:

                      - No content.

                      - The request for a refund has been accepted. Xsolla CS
                      will manually complete the refund. It may take up to two
                      business days.

                      - The request for a refund has been accepted. Xsolla CS
                      will automatically send the customer an email with
                      alternative refund options as the user's method does not
                      support direct refunds.
              example:
                message: >-
                  The request for a refund has been accepted. Xsolla CS will
                  automatically send the customer an email with alternative
                  refund options as the user's method does not support direct
                  refunds.
        '204':
          description: Refund request accepted.
        '401':
          description: Unauthorized (Access denied).
        '404':
          description: Transaction Not Found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Transaction ID not valid. Please check payment
                      credentials. Otherwise, contact Xsolla support at
                      support@xsolla.com.
              example:
                message: >-
                  Transaction ID not valid. Please check payment credentials.
                  Otherwise, contact Xsolla support at support@xsolla.com.
        '422':
          description: Unprocessable Entity (Invalid request parameters).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >
                      Can return one of the following messages:

                      - We are processing the refund request. This may take up
                      to two business days.

                      - We are reaching the user for the information required
                      for the refund. For details, contact Xsolla Support.

                      - Incorrect payment status. Refund is possible only for
                      payments with "completed" or "error" status.

                      - To process this request, the customer's email address
                      field must be filled. Please specify the customer's email
                      address and try again.

                      - Full refund is unavailable because there are successful
                      partial refunds for this transaction.

                      - Refund failed. Please contact Xsolla Support to process
                      it manually.

                      - Dispute for this invoice is already opened. Can’t make a
                      refund yet.
              example:
                message: >-
                  We are processing the refund request. This may take up to two
                  business days.
  /merchants/{merchant_id}/reports/transactions/{transaction_id}/partial_refund:
    put:
      summary: Request partial refund
      description: >
        Sends a request for a partial refund to a user. Refer to our
        [documentation](https://developers.xsolla.com/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow)
        for detailed information about the refund process and payment methods
        that support partial refunds.


        <div class="note">
          <p><strong>Note</strong></p><p>You can call this API method in sandbox mode. To do this, pass the test payment data in the request. Refer to the <a href="https://developers.xsolla.com/doc/pay-station/testing/test-one-time-purchase-in-sandbox/#pay_station_testing_sandbox_bank_card_partial_refund">instruction</a> for more information about sandbox mode access and testing scenarios.</p>
        </div>


        <p></p>


        <div class="notice">
          <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.</p>
        </div>
      tags:
        - refund
      operationId: request-partial-refund
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/transaction-id-path-param'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - description
                - refund_amount
              properties:
                description:
                  type: string
                  maxLength: 4000
                  description: Reason for a refund.
                refund_amount:
                  type: number
                  format: float
                  description: The refund amount in a purchase currency.
            example:
              refund_amount: 1.5
              description: test refund request
      responses:
        '204':
          description: Refund request accepted
        '403':
          description: Do not have necessary permission
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Transaction with specified ID does not exist. Please check
                      payment credentials. Otherwise, contact Xsolla support at
                      support@xsolla.com.
              example:
                message: Transaction with specified ID does not exist.
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >
                      **Refund is not acceptable**


                      Returns one of the following messages:

                      - Partial refund is unavailable for operations with user
                      balance.

                      - Requested transaction is partial refund and cannot be
                      canceled.

                      - Partial refund is unavailable for subscription payments.

                      - Refund cannot be completed due to a payment system
                      error. Please try again later.

                      - Requested partial refund amount exceeds payment amount.

                      - Requested partial refund amount is less than minimum
                      amount specified by payment system.

                      - Payment amount after partial refund will be less than
                      allowable amount specified by payment system.

                      - Dispute for this invoice is already opened. Can’t make a
                      refund yet.


                      **Current payment method does not support partial
                      refunds**


                      Returns one of the following messages:

                      - Current payment method does not support partial refunds.

                      - Current transaction status does not allow refunds.

                      - Deadline for refund is exceeded.

                      - Partial refund is unavailable because discount was
                      applied during payment creation.


                      **Cannot execute partial refund because of wrong
                      precision**


                      Returns the following message:

                      - Partial refund is unavailable because requested amount
                      is specified with incorrect precision for purchase
                      currency.
              example:
                message: Partial refund is unavailable for subscription payments.
  /merchants/{merchant_id}/projects/{project_id}/payments/{transaction_id}/chargeback:
    post:
      summary: Request chargeback
      description: >
        Requests chargeback in the sandbox mode:


        - To access the sandbox mode, pass `"mode":"sandbox"` when you [get the
        token](https://developers.xsolla.com/api/pay-station/operation/create-token/).


        - Test payment has to be made in the sandbox mode in the same project
        that you use for testing.


        - Transaction status has to be **other than** `refunded`, `cancelled`.


        - Your role in Publisher Account has to be at least **Financial
        manager**. (You can find it in the **Company settings > Users**
        section.)


        - Refer to the <a
        href="https://developers.xsolla.com/doc/pay-station/testing/test-one-time-purchase-in-sandbox/#pay_station_testing_sandbox_bank_card_chargeback">instruction</a>
        for more information about this testing scenario.


        <div class="note">
          <p><strong>Note</strong></p><p>Refer to the <a href="https://developers.xsolla.com/doc/pay-station/testing/general-info/">documentation</a> for more information about other testing scenarios.</p>
        </div>
      tags:
        - testing
      operationId: request-chargeback
      x-server: true
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/merchant-id-path-param'
        - $ref: '#/components/parameters/project-id-path-param'
        - $ref: '#/components/parameters/transaction-id-path-param'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/empty-body'
      responses:
        '204':
          description: No Content (No error).
        '404':
          description: Transaction Not Found.
        '422':
          description: Unprocessable Entity (Invalid request parameters).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >
                      Can return one of the following messages:

                      - Error processing chargeback. Try again or use another
                      payment.

                      - Payment not found. Check payment ID.

                      - Payment does not belong to this project.

                      - Not test payment. Chargeback is possible only for
                      payments made in sandbox mode.

                      - Incorrect payment status. Chargeback is possible only
                      for payments with “Completed” status.
              example:
                message: >-
                  Not test payment. Chargeback is possible only for payments
                  made in sandbox mode.
components:
  securitySchemes:
    basicAuth:
      type: http
      description: >-
        Xsolla API uses basic access authentication. All requests to API must
        contain the `Authorization: Basic <your_authorization_basic_key>`
        header, where `<your_authorization_basic_key>` is the
        `merchant_id:api_key` pair encoded according to the Base64 standard.

         Go to [Publisher Account](https://publisher.xsolla.com/) to find these parameters:<ul><li>`merchant_id` is shown:<ul><li>In the **Company settings > Company** section.</li><li>In the URL in the browser address bar on any Publisher Account page. The URL has the following format: `https://publisher.xsolla.com/<merchant_id>`.</li></ul></li><li>`api_key` is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:<ul><li>**Company settings > API keys**.</li><li>**Project settings > API keys**.</li></ul></li></ul><br>
         For more information about working with API keys, see the [API reference](https://developers.xsolla.com/api/getting-started/#api_keys_overview).
      scheme: basic
  parameters:
    merchant-id-path-param:
      name: merchant_id
      in: path
      required: true
      description: Merchant ID.
      schema:
        type: integer
    project-id-path-param:
      name: project_id
      in: path
      required: true
      description: Project ID.
      schema:
        type: integer
    user-id-path-param:
      name: user_id
      in: path
      required: true
      description: >-
        Unique user ID in the game stored on your side. Make sure you pass the
        existing user ID. In case an error occurs, refer to the [answers to the
        FAQs](/doc/pay-station/references/faq/#faq_validation).
      schema:
        type: string
    mode:
      name: mode
      in: query
      required: false
      description: >-
        Set to `sandbox` to test the payment process. Remove the parameter to
        make real payments.
      schema:
        type: string
    type-path-param:
      name: type
      in: path
      required: true
      description: |
        Type of payment account.
      schema:
        type: string
        enum:
          - card
          - amazon
          - skrill
          - paypal
          - toss
          - alipayplus_cn
          - alipayplus_hk
          - alipayplus_gcash
          - alipayplus_dana
          - alipayplus_rabbitlinepay
          - alipayplus_tng
          - alipayplus_boost
          - alipayplus_truemoney
          - alipayplus_maya
          - alipayplus_kplus
          - softbank_paypay
          - softbank_docomo
          - softbank_softbank2
          - softbank_au
          - softbank_ymobile
          - paysafecard_eu
          - paysafecard_us
          - paidy
          - klarna
          - mercadopago
          - nupay
        x-enumDescriptions:
          card: Bank cards.
          amazon: Amazon Pay.
          skrill: Skrill Digital Wallet.
          paypal: PayPal.
          toss: Toss Wallet.
          alipayplus_cn: Alipay.
          alipayplus_hk: Alipay (Hong Kong).
          alipayplus_gcash: GCash.
          alipayplus_dana: DANA.
          alipayplus_rabbitlinepay: Rabbit LINE pay.
          alipayplus_tng: Touch 'n Go.
          alipayplus_boost: Boost.
          alipayplus_truemoney: TrueMoney Wallet.
          alipayplus_maya: Maya.
          alipayplus_kplus: K PLUS.
          softbank_paypay: PayPay.
          softbank_docomo: Docomo.
          softbank_softbank2: SoftBank.
          softbank_au: au Easy Payment.
          softbank_ymobile: Y!mobile.
          paysafecard_eu: Paysafecard (EU).
          paysafecard_us: Paysafecard (US).
          paidy: Paidy.
          klarna: >-
            Klarna. Payment account saving is available only for US, UK, Sweden,
            Germany, Austria, Norway, Finland, Denmark, Netherlands.
          mercadopago: Mercado Pago (including Mercado Pago Connect).
          nupay: NuPay.
    account-id-path-param:
      name: account_id
      in: path
      required: true
      description: ID of the saved account in Xsolla database.
      schema:
        type: integer
    format:
      name: format
      in: path
      required: true
      description: |
        Data format.
      schema:
        type: string
        enum:
          - json
          - csv
          - xls
    datetime-from:
      name: datetime_from
      in: query
      required: false
      description: Period start.
      schema:
        type: string
        format: datetime
    datetime-to:
      name: datetime_to
      in: query
      required: false
      description: Period end.
      schema:
        type: string
        format: datetime
    project-id-query-param:
      name: project_id
      in: query
      required: false
      description: Project ID.
      schema:
        type: integer
    transaction-id:
      name: transaction_id
      in: query
      required: false
      description: Transaction ID.
      schema:
        type: integer
    type:
      name: type
      in: query
      required: false
      description: |
        Type of transactions shown in the search results:
      schema:
        type: string
        enum:
          - all
          - transferred
          - canceled
          - test
        x-enumDescriptions:
          all: All transactions.
          transferred: Successful transactions excluding test transactions.
          canceled: Canceled transactions excluding test transactions.
          test: Test transactions.
    phone:
      name: phone
      in: query
      required: false
      description: Phone number in international format.
      schema:
        type: string
    user-id-query-param:
      name: user_id
      in: query
      required: false
      description: >-
        Unique user ID in the game stored on your side. Make sure you pass the
        existing user ID. In case an error occurs, refer to the [answers to the
        FAQs](/doc/pay-station/references/faq/#faq_validation).
      schema:
        type: string
    user-name:
      name: user_name
      in: query
      required: false
      description: Username.
      schema:
        type: string
    user-custom:
      name: user_custom
      in: query
      required: false
      description: Custom parameter for user identification.
      schema:
        type: string
    email:
      name: email
      in: query
      required: false
      description: User email.
      schema:
        type: string
        maxLength: 100
    external-id:
      name: external_id
      in: query
      required: false
      description: Transaction ID in the game. Has to be unique for each user payment.
      schema:
        type: string
    order-id:
      name: order_id
      in: query
      required: false
      description: >-
        Order ID. You can use it to call the [Get
        order](/api/shop-builder/operation/get-order/) API method.
      schema:
        type: integer
      example: 1234
    offset:
      name: offset
      in: query
      required: false
      description: >-
        Number of the element from which the list is generated (the count starts
        from 0).
      schema:
        type: integer
    limit:
      name: limit
      in: query
      required: false
      description: Limit for the number of elements on the page.
      schema:
        type: integer
    status:
      name: status
      in: query
      required: false
      description: A transaction status.
      schema:
        $ref: '#/components/schemas/status.enum'
    transaction-id-path-param:
      name: transaction_id
      in: path
      required: true
      description: Transaction ID.
      schema:
        type: integer
    datetime-from-req:
      name: datetime_from
      in: query
      required: true
      description: >-
        Period start in the YYYY-MM-DD format. Not required if at least one of
        the following parameters is
        passed:<ul><li>`transfer_id`</li><li>`report_id`</li></ul>
      schema:
        type: string
        format: datetime
      example: '2023-02-08'
    datetime-to-req:
      name: datetime_to
      in: query
      required: true
      description: >-
        Period end in the YYYY-MM-DD format. Not required if at least one of the
        following parameters is
        passed:<ul><li>`transfer_id`</li><li>`report_id`</li></ul> The
        difference between `datetime_from` and `datetime_to` cannot be more than
        92 days.
      schema:
        type: string
        format: datetime
      example: '2023-03-08'
    in-transfer-currency:
      name: in_transfer_currency
      in: query
      required: true
      description: >-
        Converts all financial data to the payout currency (the pay-in currency
        is used by default). Not required if at least one of the following
        parameters is passed:<ul><li>`transfer_id`</li><li>`report_id`</li></ul>
      schema:
        type: integer
    show-total:
      name: show_total
      in: query
      description: >-
        Whether to include the total transactions amount in the report.
        Available for export in CSV format only. `true` by default.
      schema:
        type: boolean
    merchant-of-records:
      name: merchant_of_records
      in: query
      required: false
      description: >-
        Merchant of Record. Can be `xsolla`, `merchant`, or not specified. If
        `merchant`, returns transactions made via the partner’s gateways. If
        `xsolla`, returns transactions made not via the partner’s gateways. If
        not specified, returns all transactions.
      schema:
        type: string
        nullable: true
        enum:
          - xsolla
          - merchant
        x-enumDescriptions:
          merchant: Returns transactions made via the partner’s gateways.
          xsolla: Returns transactions made not via the partner’s gateways.
    show-dry-run:
      name: show_dry_run
      in: query
      required: false
      description: Whether to include test transactions.
      schema:
        type: boolean
    transfer-id:
      name: transfer_id
      in: query
      required: false
      description: Payout ID.
      schema:
        type: integer
    report-id:
      name: report_id
      in: query
      required: false
      description: Financial report ID.
      schema:
        type: integer
    limit-req:
      name: limit
      in: query
      required: false
      description: >-
        Limit for the number of displayed transactions on the page. If this
        parameter is passed, you don’t need to pass the `datetime_from` and
        `datetime_to` parameters.
      schema:
        type: integer
    transaction-status:
      name: status
      in: query
      required: false
      description: Transaction status.
      schema:
        type: string
        enum:
          - done
          - canceled
          - error
          - refunded
    legal-entity-id:
      name: legal_entity_id
      in: query
      required: false
      description: ID of the developer's legal entity.
      schema:
        type: integer
    payout-status:
      name: status
      in: query
      required: false
      description: |
        Payout status.
      schema:
        type: string
        enum:
          - hold
          - ready
          - paid
        x-enumDescriptions:
          hold: Waiting for a request to proceed.
          ready: Payout in progress.
          paid: Payout completed.
  schemas:
    id.user:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          description: >-
            Unique user ID in the game stored on your side. Make sure you pass
            the existing user ID. In case an error occurs, refer to the [answers
            to the FAQs](/doc/pay-station/references/faq/#faq_validation).
    email.user:
      type: object
      maxLength: 100
      description: >
        The `user.email` object is an integral part of building anti-fraud
        models and helps increase acceptance rates. It is both Xsolla and
        payment systems requirement. If the parameter is not passed, the
        required field for entering email appears on the payment page. A user
        receives a purchase receipt to the email passed in the parameter or
        entered on the payment page.
      required:
        - value
      properties:
        value:
          type: string
          description: >-
            User email. Must be valid according to the [RFC
            822](https://www.w3.org/Protocols/rfc822/#z8) protocol.
        allow_modify:
          type: boolean
          description: >-
            Whether a user can enter their email in the payment UI. If the
            `user.email.value` parameter is passed in the token, the value is
            `false` by default.
    name.user:
      type: object
      properties:
        value:
          type: string
          description: User screen name.
        allow_modify:
          type: boolean
          description: >-
            Whether a user can enter their name in the payment UI. If the
            `user.name.value` parameter is passed in the token, the value is
            `false` by default.
    age.user:
      type: integer
      description: User age.
    phone.user:
      type: object
      properties:
        value:
          type: string
          description: User phone number.
      nullable: true
    country.user:
      type: object
      properties:
        value:
          type: string
          description: >-
            Two-letter uppercase country code per [ISO 3166-1
            alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        allow_modify:
          type: boolean
          description: >-
            Whether a user can change the country on payment UI. If
            `country.value` is passed in the token, the value is `false` by
            default.
    attributes.user:
      type: object
      description: >-
        User attributes for filtering the item list, represented as a valid JSON
        set of key-value pairs.
    steam_id.user:
      type: object
      properties:
        value:
          type: string
          description: Steam ID.
    tracking_id.user:
      type: object
      properties:
        value:
          type: string
          minLength: 32
          maxLength: 32
          description: >-
            Unique user ID — used in marketing campaigns. Can contain digits and
            Latin characters.
    public_id.user:
      type: object
      properties:
        value:
          type: string
          description: >-
            Parameter that uniquely identifies the user and is known to the user
            (email, screen name, etc). Allows the user to make purchases outside
            the game store (e.g., via cash kiosks).
    utm.user:
      type: object
      description: Traffic attributes.
      properties:
        utm_source:
          type: string
          description: Traffic source.
        utm_medium:
          type: string
          description: Traffic channel (contextual ads, media ads, email lists, etc.).
        utm_campaign:
          type: string
          description: Campaign title, transliterated or translated to English.
        utm_term:
          type: string
          description: >-
            Campaign keyword. If set, statistics will be based on the keywords
            used for ad targeting rather than on specific search queries. In
            Google Analytics, the specified `utm_term` is part of the general
            search terms report.
        utm_content:
          type: string
          description: Campaign content.
    is_legal.user:
      type: boolean
      description: Whether the user is a legal entity.
    legal:
      type: object
      description: Object with legal entity details.
      properties:
        name:
          type: string
          description: Full legal name.
        address:
          type: string
          description: Full legal address.
        vat_id:
          type: string
          description: Individual taxpayer identifier.
        country:
          type: string
          description: >-
            Country of incorporation. Two-letter uppercase country code per [ISO
            3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) is
            used.
    legal.user:
      allOf:
        - description: >-
            Object with legal entity details. Object and all its parameters are
            required if `user.is_legal` is `true`.
        - $ref: '#/components/schemas/legal'
    user:
      type: object
      description: User details.
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/id.user'
        email:
          $ref: '#/components/schemas/email.user'
        name:
          $ref: '#/components/schemas/name.user'
        age:
          $ref: '#/components/schemas/age.user'
        phone:
          $ref: '#/components/schemas/phone.user'
        country:
          $ref: '#/components/schemas/country.user'
        attributes:
          $ref: '#/components/schemas/attributes.user'
        steam_id:
          $ref: '#/components/schemas/steam_id.user'
        tracking_id:
          $ref: '#/components/schemas/tracking_id.user'
        public_id:
          $ref: '#/components/schemas/public_id.user'
        utm:
          $ref: '#/components/schemas/utm.user'
        is_legal:
          $ref: '#/components/schemas/is_legal.user'
        legal:
          $ref: '#/components/schemas/legal.user'
    project_id:
      type: integer
      description: Game’s Xsolla ID. Can be found in Publisher Account.
    external_id:
      type: string
      description: >-
        Transaction ID in the game. Has to be unique for each user payment.
        Refer to <a
        href="https://developers.xsolla.com/doc/pay-station/references/faq/#faq_payments_q_new_transaction_external_id">documentation</a>
        for detailed information.
    language:
      type: string
      description: >-
        Interface language. Two-letter lowercase [language
        code](https://developers.xsolla.com/doc/pay-station/features/localization/).
    return_url:
      type: string
      description: >-
        URL of the page where a user is redirected to after the payment. Refer
        to <a
        href="https://developers.xsolla.com/doc/pay-station/how-to/how-to-configure-redirects/">documentation</a>
        for detailed information about configuring redirects.
    redirect_policy:
      type: object
      description: Redirect policy settings.
      properties:
        redirect_conditions:
          type: string
          description: >-
            Payment status for which a user is redirected to the return URL. Can
            be `none`, `successful`, `successful_or_canсeled`, or `any`.
          enum:
            - none
            - successful
            - successful_or_canceled
            - any
        delay:
          type: integer
          description: >-
            Delay (in seconds) after which a user is automatically redirected to
            the return URL.
        status_for_manual_redirection:
          type: string
          description: >-
            Payment status for which a button redirecting a user to the return
            URL is displayed. Can be `none`, `successful`,
            `successful_or_canсeled`, or `any`.
          enum:
            - none
            - successful
            - successful_or_canceled
            - any
        manual_redirection_action:
          type: string
          description: >-
            Pay Station behavior triggered by the user clicking the close button
            or the **Back to the Game** button. Can be `redirect` (by default)
            and `postmessage`. If set to `redirect`, a user is redirected to the
            URL passed in the token or specified in Publisher Account. If set to
            `postmessage`, a user is not redirected to other pages. Clicking the
            close icon initiates sending the `close` event, and clicking the
            **Back to the Game** button — the `return` event.
          enum:
            - redirect
            - postmessage
        redirect_button_caption:
          type: string
          description: Text on the button for manual redirection.
    currency:
      type: string
      description: >-
        Preferred payment currency. Three-letter currency code per [ISO
        4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/).
    mode.settings:
      type: string
      description: >-
        Set to `sandbox` to test out the payment process. In this case, use
        *https://sandbox-secure.xsolla.com* to access the test payment UI.
    payment_method:
      type: integer
      description: Payment method ID.
    payment_widget:
      type: string
      description: >-
        Payment widget. Can be `paybycash` or `giftcard`. If the parameter is
        set, the user is redirected to the Pay by Cash or Gift Cards widget,
        respectively.
      enum:
        - paybycash
        - giftcard
    theme.ui:
      type: string
      description: >-
        Payment UI theme. Can be `63295a9a2e47fab76f7708e1` for the light theme
        (default) or `63295aab2e47fab76f7708e3` for the dark theme. You can also
        [create a custom
        theme](https://developers.xsolla.com/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_in_token)
        and pass its ID in this parameter.
      enum:
        - 63295a9a2e47fab76f7708e1
        - 63295aab2e47fab76f7708e3
    close_button_icon:
      type: string
      description: The icon of the **Close** button in the payment UI.
      enum:
        - arrow
        - cross
      x-enumDescriptions:
        arrow: The **←** icon on the left side of the payment UI header.
        cross: The **×** icon on the right side of the payment UI header.
    header.desktop:
      type: object
      description: Header settings.
      properties:
        is_visible:
          type: boolean
          description: Whether to show the header in the payment UI.
        visible_logo:
          type: boolean
          description: >-
            If `true`, the logo is displayed in the header. To upload the image,
            open your project in [Publisher
            Account](https://publisher.xsolla.com/) and go to the **Pay Station
            > Settings** section.
        visible_name:
          type: boolean
          description: Whether to show the project name in the header.
        visible_purchase:
          type: boolean
          description: >-
            Whether to show the purchase description
            (`purchase.description.value`) in the header. `true` by default.
        type:
          type: string
          description: >-
            How to show the header. Can be `compact` (hides project name and
            user ID) or `normal` (default).
          enum:
            - compact
            - normal
        close_button:
          type: boolean
          description: >-
            Whether to show the **Close** button in the payment UI. The button
            closes the payment UI and redirects the user to the URL specified in
            the `settings.return_url` parameter. `false` by default.
        close_button_icon:
          $ref: '#/components/schemas/close_button_icon'
    subscription_list.desktop:
      type: object
      description: Settings for the list of subscription plans.
      properties:
        description:
          type: string
          description: >-
            Any text to show above the list of available subscription plans in
            the payment UI.
        display_local_price:
          type: boolean
          description: >
            If `true`, and if the user’s local currency is different from the
            one set for the subscription plan, the user will be able to see both
            prices: one in the local and one in the basic currency.
    desktop.ui:
      type: object
      description: Interface settings for the desktop version.
      properties:
        header:
          $ref: '#/components/schemas/header.desktop'
        subscription_list:
          $ref: '#/components/schemas/subscription_list.desktop'
    header.ui:
      type: object
      properties:
        visible_virtual_currency_balance:
          type: boolean
          description: >-
            Whether or not this element can be hidden on Payment UI. `true` by
            default.
    mobile.ui:
      type: object
      properties:
        header:
          type: object
          properties:
            close_button:
              type: boolean
              description: >-
                Whether to show a **Close** button in Pay Station mobile. The
                button closes Pay Station and redirects the user to the URL
                specified in the `settings.return_url` parameter. `false` by
                default.
            close_button_icon:
              $ref: '#/components/schemas/close_button_icon'
    components:
      type: object
      description: Menu settings.
      properties:
        virtual_items:
          type: object
          description: Virtual items submenu settings.
          properties:
            order:
              type: integer
              description: Position of the submenu in the menu.
            hidden:
              type: boolean
              description: Whether to show the submenu.
            selected_group:
              type: string
              description: Group to show after opening the virtual items tab.
            selected_item:
              type: string
              description: Item to show after opening the virtual items tab (item SKU).
        virtual_currency:
          type: object
          description: Virtual currency submenu settings.
          properties:
            custom_amount:
              type: boolean
              description: >-
                Whether the user can enter an arbitrary quantity of the virtual
                currency in the payment UI.
            order:
              type: integer
              description: Position of the submenu in the menu.
            hidden:
              type: boolean
              description: Whether to show the submenu.
        subscriptions:
          type: object
          description: Subscription plans submenu settings.
          properties:
            order:
              type: integer
              description: Position of the submenu in the menu.
            hidden:
              type: boolean
              description: Whether to show the submenu.
    mode.ui:
      type: string
      description: >
        Display mode of the payment UI for managing saved payment methods. Can
        be set to `user_account` or omitted. In this mode, the user can only
        change the language, add new payment methods, and remove existing ones.


        <div class="note">
          <p><strong>Note</strong></p><p>When this parameter is passed, the redirect button is not displayed. To redirect a user after saving a payment method, configure <a href="/doc/pay-station/how-to/how-to-configure-redirects/#pay_station_how_to_configure_redirects_automatic/">automatic redirects</a>.</p>
        </div>
    is_prevent_external_link_open:
      type: boolean
      description: >-
        Whether or not redirecting links to an external resource is disabled.
        `false` by default. When clicking an external link, the
        `external-link-open` event is sent via the `postMessage` mechanism. The
        address for the redirected link is passed in the `url` parameter.
    is_payment_methods_list_mode:
      type: boolean
      description: >-
        Whether the list of payment methods available in the user’s country is
        displayed when opening the payment UI. If `false` (default), the payment
        method passed in the `settings.payment_method` parameter or the method
        selected by the [PayRank
        algorithm](https://developers.xsolla.com/solutions/payments/payment-ui-management/top-payment-methods-management/)
        is displayed.
    is_independent_windows:
      type: boolean
      description: >-
        Whether to redirect users from the embedded launcher’s browser (WebView)
        to their default browser to make a purchase. `false` by default.
    payment_accounts_enable:
      type: object
      properties:
        enable:
          type: boolean
          description: >-
            Specifies whether to display the pencil icon in the payment UI that
            goes to the payment method editing page. `true` by default.
        order:
          type: integer
          description: >-
            Position of the section in the drop-down list in the payment UI.
            Required if `settings.ui.user_account.payment_accounts.enable` is
            passed.
          minimum: 1
    user_account:
      type: object
      description: User account details.
      properties:
        payment_accounts:
          allOf:
            - description: '**Saved methods** section.'
            - $ref: '#/components/schemas/payment_accounts_enable'
    currency_format:
      type: string
      description: >-
        Set to `code` to display a three-letter [ISO
        4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/)
        currency code in the payment UI. The currency symbol is displayed
        instead of the three-letter currency code by default.
    is_show_close_widget_warning:
      type: boolean
      description: >-
        Whether to show a warning about processing the transaction when hovering
        over the **×** icon before closing the payment page. If `false` is
        passed, or the parameter is not passed, the warning is not displayed.
        `true` by default.
    layout:
      type: string
      description: >-
        Location of the main elements of the payment UI. You can open the
        payment UI inside your game and/or swap the columns with information
        about an order and payment methods. Refer to the [customization
        instructions](https://developers.xsolla.com/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_layout)
        for detailed information.
      enum:
        - embed
        - column_reverse
        - embed_column_reverse
    is_three_ds_independent_windows:
      type: boolean
      description: >-
        Whether the 3-D Secure verification opens in a new browser window. If
        your setup enforces a Content Security Policy (CSP), set to `true`.
      default: false
    is_cart_open_by_default:
      type: boolean
      description: >-
        The display of the list of cart items and financial details in the
        payment UI. If `true`, information is displayed in an extended view. If
        `false` (default) or the parameter is not passed, information is
        displayed in a collapsed view.
    gp_quick_payment_button:
      type: boolean
      description: >-
        The way the Google Pay payment method is displayed. If `true`, the
        button for quick payment via Google Pay is displayed at the top of the
        payment UI, regardless of the user’s device and browser. If `false`,
        Google Pay is displayed in the list of payment methods according to the
        [PayRank](/doc/pay-station/how-to/how-to-manage-top-payment-methods/)
        algorithm. If the parameter is not passed, Google Pay is displayed at
        the top of the payment UI on any user’s devices and browsers, except
        Safari — on Safari, it is displayed in the list of payment methods.
    ap_quick_payment_button:
      type: boolean
      description: >
        Whether to display the button for quick payment via Apple Pay at the top
        of the payment UI on supported devices. `true` by default. If `false`,
        Apple Pay is displayed in the list of payment methods according to the
        [PayRank](/doc/pay-station/how-to/how-to-manage-top-payment-methods/)
        algorithm.


        <div class="note">
          <p><strong>Note</strong></p><p>On Android devices and any other devices that don’t support payment with Apple Pay, this payment method will be hidden from the list of available ones regardless of the parameter value.</p>
        </div>
    is_search_field_hidden:
      type: boolean
      description: >-
        Whether to show a payment method search bar in the payment UI. If
        `true`, the search bar is hidden. `false` by default.
    is_language_selector_hidden:
      type: boolean
      description: >-
        Whether the language selector is hidden on the payment page. If `false`
        (by default), the selector is displayed.
    ui:
      type: object
      description: Interface settings.
      properties:
        theme:
          $ref: '#/components/schemas/theme.ui'
        desktop:
          $ref: '#/components/schemas/desktop.ui'
        header:
          $ref: '#/components/schemas/header.ui'
        mobile:
          $ref: '#/components/schemas/mobile.ui'
        components:
          $ref: '#/components/schemas/components'
        mode:
          $ref: '#/components/schemas/mode.ui'
        is_prevent_external_link_open:
          $ref: '#/components/schemas/is_prevent_external_link_open'
        is_payment_methods_list_mode:
          $ref: '#/components/schemas/is_payment_methods_list_mode'
        is_independent_windows:
          $ref: '#/components/schemas/is_independent_windows'
        user_account:
          $ref: '#/components/schemas/user_account'
        currency_format:
          $ref: '#/components/schemas/currency_format'
        is_show_close_widget_warning:
          $ref: '#/components/schemas/is_show_close_widget_warning'
        layout:
          $ref: '#/components/schemas/layout'
        is_three_ds_independent_windows:
          $ref: '#/components/schemas/is_three_ds_independent_windows'
        is_cart_open_by_default:
          $ref: '#/components/schemas/is_cart_open_by_default'
        gp_quick_payment_button:
          $ref: '#/components/schemas/gp_quick_payment_button'
        apple_pay_quick_payment_button:
          $ref: '#/components/schemas/ap_quick_payment_button'
        is_search_field_hidden:
          $ref: '#/components/schemas/is_search_field_hidden'
        is_language_selector_hidden:
          $ref: '#/components/schemas/is_language_selector_hidden'
    settings:
      type: object
      description: Settings for configuring payment process and the payment UI for a user.
      required:
        - project_id
      properties:
        project_id:
          $ref: '#/components/schemas/project_id'
        external_id:
          $ref: '#/components/schemas/external_id'
        language:
          $ref: '#/components/schemas/language'
        return_url:
          $ref: '#/components/schemas/return_url'
        redirect_policy:
          $ref: '#/components/schemas/redirect_policy'
        currency:
          $ref: '#/components/schemas/currency'
        mode:
          $ref: '#/components/schemas/mode.settings'
        payment_method:
          $ref: '#/components/schemas/payment_method'
        payment_widget:
          $ref: '#/components/schemas/payment_widget'
        ui:
          $ref: '#/components/schemas/ui'
    subscription:
      type: object
      description: Subscription data.
      properties:
        plan_id:
          type: string
          description: >-
            External ID of the subscription plan. Can be found in the
            **Subscriptions > Subscription plans** section of Publisher Account.
        operation:
          type: string
          description: >-
            The type of operation applied to the user’s subscription plan. To
            change the subscription plan, pass the `change_plan` value. You need
            to specify the new plan ID in the `purchase.subscription.plan_id`
            parameter.
        product_id:
          type: string
          description: Product ID.
        currency:
          type: string
          description: Currency of the subscription plan to use in all calculations.
        available_plans:
          type: array
          items:
            type: string
          description: Subscription plans to show in the payment UI.
        trial_days:
          type: integer
          description: Trial period in days.
    purchase:
      type: object
      description: Object containing purchase details.
      properties:
        subscription:
          $ref: '#/components/schemas/subscription'
    custom_parameters:
      type: object
      description: >
        This object contains parameters to configure anti-fraud filters. The
        list of parameters is shown below. To add custom parameters, contact
        your Customer Success Manager or email at
        [csm@xsolla.com](mailto:csm@xsolla.com).
      properties:
        registration_date:
          type: string
          description: >-
            Account creation date per [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        total_hours:
          type: integer
          description: Total number of in-game hours.
        total_characters:
          type: integer
          description: Number of in-game characters.
        social_networks_added:
          type: boolean
          description: Whether the player has connected social media profiles.
        profile_image_added:
          type: boolean
          description: Whether the player has uploaded a profile image.
        active_date:
          type: string
          description: >-
            Last seen date per [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        total_friends:
          type: integer
          description: Number of friends.
        additional_verification:
          type: boolean
          description: Whether the player uses account verification procedures.
        win_rate:
          type: integer
          description: Win rate.
        last_change_password_date:
          type: string
          description: >-
            Last password change date per [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
        chat_activity:
          type: boolean
          description: Whether the player uses the chat function.
        forum_activity:
          type: boolean
          description: Whether the player uses the forum function.
        total_bans:
          type: integer
          description: Number of times the player was banned in the chat/forum.
        profile_completed:
          type: boolean
          description: Whether the player added additional information to their profile.
        notifications_enabled:
          type: boolean
          description: Whether the player enabled notifications.
        user_level:
          type: integer
          description: Player’s level, reputation, or rank.
        karma_points:
          type: integer
          description: Player’s karma.
        total_sum:
          type: number
          format: float
          description: Total amount of payments.
        non_premium_currency:
          type: number
          format: float
          description: Amount of non-premium currency.
        total_game_events:
          type: integer
          description: Number of in-game events the player took part in.
        total_gifts:
          type: integer
          description: Number of in-game gifts the player has sent/received.
        tutorial_completed:
          type: boolean
          description: Whether the player has completed the game’s tutorial.
        completed_tasks:
          type: integer
          description: Number of tasks/objectives completed.
        items_used:
          type: boolean
          description: Whether the player uses purchased in-game items.
        pvp_activity:
          type: boolean
          description: >-
            Whether the player takes part in PvP (Player(s) versus player(s))
            battles.
        total_clans:
          type: integer
          description: Number of clans the player is a member of.
        unlocked_achievements:
          type: integer
          description: Number of achievements unlocked.
        total_inventory_value:
          type: number
          format: float
          description: Total inventory value (in-game currency).
        character_customized:
          type: boolean
          description: Whether the player has customized their character.
        session_time:
          type: string
          description: >-
            Average session time per [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
    token:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/user'
        settings:
          $ref: '#/components/schemas/settings'
        purchase:
          $ref: '#/components/schemas/purchase'
        custom_parameters:
          $ref: '#/components/schemas/custom_parameters'
      example:
        settings:
          currency: USD
          language: en
          project_id: 16184
          ui:
            size: medium
        user:
          email:
            value: email@example.com
          id:
            value: user_2
          name:
            value: John Smith
    mock_code:
      type: integer
      description: >-
        An error code that you want to reproduce when testing the payment
        process via PayPal in sandbox mode. It works correctly only if you pass
        the `"mode":"sandbox"` parameter.
      enum:
        - 1057
        - 1015
        - 3006
        - 1801
        - 1803
        - 1039
        - 3031
        - 1203
        - 3006
        - 1201
        - 1002
        - 1089
        - 2031
        - 1046
        - 5004
    status.enum:
      type: string
      enum:
        - created
        - processing
        - review
        - error
        - done
        - awaitingRefund
        - refunded
        - canceled
        - partiallyRefunded
      x-enumDescriptions:
        created: The user initiated the transaction but it has not been processed yet.
        processing: The transaction is being processed.
        review: >-
          Transaction processing has been suspended by the anti-fraud system,
          and the transaction is currently under additional verification.
        error: >-
          An error occurred while processing the transaction. Such payments can
          be refunded by contacting Xsolla customer support.
        done: The transaction was successfully processed.
        awaitingRefund: >-
          The transaction is awaiting a decision on refund. After the user
          requested a refund, Xsolla customer support manually processes the
          request and makes a decision on the refund.
        refunded: A refund was made to the user’s Xsolla balance.
        canceled: |-
          There are two possible scenarios:
            - The transaction has been canceled on the payment system’s side. For example, there were insufficient funds in user account.
            - The payment was refunded to the user.
        partiallyRefunded: The user received a partial refund.
    empty-body:
      type: object
      nullable: true
      description: For the API call to work correctly, the request body must be empty.
  requestBodies:
    charge-with-saved-account:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              user:
                type: object
                description: User details.
                required:
                  - ip
                properties:
                  ip:
                    type: string
                    description: User IP address.
                  name:
                    type: string
                    description: Username.
                  legal:
                    $ref: '#/components/schemas/legal'
              settings:
                type: object
                description: Object containing purchase settings.
                properties:
                  currency:
                    $ref: '#/components/schemas/currency'
                  external_id:
                    $ref: '#/components/schemas/external_id'
                  mode:
                    type: string
                    description: >-
                      Set to `sandbox` to test out the payment process. Remove
                      the parameter for real payments.
                  mock_code:
                    $ref: '#/components/schemas/mock_code'
              purchase:
                type: object
                description: Object containing purchase details.
                properties:
                  description:
                    type: object
                    maxLength: 4000
                    properties:
                      value:
                        type: string
                  virtual_currency:
                    type: object
                    description: Object containing virtual currency details.
                    properties:
                      quantity:
                        type: number
                        format: float
                        description: Purchase amount in the virtual currency.
                  checkout:
                    type: object
                    description: Object containing checkout details.
                    properties:
                      currency:
                        type: string
                        description: >-
                          Currency of the purchase. Three-letter currency code
                          per [ISO
                          4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/).
                      amount:
                        type: number
                        format: float
                        description: Purchase amount.
              custom_parameters:
                $ref: '#/components/schemas/custom_parameters'
          example:
            purchase:
              description:
                value: currency purchase
              virtual_currency:
                quantity: 100
            settings:
              currency: USD
              external_id: ext123
              mode: sandbox
            user:
              ip: 111.11.11.11
              name: John Smith
              legal:
                name: My Awesome Company
                address: 17 Crown Street London SW2 0JW United Kingdom
                vat_id: GB111111111
                country: GB
