spintax-net Billing API

openapi: 3.2.0
info:
  title: clx management Billing API
  version: 0.8.0
  description: 'The /v1 API of clx (docs/spec.md §15). The clx.cx page is a thin client over the same endpoints.

    Authorization: `Bearer ` from a signed-in page, or `Bearer clx_…` — an API key

    (one on the `free` plan, up to 5 on `api`). Every POST, PUT, PATCH and DELETE takes an `Idempotency-Key` header, required

    with an API key; a repeat with the same body replays the first answer for 24 hours.

    Errors: `{ "error": { "code", "message", "details"? } }`. This file grows with each stage; a

    test checks that every route in the code is here and back.'
servers:
- url: https://clx.cx
security:
- bearer: []
tags:
- name: Billing
paths:
  /v1/billing:
    get:
      summary: The balance, Pro and the last 50 journal rows (scope billing)
      description: 'Money is integer micro-USD (1 USD = 1,000,000). Pro — the `api` plan — is $9 per 30 days,

        charged by the UTC day from the balance (docs/spec.md §18).'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Billing'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Billing
      operationId: getV1Billing
      x-operation-id-source: derived
  /v1/billing/invoices:
    post:
      summary: A crypto top-up (scope billing)
      description: 'Whole dollars, 9 to 1,000, in one of four coins; at most 3 pending whose hour has not run out (`invoice_limit`).

        The answer has the address and the exact amount to send, fees included, for an hour; what

        arrives is credited, partial payments go to an operator. Needs a confirmed e-mail.

        `payments_unavailable` when the processor is not set up or did not answer. Telegram Stars

        are paid in the bot (/pay), not here.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - usd
              - coin
              properties:
                usd:
                  type: integer
                  minimum: 9
                  maximum: 1000
                coin:
                  type: string
                  enum:
                  - USDT_TRC20
                  - USDT_BSC
                  - USDT_ERC20
                  - USDC_ERC20
      responses:
        '201':
          description: Made
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Billing
      operationId: postV1BillingInvoices
      x-operation-id-source: derived
  /v1/billing/invoices/{id}:
    get:
      summary: A top-up and its state (scope billing)
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Billing
      operationId: getV1BillingInvoicesById
      x-operation-id-source: derived
  /v1/billing/refunds:
    post:
      summary: Ask for a refund of a top-up (page session only)
      description: 'A credited top-up under 90 days old, one open request per top-up (`refund_open`). An

        operator makes it: at most what that top-up brought in less what was refunded from it, and

        never more than the balance. Crypto goes, less the network fee, to `address` — yours, on the

        network the top-up came by (Tron for USDT_TRC20, an 0x address for the others); Stars go back

        whole, in Telegram, with no address.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - invoice_id
              properties:
                invoice_id:
                  type: string
                address:
                  type: string
      responses:
        '201':
          description: Asked
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund:
                    $ref: '#/components/schemas/Refund'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Billing
      operationId: postV1BillingRefunds
      x-operation-id-source: derived
  /v1/billing/pro:
    post:
      summary: Switch Pro on or off (scope billing)
      description: 'On needs a confirmed e-mail and at least $9 on the balance (`insufficient_balance`), and

        charges today; a day is charged once, however often Pro is switched. Off ends Pro after today

        (or at its first unpaid day, which is then not owed); the account returns to free and what is

        beyond its limits is paused, not deleted.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - 'on'
              properties:
                'on':
                  type: boolean
      responses:
        '200':
          description: Switched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Billing'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Billing
      operationId: postV1BillingPro
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: 'Stable codes: unauthorized, invalid_request, not_found, payload_too_large,

                limit_reached, service_full, idempotency_conflict, operation_in_progress,

                scope_required, session_required, key_already_issued,

                account_taken, already_connected, account_not_ready, invalid_bootstrap,

                bootstrap_permission_error, permission_catalog, orphan_not_deleted,

                token_rights_mismatch, token_check_failed, renew_lost, rate_limited, cloudflare_unavailable,

                not_configured, internal. In an account''s or operation''s `error` (the install, §4):

                name_taken, resource_drift, cron_limit, permission_error, revoked, self_check_timeout,

                credentials_missing, credentials_unreadable (clx cannot open the stored token),

                cloudflare_error. Sites: zone_not_found, site_exists, route_conflict, site_not_active,

                update_required (external sites need a newer clx-edge),

                route_not_ours (a route clx made was changed outside clx and left in place).

                Sign-up: email_unconfirmed (POST /v1/accounts before the address is confirmed),

                invalid_password, balance_not_empty (DELETE /v1/me while money is on the balance or the partner wallet or still moving, §18).

                Billing (docs/spec.md §18): insufficient_balance (Pro needs $9 on the balance), invoice_limit (3 pending top-ups),

                payments_unavailable (crypto top-ups not set up or the processor down),

                refund_unavailable (a top-up never credited, older than 90 days or refunded

                already), refund_open (a refund of that top-up is asked for already), paused (an

                object beyond the free plan''s limits: it can be read and deleted, not changed).

                Links: link_exists (the code is taken on that link host), link_host_not_ready (links go

                on an active host only), link_host_in_use

                (DELETE /v1/link-hosts/{id} while live links are on it). In a link host''s `error`:

                dns_record_exists (the named host already has a DNS record — never taken over),

                domain_taken (another worker''s custom domain), domain_not_ours.

                '
            message:
              type: string
            details:
              type: object
    Billing:
      type: object
      properties:
        balance_micro_usd:
          type: integer
        pro:
          type: object
          properties:
            'on':
              type: boolean
              description: Pro is on — paid, or given by an operator
            given:
              type: boolean
              description: 'given by an operator: never charged'
            since:
              type:
              - string
              - 'null'
              format: date
              description: the first day of the open period
            paid_through:
              type:
              - string
              - 'null'
              format: date
              description: the last day of the unbroken run of paid days
            grace_until:
              type:
              - string
              - 'null'
              format: date-time
              description: 'a day is unpaid: Pro works until then; still unpaid, the account returns to free'
            price_micro_usd:
              type: integer
              description: 9,000,000 — per 30 days
            day_micro_usd:
              type: integer
              description: 300,000 — what a day costs
        journal:
          type: array
          description: the last 50 rows, newest first
          items:
            type: object
            properties:
              id:
                type: integer
              type:
                type: string
                enum:
                - deposit
                - charge
                - bonus
                - adjustment
                - refund
                - partner_transfer
              amount_micro_usd:
                type: integer
                description: negative for a charge or a refund
              day:
                type:
                - string
                - 'null'
                format: date
                description: the day a charge pays
              invoice_id:
                type:
                - string
                - 'null'
              note:
                type:
                - string
                - 'null'
              at:
                type: string
                format: date-time
        invoices:
          type: array
          description: the last 10 top-ups, newest first
          items:
            allOf:
            - $ref: '#/components/schemas/Invoice'
            - type: object
              properties:
                refundable_micro_usd:
                  type: integer
                  description: 'what a refund request may still take from this top-up: under 90 days old, something left, no request open; 0 otherwise'
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
          description: the last 10 refund requests, newest first
    Refund:
      type: object
      properties:
        id:
          type: string
        invoice_id:
          type: string
          description: the top-up refunded
        rail:
          type: string
          enum:
          - crypto
          - stars
        address:
          type:
          - string
          - 'null'
          description: where crypto goes; null for Stars
        status:
          type: string
          enum:
          - requested
          - pending
          - done
          - declined
          description: 'pending: taken from the balance, on its way'
        amount_micro_usd:
          type:
          - integer
          - 'null'
          description: taken from the balance, once an operator made it; crypto is sent less the network fee
        txid:
          type:
          - string
          - 'null'
          description: the crypto transfer, once sent
        created_at:
          type: string
          format: date-time
        settled_at:
          type:
          - string
          - 'null'
          format: date-time
    Invoice:
      type: object
      properties:
        id:
          type: string
        rail:
          type: string
          enum:
          - crypto
          - stars
        usd_micro_usd:
          type: integer
          description: the nominal; what is credited is what arrived
        coin:
          type: string
          description: USDT_TRC20, USDT_BSC, USDT_ERC20, USDC_ERC20; XTR for Stars
        coin_label:
          type: string
        stars:
          type:
          - integer
          - 'null'
        status:
          type: string
          enum:
          - pending
          - paid
          - expired
          - review
          - void
          description: expired may still turn paid if crypto comes late (checked for 30 days); review waits for an operator
        address:
          type:
          - string
          - 'null'
          description: 'where to send, while pending — null when the processor gave no whole quote: use pay_url'
        amount:
          type:
          - string
          - 'null'
          description: the exact amount of the coin to send, fees included, while pending
        pay_url:
          type:
          - string
          - 'null'
          description: the processor's own payment page, while pending
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        paid_at:
          type:
          - string
          - 'null'
          format: date-time
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 200
        pattern: ^[!-~]{1,200}$
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,64}$
        description: 'an id of clx: 22 characters of base64url'
  responses:
    Error:
      description: An error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer