openapi: 3.0.3
info:
  title: Account API
  description: "In order to start using the Account API, you must have an API key, which you can generate in the client panel. Each API key has independent permissions assigned to it."
  version: 1.0.0
servers:
  - url: https://cluster.cashbill.pl/api.php
    description: PROD API
tags:
  - name: test
    description: Test
    x-displayName: Test Resource
  - name: account
    description: Account Resource
    x-displayName: Account Resource
  - name: refund
    description: Refund Resource
    x-displayName: Refund Resource
  - name: Nonce Resource
    description: Nonce Resource
paths:
  /test/ping/{msg}:
    get:
      tags:
        - test
      summary: Test the REST connection.
      description: Returns the same message it receives.
      parameters:
        - name: msg
          in: path
          description: Test message
          required: true
          schema:
            type: string
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/String"
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /payments/getbalance:
    get:
      tags:
        - account
      summary: Retrieves information about the current balance of the account.
      description: The current balance of the account in PLN.
      parameters:
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Float"
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /payments/withdraw:
    post:
      tags:
        - account
      summary: Payout all funds.
      description: The payment will be made to the bank account defined in the CashBill panel.
      parameters:
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PayoutOrder"
      responses:
        "200":
          description: Response status 200 is confirmation that request was obtain. By using the Nonce Resource it is possible to check the request additionally.
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /payments/withdrawamount:
    post:
      tags:
        - account
      summary: Payout specific value of funds.
      description: The payment will be made to the bank account defined in the CashBill panel.
      parameters:
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PayoutAmountOrder"
      responses:
        "200":
          description: Response status 200 is confirmation that request was obtain. By using the Nonce Resource it is possible to check the request additionally.
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /payments/refund:
    post:
      tags:
        - refund
      summary: Refund order for the transaction.
      description: Refund request for the transaction must contain a unique nonce. Refund requests with the same nonce will be rejected.
      parameters:
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/RefundOrder"
      responses:
        "200":
          description: Identifier of the ordered refund
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/String"
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /payments/refund/{refundId}:
    get:
      tags:
        - refund
      summary: Retrieves information about the refund status.
      description: There are 3 possible values ok, err and pending.
      parameters:
        - name: refundId
          in: path
          description: Refund ID
          required: true
          schema:
            type: string
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Refund status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefundStatus"
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /nonce/status/{nonce}:
    get:
      tags:
        - Nonce Resource
      summary: Verifying the correctness of the executed order.
      description: |
        Most operations require a unique operation identifier (nonce) to control the execution of the operation and to provide error handling in the event of connection problems.
        :::note
        Unique identifiers are valid for one hour.
        :::
      parameters:
        - name: key
          in: query
          description: API key
          required: true
          schema:
            type: string
        - name: nonce
          in: path
          description: Unique nonce
          required: true
          schema:
            $ref: "#/components/schemas/Nonce"
      responses:
        "200":
          description: There are 3 possible values done (order executed), error (runtime error) and null (unknown or expired nonce).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/String"
        default:
          description: API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    String:
      type: string
    Float:
      type: number
    Nonce:
      description: Nonce is unique identifier to control the execution of the operation and to provide error handling in the event of connection problems. Unique identifiers are valid for one hour.
      type: string
    RefundStatus:
      type: object
      properties:
        status:
          description: Refund status
          type: string
          enum:
            - ok
            - err
            - pending
    RefundOrder:
      required:
        - nonce
        - orderId
        - amount
      type: object
      properties:
        nonce:
          $ref: "#/components/schemas/Nonce"
        orderId:
          description: Transaction identifier
          type: string
        amount:
          description: Float amount to return
          type: number
          format: float
    PayoutOrder:
      required:
        - nonce
      type: object
      properties:
        nonce:
          $ref: "#/components/schemas/Nonce"
    PayoutAmountOrder:
      required:
        - nonce
        - amount
      type: object
      properties:
        nonce:
          $ref: "#/components/schemas/Nonce"
        amount:
          description: Float amount to payout
          type: number
          format: float
    ErrorMessage:
      type: object
      properties:
        message:
          type: string
    Error:
      type: object
      properties:
        error:
          $ref: "#/components/schemas/ErrorMessage"