openapi: 3.1.0
info:
  title: Freeconomy Payments API
  version: "1.0.0"
  description: >
    Minimal reference for the Freeconomy custodial payments API. All amounts are
    integer minor units (amountMinor). Money movement and custody run inside the
    regulated perimeters of licensed EMI/PI and CASP/VASP partners; this API is
    the integration surface for onboarded, KYC/KYB-verified clients.
servers:
  - url: https://app.freeconomy.shop/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Payments
  - name: Payouts
  - name: Balances
paths:
  /payments:
    post:
      tags: [Payments]
      summary: Create a payment
      description: >
        Create a payment (collection) intent. Supply an Idempotency-Key header;
        retries with the same key return the original result.
      operationId: createPayment
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreate'
      responses:
        '201':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /payments/{id}:
    get:
      tags: [Payments]
      summary: Retrieve a payment
      operationId: getPayment
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, example: "pay_9f2a71c4" }
      responses:
        '200':
          description: The payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /payouts:
    post:
      tags: [Payouts]
      summary: Create a payout
      description: >
        Request a settlement payout in USDC (default), USDT (where available,
        subject to policy) or USD. Supply an Idempotency-Key header.
      operationId: createPayout
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutCreate'
      responses:
        '201':
          description: Payout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /balances:
    get:
      tags: [Balances]
      summary: List balances
      description: Current balances per currency, in integer minor units.
      operationId: listBalances
      responses:
        '200':
          description: Balances
          content:
            application/json:
              schema:
                type: object
                properties:
                  balances:
                    type: array
                    items: { $ref: '#/components/schemas/Balance' }
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: Client-generated key; retries with the same key are safe.
      schema: { type: string, example: "9d1c8f2e-3b47-4a1e-9c2a-77f0b5a1e9d0" }
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Currency:
      type: string
      enum: [RUB, USD, USDC, USDT]
      description: USDC is the default settlement currency; USDT is subject to policy.
    PaymentCreate:
      type: object
      required: [amountMinor, currency]
      properties:
        amountMinor:
          type: integer
          format: int64
          description: Amount in integer minor units (e.g. kopecks, cents).
          example: 1000000
        currency: { $ref: '#/components/schemas/Currency' }
        method:
          type: string
          enum: [sbp, card]
          example: sbp
        reference:
          type: string
          example: "order-4821"
    Payment:
      type: object
      properties:
        id: { type: string, example: "pay_9f2a71c4" }
        status:
          type: string
          enum: [created, pending, paid, review, failed, refunded]
          example: pending
        amountMinor: { type: integer, format: int64, example: 1000000 }
        currency: { $ref: '#/components/schemas/Currency' }
        correlationId:
          type: string
          description: Traces this incoming payment to its outgoing settlement leg.
          example: "cor_1a2b3c4d"
        qr:
          type: string
          nullable: true
          description: SBP dynamic QR payload, when applicable.
        createdAt: { type: string, format: date-time }
    PayoutCreate:
      type: object
      required: [amountMinor, currency, destination]
      properties:
        amountMinor: { type: integer, format: int64, example: 10840 }
        currency: { $ref: '#/components/schemas/Currency' }
        destination:
          type: string
          description: Payout destination (wallet address or account reference).
          example: "0x7390...a1e9"
    Payout:
      type: object
      properties:
        id: { type: string, example: "po_51ab90c2" }
        status:
          type: string
          enum: [created, processing, settled, failed]
          example: processing
        amountMinor: { type: integer, format: int64, example: 10840 }
        currency: { $ref: '#/components/schemas/Currency' }
        createdAt: { type: string, format: date-time }
    Balance:
      type: object
      properties:
        currency: { $ref: '#/components/schemas/Currency' }
        availableMinor: { type: integer, format: int64, example: 2690000 }
        pendingMinor: { type: integer, format: int64, example: 62000 }
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string, example: "invalid_request" }
            message: { type: string, example: "amountMinor must be a positive integer" }