openapi: 3.1.0
info:
  title: Howler API v3 Artists Cashout API
  version: 3.6.1
  description: '*Last updated: 2026-01-20 21:15:49 +0200*

    '
servers:
- url: https://{defaultHost}/api/v3/consumer_portal
  variables:
    defaultHost:
      default: www.howler.co.za
  description: Server for consumer portal endpoints
security:
- bearer_header: []
  bearer_param: []
  api_key: []
  bearer_auth: []
tags:
- name: Cashout
paths:
  /cashless_tags/{cashless_tag_uid}/cashout:
    parameters:
    - name: cashless_tag_uid
      in: path
      description: cashless_tag_uid
      required: true
      schema:
        type: string
    post:
      summary: check event (1)
      operationId: updateConsumerCashoutEvent
      tags:
      - Cashout
      parameters: []
      description: 'Create a new cashless tag pairing for a specific cashless tag and event.

        '
      responses:
        '200':
          description: pair (during event - where cashless_tag does not exist in core)
          content:
            application/json:
              examples:
                Cashless Tag Pairing:
                  value:
                    cashless_tag_pairing:
                      id: 1
                      cashless_tag_uid: '123'
                      status: not_cashed_out
                      event: {}
                      user: {}
                    next_step: /api/v3/consumer_portal/cashless_tags/1234EEEEE/cashout/1/amounts
              schema:
                type: object
                properties:
                  cashless_tag_pairing:
                    $ref: '#/components/schemas/CashlessTagPairing'
                  next_step:
                    type: string
                required:
                - cashless_tag_pairing
        '400':
          description: cashless tag already linked
        '404':
          description: event not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cashless_tag_pairing:
                  type: object
                  properties:
                    event_id:
                      type: integer
                    ticket_id:
                      type: integer
                  required:
                  - event_id
              required:
              - cashless_tag_pairing
            examples:
              cashless_tag_pairing:
                summary: Cashless Tag Pairing
                value:
                  cashless_tag_pairing:
                    event_id: 3
        required: true
  /cashless_tags/{cashless_tag_uid}/cashout/{cashless_tag_pairing_id}/amounts:
    parameters:
    - name: cashless_tag_uid
      in: path
      description: cashless_tag_uid
      required: true
      schema:
        type: string
    - name: cashless_tag_pairing_id
      in: path
      description: cashless_tag_pairing_id
      required: true
      schema:
        type: integer
    put:
      summary: cashout amounts (2)
      operationId: updateConsumerCashoutAmounts
      tags:
      - Cashout
      description: 'Check if the cashless tag pairing can be cashed out and if so retrieve the amounts for the cashouts.


        The amounts include the current balance, estimated cashout fee and refundable balance (balance less fee).

        It is also possible that the user might not have enough remaining balance to cashout.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                Cashless Tag Pairing:
                  value:
                    cashless_tag_pairing:
                      id: 1
                      cashless_tag_uid: '123'
                      status: not_cashed_out
                      event: {}
                      user: {}
                    amounts:
                      balance: 1000
                      fee: 100
                      balance_less_fee: 900
                    next_step: /api/v3/consumer_portal/cashless_tags/1234EEEEE/cashout/1/confirmation
              schema:
                type: object
                properties:
                  cashless_tag_pairing:
                    $ref: '#/components/schemas/CashlessTagPairing'
                  amounts:
                    balance:
                      type: number
                    fee:
                      type: number
                    balance_less_fee:
                      type: number
                  next_step:
                    type: string
                required:
                - cashless_tag_pairing
                - next_step
        '400':
          description: tag paired to someone else
        '404':
          description: cashless tag pairing does not exist
  /cashless_tags/{cashless_tag_uid}/cashout/{cashless_tag_pairing_id}/confirmation:
    parameters:
    - name: cashless_tag_uid
      in: path
      description: cashless_tag_uid
      required: true
      schema:
        type: string
    - name: cashless_tag_pairing_id
      in: path
      description: cashless_tag_pairing_id
      required: true
      schema:
        type: integer
    put:
      summary: confirm cashout (3)
      operationId: updateConsumerCashoutConfirm
      tags:
      - Cashout
      description: 'Confirm that the cashout should be processed.


        The user must have enough balance available and have a bank account set up.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                Cashless Tag Pairing:
                  value:
                    cashless_tag_pairing:
                      id: 1
                      cashless_tag_uid: '123'
                      status: not_cashed_out
                      event: {}
                      user: {}
              schema:
                type: object
                properties:
                  cashless_tag_pairing:
                    $ref: '#/components/schemas/CashlessTagPairing'
                  amounts:
                    balance:
                      type: number
                    fee:
                      type: number
                    balance_less_fee:
                      type: number
                required:
                - cashless_tag_pairing
        '400':
          description: tag paired to someone else
        '404':
          description: cashless tag pairing does not exist
  /cashless_tags/{cashless_tag_uid}/cashout/{cashless_tag_pairing_id}/web/amounts:
    get:
      summary: view amounts
      operationId: showCashlessTagCashoutAmountWeb
      tags:
      - Cashout
      description: '**Private API**

        '
      parameters:
      - name: cashless_tag_uid
        in: path
        description: cashless_tag_uid
        required: true
        schema:
          type: string
      - name: cashless_tag_pairing_id
        in: path
        description: cashless_tag_pairing_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: successful
    put:
      summary: confirm amounts
      operationId: updateCashlessTagCashoutAmountWeb
      tags:
      - Cashout
      description: '**Private API**

        '
      parameters:
      - name: cashless_tag_uid
        in: path
        description: cashless_tag_uid
        required: true
        schema:
          type: string
      - name: cashless_tag_pairing_id
        in: path
        description: cashless_tag_pairing_id
        required: true
        schema:
          type: integer
      responses:
        '302':
          description: successful
components:
  schemas:
    CashlessTagPairing:
      type: object
      properties:
        id:
          type: integer
        event_id:
          type: integer
        cashless_tag_uid:
          type: string
        status:
          type: string
          status:
            type: string
            enum:
            - not_cashed_out
            - cashed_out
            - pending_cash_out
            - pending_pair_and_cash_out
        user:
          $ref: '#/components/schemas/User'
        created_at:
          type: string
          format: ISO 8601
        updated_at:
          type: string
          format: ISO 8601
        cashless_tag_balance:
          $ref: '#/components/schemas/CashlessTagBalance'
      required:
      - id
      - event_id
      - cashless_tag_uid
      - status
      - user
      - created_at
      - updated_at
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Primary Key
        first_name:
          type: string
          description: First Name
        last_name:
          type: string
          description: Last Name
        primary_email:
          type: string
          readOnly: true
          description: Email address of user or dummy user
        dummy?:
          type: boolean
          readOnly: true
          description: True if the user has not yet signed up for an account.
      required:
      - id
      - first_name
      - last_name
      - primary_email
      - dummy?
    CashlessTagBalance:
      type: object
      properties:
        id:
          type: integer
        amount_cents:
          type: integer
        amount_currency:
          type: string
        created_at:
          type: string
          format: ISO 8601
        updated_at:
          type: string
          format: ISO 8601
        last_transaction_time:
          type: string
      required:
      - id
      - amount_cents
      - amount_currency
      - created_at
      - updated_at
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authentication for third-party applications
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            public: Public scope
            login: Login scope
            ott: One-time token scope
    bearer_header:
      type: http
      scheme: bearer
      bearerFormat: oauth2
      in: header
    bearer_param:
      type: apiKey
      scheme: bearer
      bearerFormat: oauth2
      name: bearer_token
      in: query
    jwt_header:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from basic authentication login
    jwt_param:
      type: apiKey
      name: bearer_token
      in: query
      description: JWT token as query parameter (alternative to Authorization header)
    basic_auth:
      type: http
      scheme: basic
      description: Basic authentication with email and password
    api_key:
      type: apiKey
      name: x-auth-token
      in: header
      description: API key authentication
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication