openapi: 3.1.0
info:
  title: Howler API v3 Artists Top Up Ticket 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: Top Up Ticket
paths:
  /tickets/{ticket_id}/top_up:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    post:
      summary: select ticket (1)
      operationId: updateConsumerticketTopup
      tags:
      - Top Up Ticket
      description: 'Start the top up process of a ticket by providing the ticket id.


        The next_step in the body will indicate which action should be performed next.


        If the user is typing in the barcode manually use `/api/v3/consumer_portal/top_up` instead.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  top_up_order:
                    $ref: '#/components/schemas/Order'
                  next_step:
                    type: string
                required:
                - top_up_order
                - next_step
        '404':
          description: ticket not found
        '400':
          description: ticket already claimed
  /tickets/{ticket_id}/top_up/{top_up_order_id}/amounts:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    - name: top_up_order_id
      in: path
      description: top_up_order_id
      required: true
      schema:
        type: integer
    put:
      summary: accept amounts (2)
      operationId: updateConsumerTicketAmounts
      tags:
      - Top Up Ticket
      description: 'Specify the amount to top up the ticket with.

        '
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  top_up_order:
                    $ref: '#/components/schemas/Order'
                  next_step:
                    type: string
                required:
                - top_up_order
                - next_step
        '404':
          description: ticket not found
        '400':
          description: ticket already claimed
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cashless_top_up:
                  type: object
                  properties:
                    amount:
                      type: number
                  required:
                  - amount
              required:
              - cashless_top_up
            examples:
              top_up:
                summary: Top Up
                value:
                  cashless_top_up:
                    amount: 5.25
        required: true
  /tickets/{ticket_id}/top_up/{top_up_order_id}/payments:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    - name: top_up_order_id
      in: path
      description: top_up_order_id
      required: true
      schema:
        type: integer
    get:
      summary: select payment method (3)
      operationId: editConsumerTicketPayment
      tags:
      - Top Up Ticket
      description: 'Renders a webpage to allow the user to pay for their top up order.


        Once the user has successfully completed a payment, a redirect will be done to a specific URL.

        '
      responses:
        '200':
          description: successful
        '400':
          description: top up order invalid status
  /tickets/{ticket_id}/top_up/{top_up_order_id}/completes:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    - name: top_up_order_id
      in: path
      description: top_up_order_id
      required: true
      schema:
        type: integer
    get:
      summary: check complete (4)
      operationId: getConsumerTicketComplete
      tags:
      - Top Up Ticket
      description: 'Check if the top up order was completed. This request should be made after the payment web page has redirected back to the application.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  top_up_order:
                    $ref: '#/components/schemas/Order'
                required:
                - top_up_order
        '404':
          description: top up order not found
  /tickets/{ticket_id}/top_up/{top_up_order_id}/successful_payment:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    - name: top_up_order_id
      in: path
      description: top_up_order_id
      required: true
      schema:
        type: integer
    - name: merchant_reference
      in: query
      description: merchant_reference
      required: true
      schema:
        type: integer
    get:
      summary: custom schema redirect for Safari browser
      operationId: customSchemaRedirectForSafari
      tags:
      - Top Up Ticket
      description: '**Private API**

        Tests the custom redirect page rendering for Safari browsers with custom schema URLs.

        '
      responses:
        '303':
          description: successful
        '302':
          description: custom redirect page rendered
  /tickets/{ticket_id}/top_up/{top_up_order_id}/pending_successful_payment:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    - name: top_up_order_id
      in: path
      description: top_up_order_id
      required: true
      schema:
        type: integer
    - name: merchant_reference
      in: query
      description: merchant_reference
      required: true
      schema:
        type: integer
    get:
      summary: submit pending successful payment method (3)
      operationId: pendingSuccessConsumerTicketPayment
      tags:
      - Top Up Ticket
      description: '**Private API**

        This end-point should only ever be called by the web page rendered using the GET version of this end-point.

        '
      responses:
        '303':
          description: failed
  /tickets/{ticket_id}/top_up/{top_up_order_id}/failed_payment:
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: integer
    - name: top_up_order_id
      in: path
      description: top_up_order_id
      required: true
      schema:
        type: integer
    - name: merchant_reference
      in: query
      description: merchant_reference
      required: true
      schema:
        type: integer
    get:
      summary: submit failed payment method (3)
      operationId: failedConsumerTicketPayment
      tags:
      - Top Up Ticket
      description: '**Private API**

        This end-point should only ever be called by the web page rendered using the GET version of this end-point.

        '
      responses:
        '303':
          description: successful
components:
  schemas:
    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?
    Order:
      type: object
      properties:
        id:
          type: integer
        reference:
          type: string
        type:
          type: string
        status:
          type: string
          enum:
          - pending
          - paid
          - expired
          - pending_payment
          - created
          - processing
        user:
          $ref: '#/components/schemas/User'
        cashless_deposit_cents:
          type: integer
      required:
      - id
      - reference
      - status
      - type
      - user
      - cashless_deposit_cents
  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