openapi: 3.0.3
info:
  version: v1.0.3
  title: LE-KO Pay
  license:
    name: private
    url: https://le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO Payment
servers:
  - url: https://payment-{env}.le-ko.deggex.com/{basePath}
    description: Payments endpoint
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: pay
    description: Pay
paths:
  /earnings:
    get:
      operationId: getEarnings
      summary: .../earnings
      description: ✨ Get earnings
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CoachUserId'
        - $ref: '#/components/parameters/CoolDownDays'
      responses:
        '200':
          description: Earnings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Earnings'
        '400':
          $ref: '#/components/responses/400'
  /recipients:
    get:
      operationId: getRecipients
      summary: .../recipients
      description: ✨ Get recipients
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CoachUserId'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageLimit'
      responses:
        '200':
          description: List of Recipients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientsPage'
        '400':
          $ref: '#/components/responses/400'
    post:
      operationId: createRecipient
      summary: .../recipients
      description: ✨ Create new Recipient
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CoachUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientCreate'
      responses:
        '200':
          description: Recipient created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '400':
          $ref: '#/components/responses/400'
  /recipients/{recipientId}:
    get:
      operationId: getRecipientById
      summary: .../recipients/{id}
      description: ✨ Get Recipient by id
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/RecipientId'
        - $ref: '#/components/parameters/CoachUserId'
      responses:
        '200':
          description: Recipient details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '400':
          $ref: '#/components/responses/400'
    put:
      operationId: updateRecipient
      summary: .../recipients/{id}
      description: ✨ Update Recipient
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/RecipientId'
        - $ref: '#/components/parameters/CoachUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientCreate'
      responses:
        '200':
          description: Recipient updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '400':
          $ref: '#/components/responses/400'
  /payments:
    get:
      operationId: getPayments
      summary: .../payments
      description: ✨ Get payments
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/AthleteUserId'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: List of User Payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsPage'
        '400':
          $ref: '#/components/responses/400'
    post:
      operationId: createPayment
      summary: .../payments
      description: ✨ Create new Payment
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/AthleteUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreate'
      responses:
        '200':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/400'
  /payments/{paymentId}:
    get:
      operationId: getPaymentById
      summary: .../payments/{id}
      description: ✨ Get Payment by id
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/PaymentId'
        - $ref: '#/components/parameters/IncludeOperation'
        - $ref: '#/components/parameters/AthleteUserId'
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/400'
  /payments/{paymentId}/refund:
    post:
      operationId: refundPayment
      summary: .../payments/{id}/refund
      description: ✨ Refund Payment
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/PaymentId'
        - $ref: '#/components/parameters/AthleteUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRefund'
      responses:
        '200':
          description: Payment refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '400':
          $ref: '#/components/responses/400'
  /payments/{paymentId}/capture:
    post:
      operationId: capturePayment
      summary: .../payments/{id}/capture
      description: ✨ Capture Payment
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/PaymentId'
        - $ref: '#/components/parameters/AthleteUserId'
      responses:
        '200':
          description: Payment capture
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capture'
        '400':
          $ref: '#/components/responses/400'
  /remittances:
    post:
      operationId: createRemittance
      summary: .../remittances
      description: ✨ Create new Remittance
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CoachUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemittanceCreate'
      responses:
        '200':
          description: Remittance created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Remittance'
        '400':
          $ref: '#/components/responses/400'
  /remittances/{remittanceId}:
    get:
      operationId: getRemittanceById
      summary: .../remittances/{remittanceId}
      description: ✨ Get Remittance by id
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/RemittanceId'
        - $ref: '#/components/parameters/CoachUserId'
      responses:
        '200':
          description: Remittance details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Remittance'
        '400':
          $ref: '#/components/responses/400'
  /operations:
    get:
      operationId: getOperations
      summary: .../operations
      description: ✨ Get operations
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CoachUserId'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
        - $ref: '#/components/parameters/OperationType'
      responses:
        '200':
          description: List of User Operations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationsPage'
        '400':
          $ref: '#/components/responses/400'
  /operations/{operationId}:
    get:
      operationId: getOperationById
      summary: .../operations/{id}
      description: ✨ Get operation by id
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CoachUserId'
        - $ref: '#/components/parameters/OperationId'
      responses:
        '200':
          description: Operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        '400':
          $ref: '#/components/responses/400'
  /settings:
    get:
      operationId: getSettings
      summary: .../settings
      description: ✨ Get settings
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/Name'
      responses:
        '200':
          description: Settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllSettings'
        '400':
          $ref: '#/components/responses/400'
  /callbacks:
    get:
      operationId: getCallback
      summary: .../callbacks
      description: ✨ Callback
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CallbackType'
        - $ref: '#/components/parameters/CallbackStatus'
        - $ref: '#/components/parameters/TrackingId'
      responses:
        '200':
          description: Callback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Callback'
        '400':
          $ref: '#/components/responses/400'
    post:
      operationId: postCallback
      summary: .../callbacks
      description: ✨ Callback
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/CallbackType'
        - $ref: '#/components/parameters/CallbackStatus'
        - $ref: '#/components/parameters/TrackingId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackBody'
      responses:
        '200':
          description: Callback posted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Callback'
        '400':
          $ref: '#/components/responses/400'
  /prices:
    post:
      operationId: calculatePrice
      summary: .../prices
      description: ✨ Calculate price
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/AthleteUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceRequest'
      responses:
        '200':
          description: Total price breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotalPrice'
        '400':
          $ref: '#/components/responses/400'
  /upstreams:
    get:
      operationId: getUpstreams
      summary: .../upstreams
      description: ✨ Get upstreams
      tags:
        - pay
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/UpstreamName'
      responses:
        '200':
          description: Upstreams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamPage'
        '400':
          $ref: '#/components/responses/400'
  /documents:
    get:
      operationId: getDocuments
      summary: .../documents
      description: ✨ Get documents by type and filters
      tags:
        - pay
      parameters:
        - name: type
          in: query
          required: true
          schema:
            type: string
            enum:
              - act
          description: Document type filter
        - name: order_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter documents by order ID
        - name: session_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter documents by session ID
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageLimit'
      responses:
        '200':
          description: List of Documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsPage'
        '400':
          $ref: '#/components/responses/400'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CoachId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Coach ID - user who receives money
      format: uuid
    CoolDownDays:
      type: integer
      example: 6
      description: The number of days ago to calculate the time period, defaults to 6 for col down period.
      format: integer
    Amount:
      type: string
      pattern: ^\d+?( [A-Z]{3})?$
      example: 100 RUB
      description: The monetary amount as a string rounded to whole, without decimal places with optional currency code.
      format: string
    FirstPaymentCreatedAt:
      type: string
      format: date-time
      description: First payment date in a period. RFC-3339 format.
      example: '2024-11-29T12:09:53+00:00'
    LastPaymentCreatedAt:
      type: string
      format: date-time
      description: Last payment date in a period. RFC-3339 format.
      example: '2024-11-29T12:09:53+00:00'
    DateTime:
      type: string
      format: date-time
      description: Date and time in RFC-3339
      example: '2024-11-29T12:09:53+00:00'
    TimePeriod:
      type: object
      description: A time period since the last remittance (or since sign up) and the date minus cool down days, defaults to 6 days ago.
      required:
        - start
        - end
      properties:
        start:
          $ref: '#/components/schemas/DateTime'
        end:
          $ref: '#/components/schemas/DateTime'
    Balance:
      type: object
      required:
        - amount
        - firstPaymentCreatedAt
        - lastPaymentCreatedAt
        - timePeriod
      description: Balance for a period.
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        firstPaymentCreatedAt:
          $ref: '#/components/schemas/FirstPaymentCreatedAt'
        lastPaymentCreatedAt:
          $ref: '#/components/schemas/LastPaymentCreatedAt'
        timePeriod:
          $ref: '#/components/schemas/TimePeriod'
    Earnings:
      type: object
      required:
        - coachId
        - totalBalance
        - availableBalance
        - coolDownDays
        - thresholdAmount
        - overrideThresholdPlatformFeeAmount
      description: Earnings for a coach for a period.
      properties:
        coachId:
          $ref: '#/components/schemas/CoachId'
        totalBalance:
          $ref: '#/components/schemas/Balance'
        availableBalance:
          $ref: '#/components/schemas/Balance'
        thresholdAmount:
          $ref: '#/components/schemas/Amount'
          example: 7000 RUB
        overrideThresholdPlatformFeeAmount:
          $ref: '#/components/schemas/Amount'
        coolDownDays:
          $ref: '#/components/schemas/CoolDownDays'
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          description: Error unique code
          enum:
            - validation
            - internal
            - oops
            - unexpected
            - tooManyRequests
            - notFound
            - unauthorized
            - forbidden
        message:
          type: string
          description: Error message
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    PageNumber:
      type: integer
      description: Page number
      example: 0
      minimum: 0
      default: 0
    Limit:
      type: integer
      description: Page limit
      default: 10
      minimum: 1
      maximum: 100
      example: 10
    Count:
      type: integer
      description: Page entries count
      example: 10
    Total:
      type: integer
      description: Total count
      default: 0
      minimum: 0
      example: 1000
    Page:
      type: object
      required:
        - data
        - count
        - page
        - limit
        - total
      properties:
        data:
          type: array
          items:
            type: object
        count:
          $ref: '#/components/schemas/Count'
        page:
          $ref: '#/components/schemas/PageNumber'
        limit:
          $ref: '#/components/schemas/Limit'
        total:
          $ref: '#/components/schemas/Total'
    RecipientId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Recipient ID
      format: uuid
    RecipientName:
      type: string
      example: IP Bob Johnson's Gym
      description: Recipient name, used to fill in the name field in the payment receipt
      format: text
    RecipientAddress:
      type: string
      example: Saint-Petersburg, Russia
      description: Recipient address, used to fill in the address field in the payment receipt
      format: text
    RecipientPhone:
      type: string
      example: '+79991234567'
      description: Recipient phone number, used to fill in the phone number field in the payment receipt
      format: text
    RecipientEmail:
      type: string
      example: example@email.com
      description: Recipient email, used to fill in the email field in the payment receipt
      format: text
    Inn:
      type: string
      example: '000000000000'
      description: Individual tax payer number
      format: text
    BankCode:
      type: string
      example: '200000000001056'
      description: Bank code (a.k.a BIK)
      format: text
    BankAccountNumber:
      type: string
      example: '1234567890'
      description: Bank account number
      format: text
    BankAccountHolder:
      type: string
      example: John Doe
      description: Bank account holder
      format: text
    Recipient:
      type: object
      required:
        - recipientId
        - coachId
        - inn
        - name
        - address
        - bankCode
        - bankAccountNumber
        - bankAccountHolder
        - createdAt
        - updatedAt
      properties:
        recipientId:
          $ref: '#/components/schemas/RecipientId'
        coachId:
          $ref: '#/components/schemas/CoachId'
        name:
          $ref: '#/components/schemas/RecipientName'
        address:
          $ref: '#/components/schemas/RecipientAddress'
        phone:
          $ref: '#/components/schemas/RecipientPhone'
        email:
          $ref: '#/components/schemas/RecipientEmail'
        inn:
          $ref: '#/components/schemas/Inn'
        bankCode:
          $ref: '#/components/schemas/BankCode'
        bankAccountNumber:
          $ref: '#/components/schemas/BankAccountNumber'
        bankAccountHolder:
          $ref: '#/components/schemas/BankAccountHolder'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
    RecipientsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Recipient'
    RecipientCreate:
      type: object
      required:
        - coachId
        - inn
        - name
        - address
        - bankCode
        - bankAccountNumber
        - bankAccountHolder
      properties:
        coachId:
          $ref: '#/components/schemas/CoachId'
        name:
          $ref: '#/components/schemas/RecipientName'
        address:
          $ref: '#/components/schemas/RecipientAddress'
        phone:
          $ref: '#/components/schemas/RecipientPhone'
        email:
          $ref: '#/components/schemas/RecipientEmail'
        inn:
          $ref: '#/components/schemas/Inn'
        bankCode:
          $ref: '#/components/schemas/BankCode'
        bankAccountNumber:
          $ref: '#/components/schemas/BankAccountNumber'
        bankAccountHolder:
          $ref: '#/components/schemas/BankAccountHolder'
    AthleteId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Athlete ID - user who pays money
      format: uuid
    OrderId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Order ID, uuid or text
      format: text
    PaymentId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Payment ID
      format: uuid
    ExternalId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: External Payment ID
      format: uuid
    Purpose:
      type: string
      example: Training sessions with a coach
      description: Payment Purpose
    PaymentStatus:
      type: string
      example: CREATED
      description: Payment Status
      enum:
        - CREATED
        - PAID
        - REFUNDED
        - FAILED
        - CAPTURED
    PaymentLink:
      type: string
      example: https://merch.example.com/order/?uuid=16ea4c54-bf1d-4e6a-a1ef-53ad55666e43
      description: Payment link, used to redirect the user to the payment page, not empty for just created payments
      format: uri
    ReceiptLink:
      type: string
      example: https://consumer.1-ofd-test.ru/ticket?fn=9999078902015137&fp=1104071615&t=20251015T0021&s=2000.00&i=21099&n=2
      description: Receipt link, used to redirect the user to the receipt page, not empty for paid payments
      format: uri
    OperationData:
      type: object
      description: Payment operation data can be anything, present only if payment requested by id with includeOperation query parameter
    Payment:
      type: object
      required:
        - paymentId
        - externalId
        - orderId
        - athleteId
        - coachId
        - amount
        - purpose
        - status
        - createdAt
      properties:
        paymentId:
          $ref: '#/components/schemas/PaymentId'
        externalId:
          $ref: '#/components/schemas/ExternalId'
        orderId:
          $ref: '#/components/schemas/OrderId'
        athleteId:
          $ref: '#/components/schemas/AthleteId'
        coachId:
          $ref: '#/components/schemas/CoachId'
        amount:
          $ref: '#/components/schemas/Amount'
        purpose:
          $ref: '#/components/schemas/Purpose'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        paymentLink:
          $ref: '#/components/schemas/PaymentLink'
        receiptLink:
          $ref: '#/components/schemas/ReceiptLink'
        operation:
          $ref: '#/components/schemas/OperationData'
        createdAt:
          $ref: '#/components/schemas/DateTime'
    PaymentsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
    ServiceName:
      type: string
      example: Classic yoga session
      description: Service Name
    SessionId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Training session ID, uuid or text
      format: text
    Service:
      type: object
      required:
        - coachDueAmount
        - name
        - sessionId
      properties:
        coachDueAmount:
          $ref: '#/components/schemas/Amount'
        name:
          $ref: '#/components/schemas/ServiceName'
        sessionId:
          $ref: '#/components/schemas/SessionId'
    SendReceiptTo:
      type: string
      example: +79991234567 or example@email.com
      description: Email or phone number to send the receipt to, optional if recipient email or phone number is provided
    PaymentCreate:
      type: object
      required:
        - totalAmount
        - purpose
        - orderId
        - coachId
      properties:
        totalAmount:
          $ref: '#/components/schemas/Amount'
        purpose:
          $ref: '#/components/schemas/Purpose'
        orderId:
          $ref: '#/components/schemas/OrderId'
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
        coachId:
          $ref: '#/components/schemas/CoachId'
        sendReceiptTo:
          $ref: '#/components/schemas/SendReceiptTo'
    PaymentRefund:
      type: object
      required:
        - paymentId
      properties:
        paymentId:
          $ref: '#/components/schemas/PaymentId'
        sessionId:
          $ref: '#/components/schemas/SessionId'
        sendReceiptTo:
          $ref: '#/components/schemas/SendReceiptTo'
    Date:
      type: string
      format: date
      description: Date in RFC-3339 format (YYYY-MM-DD)
      example: '2024-11-29'
    Refund:
      type: object
      required:
        - isRefunded
        - paymentId
        - orderId
        - amount
        - date
      properties:
        isRefunded:
          type: boolean
        paymentId:
          $ref: '#/components/schemas/PaymentId'
        sessionId:
          $ref: '#/components/schemas/SessionId'
        orderId:
          $ref: '#/components/schemas/OrderId'
        amount:
          $ref: '#/components/schemas/Amount'
        date:
          $ref: '#/components/schemas/Date'
    Capture:
      type: object
      required:
        - result
      properties:
        result:
          type: boolean
    AvailableAmount:
      type: string
      example: 100.00 RUB
      description: The available amount of payments to cash out. Taken from earnings object.
      format: string
    RemittanceCreate:
      type: object
      required:
        - coachId
        - availableAmount
        - thresholdOverrideByFee
      properties:
        availableAmount:
          $ref: '#/components/schemas/AvailableAmount'
        thresholdOverrideByFee:
          type: boolean
          description: Whether to override the threshold by fee. Defaults to false. If true, the fee will be deducted from remittance amount.
          default: false
        coachId:
          $ref: '#/components/schemas/CoachId'
    RemittanceId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Remittance ID
      format: uuid
    AmountBreakdown:
      type: object
      required:
        - dueAmount
        - paidAmount
        - feeAmount
      properties:
        dueAmount:
          $ref: '#/components/schemas/Amount'
        paidAmount:
          $ref: '#/components/schemas/Amount'
        feeAmount:
          $ref: '#/components/schemas/Amount'
    RemittanceStatus:
      type: string
      example: WAITING
      description: Remittance Status
      enum:
        - WAITING
        - FAILURE
        - COMPLETE
        - DELETED
    Remittance:
      type: object
      required:
        - remittanceId
        - coachId
        - bankAcc
        - bankBik
        - recipientInn
        - recipientName
        - amountBreakdown
        - thresholdAmount
        - platformFeePercent
        - status
        - createdAt
        - updatedAt
      properties:
        remittanceId:
          $ref: '#/components/schemas/RemittanceId'
        coachId:
          $ref: '#/components/schemas/CoachId'
        bankAcc:
          type: string
          description: Bank account number
        bankBik:
          type: string
          description: Bank BIK number
        recipientInn:
          type: string
          description: Recipient INN number
        recipientName:
          type: string
          description: Recipient name
        amountBreakdown:
          $ref: '#/components/schemas/AmountBreakdown'
        thresholdAmount:
          $ref: '#/components/schemas/Amount'
        platformFeePercent:
          type: number
          description: Platform fee percent
        status:
          $ref: '#/components/schemas/RemittanceStatus'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
    OperationType:
      type: string
      description: The type of the operation/transaction.
      enum:
        - ALL
        - INCOME
        - PAYOUT
    OperationId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Operation ID
      format: uuid
    PaymentOperation:
      type: object
      required:
        - paymentId
        - externalId
        - orderId
        - athleteId
        - amount
        - purpose
        - status
      properties:
        paymentId:
          $ref: '#/components/schemas/PaymentId'
        externalId:
          $ref: '#/components/schemas/ExternalId'
        orderId:
          $ref: '#/components/schemas/OrderId'
        athleteId:
          $ref: '#/components/schemas/AthleteId'
        amount:
          $ref: '#/components/schemas/Amount'
        purpose:
          $ref: '#/components/schemas/Purpose'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        receiptLink:
          $ref: '#/components/schemas/ReceiptLink'
    PayoutId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Payout ID
      format: uuid
    RemittanceOperation:
      type: object
      required:
        - remittanceId
        - coachId
        - amount
        - status
        - orderIds
        - payoutIds
        - paymentIds
        - createdAt
        - updatedAt
      properties:
        remittanceId:
          $ref: '#/components/schemas/RemittanceId'
        coachId:
          $ref: '#/components/schemas/CoachId'
        amount:
          $ref: '#/components/schemas/Amount'
        status:
          $ref: '#/components/schemas/RemittanceStatus'
        orderIds:
          type: array
          items:
            $ref: '#/components/schemas/OrderId'
        payoutIds:
          type: array
          items:
            $ref: '#/components/schemas/PayoutId'
        paymentIds:
          type: array
          items:
            $ref: '#/components/schemas/PaymentId'
        createdAt:
          $ref: '#/components/schemas/DateTime'
    Operation:
      type: object
      required:
        - operationId
        - operationType
        - coachId
        - createdAt
        - updatedAt
      properties:
        operationId:
          $ref: '#/components/schemas/OperationId'
        operationType:
          $ref: '#/components/schemas/OperationType'
        coachId:
          $ref: '#/components/schemas/CoachId'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
        operation:
          oneOf:
            - $ref: '#/components/schemas/PaymentOperation'
            - $ref: '#/components/schemas/RemittanceOperation'
    OperationsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Operation'
    Name:
      type: string
      example: cool-setting
      description: Setting Name
    SettingId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Setting ID
      format: uuid
    Values:
      type: object
      example:
        key1: value1
        key2: value2
      description: Settings values as map
    Settings:
      type: object
      required:
        - id
        - name
        - values
        - active
        - createdAt
        - updatedAt
      description: Settings object.
      properties:
        id:
          $ref: '#/components/schemas/SettingId'
        name:
          $ref: '#/components/schemas/Name'
        values:
          $ref: '#/components/schemas/Values'
        active:
          type: boolean
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
    AllSettings:
      type: object
      required:
        - settings
      properties:
        settings:
          type: array
          items:
            $ref: '#/components/schemas/Settings'
    CallbackType:
      type: string
      description: The type of the callback.
      enum:
        - PAYMENT
        - RECEIPT
    CallbackStatus:
      type: string
      description: The status of the callback.
      enum:
        - SUCCESS
        - FAILURE
    TrackingId:
      type: string
      example: tracking_123
      description: Tracking ID
      format: text
    Callback:
      type: object
      required:
        - status
        - callbackType
        - trackingId
      properties:
        callbackType:
          $ref: '#/components/schemas/CallbackType'
        status:
          $ref: '#/components/schemas/CallbackStatus'
        trackingId:
          $ref: '#/components/schemas/TrackingId'
    CallbackBody:
      type: object
      description: The payload of the callback.
    PriceRequest:
      type: object
      required:
        - orderId
        - services
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
    ExactAmount:
      type: string
      pattern: ^\d+(?:\.\d{2})?( [A-Z]{3})?$
      example: 100.12 RUB
      description: The monetary amount as a string with two decimal places with optional currency code.
      format: string
    PlatformFeePercentage:
      type: string
      description: |
        The fee percentage.
      format: string
      example: '3.3355'
    VatPercentage:
      type: string
      description: |
        The VAT percentage. Example: 20.00
      format: string
      example: '20.00'
    ServicePrice:
      type: object
      required:
        - sessionId
        - name
        - coachDueAmount
        - platformFeeAmount
        - totalAmount
        - vatAmount
        - vatPercentage
        - platformFeePercentage
      properties:
        sessionId:
          $ref: '#/components/schemas/SessionId'
        name:
          $ref: '#/components/schemas/ServiceName'
        coachDueAmount:
          $ref: '#/components/schemas/Amount'
        platformFeeAmount:
          $ref: '#/components/schemas/Amount'
        totalAmount:
          $ref: '#/components/schemas/Amount'
        vatAmount:
          $ref: '#/components/schemas/ExactAmount'
        vatPercentage:
          $ref: '#/components/schemas/VatPercentage'
        platformFeePercentage:
          $ref: '#/components/schemas/PlatformFeePercentage'
    TotalPrice:
      type: object
      required:
        - orderId
        - coachDueAmount
        - platformFeeAmount
        - totalAmount
        - servicesPrices
        - platformFeePercentage
        - vatPercentage
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'
        coachDueAmount:
          $ref: '#/components/schemas/ExactAmount'
        platformFeeAmount:
          $ref: '#/components/schemas/ExactAmount'
        totalAmount:
          $ref: '#/components/schemas/ExactAmount'
        vatAmount:
          $ref: '#/components/schemas/ExactAmount'
        platformFeePercentage:
          $ref: '#/components/schemas/PlatformFeePercentage'
        vatPercentage:
          $ref: '#/components/schemas/VatPercentage'
        servicesPrices:
          type: array
          items:
            $ref: '#/components/schemas/ServicePrice'
    UpstreamName:
      type: string
      example: tochka_acquiring
      enum:
        - tochka_acquiring
        - firstofd
        - tochka_b2b_registry
    Id:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Upstream ID
      format: uuid
    Payload:
      type: object
      example:
        key1: value1
        key2: value2
      description: Settings values as map
    Upstream:
      type: object
      required:
        - id
        - name
        - trackingId
        - request
        - response
        - method
        - scheme
        - host
        - path
        - query
        - statusCode
        - createdAt
      description: Earning is total payment amounts for a period.
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          $ref: '#/components/schemas/UpstreamName'
        trackingId:
          $ref: '#/components/schemas/TrackingId'
        request:
          $ref: '#/components/schemas/Payload'
        response:
          $ref: '#/components/schemas/Payload'
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - DELETE
        scheme:
          type: string
        host:
          type: string
        path:
          type: string
        query:
          type: string
        statusCode:
          type: number
        createdAt:
          $ref: '#/components/schemas/DateTime'
    UpstreamPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Upstream'
    Document:
      type: object
      required:
        - id
        - eventId
        - bookingId
        - coachId
        - documentType
        - s3Key
        - fileName
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Document ID
        eventId:
          type: string
          format: uuid
          description: Event ID
        bookingId:
          type: string
          format: uuid
          description: Booking ID
        coachId:
          $ref: '#/components/schemas/CoachId'
        athleteId:
          type: string
          format: uuid
          description: Athlete ID
          nullable: true
        documentType:
          type: string
          enum:
            - act_coach
            - act_athlete
          description: Type of document
        s3Key:
          type: string
          description: S3 storage key
        fileName:
          type: string
          description: Original file name
        downloadUrl:
          type: string
          format: uri
          description: URL to download the document
        createdAt:
          $ref: '#/components/schemas/DateTime'
    DocumentsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Document'
  parameters:
    CoachUserId:
      name: x-current-user-id
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/CoachId'
    CoolDownDays:
      name: cool_down_days
      in: query
      required: false
      description: The number of days ago to calculate the time period, defaults to 6 for col down period.
      schema:
        $ref: '#/components/schemas/CoolDownDays'
    PageNumber:
      name: page
      required: false
      in: query
      schema:
        $ref: '#/components/schemas/PageNumber'
    PageLimit:
      name: limit
      required: false
      in: query
      schema:
        $ref: '#/components/schemas/Limit'
    RecipientId:
      name: recipientId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/RecipientId'
    AthleteUserId:
      name: x-current-user-id
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/AthleteId'
    OrderId:
      name: orderId
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/OrderId'
    PaymentId:
      name: paymentId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/PaymentId'
    IncludeOperation:
      name: includeOperation
      in: query
      required: false
      schema:
        type: boolean
        default: false
    RemittanceId:
      name: remittanceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/RemittanceId'
    StartDate:
      name: start_date
      in: query
      required: false
      description: The start date, defaults to current week start.
      schema:
        $ref: '#/components/schemas/Date'
    EndDate:
      name: end_date
      in: query
      required: false
      description: The end date, defaults to today.
      schema:
        $ref: '#/components/schemas/Date'
    OperationType:
      name: type
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/OperationType'
    OperationId:
      name: operationId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/OperationId'
    Name:
      name: name
      in: query
      required: false
      description: The setting name.
      schema:
        $ref: '#/components/schemas/Name'
    CallbackType:
      name: callback_type
      in: query
      required: true
      description: The type of the callback.
      schema:
        type: string
        $ref: '#/components/schemas/CallbackType'
    CallbackStatus:
      name: status
      in: query
      required: true
      description: The status of the operation.
      schema:
        type: string
        $ref: '#/components/schemas/CallbackStatus'
    TrackingId:
      name: tracking_id
      in: query
      required: true
      description: The tracking ID of the callback.
      schema:
        type: string
        $ref: '#/components/schemas/TrackingId'
    UpstreamName:
      name: name
      in: query
      required: true
      description: The upstream name.
      schema:
        $ref: '#/components/schemas/UpstreamName'
  responses:
    '400':
      description: Bad Request, the request is not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
            example:
              errors:
                - code: 400
                  message: The request is not valid