openapi: 3.1.0
info:
  title: Howler API v3 Artists Bank Account 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: Bank Account
paths:
  /bank_account/edit:
    get:
      summary: edit bank account
      operationId: editConsumerBankAccount
      parameters:
      - name: show_auto_cashout
        in: query
        description: show_auto_cashout
        schema:
          type: boolean
      - name: cashless_tag_pairing_id
        in: query
        required: false
        schema:
          type: integer
      tags:
      - Bank Account
      description: 'Renders a webpage to allow the user to complete their bank account details. The user can also enable auto cashouts from this page.


        Once the user has successfully updated their details a redirect will be done to a specific URL.

        '
      responses:
        '200':
          description: successful without auto cashout
  /bank_account:
    get:
      summary: show bank account details
      operationId: showConsumerBankAccount
      tags:
      - Bank Account
      description: Returns the current bank account details of the authenticated user.
      security:
      - oauth2: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_account:
                    type:
                    - object
                    - 'null'
                    properties:
                      id:
                        type: integer
                      type:
                        type: string
                      bank_name:
                        type: string
                      account_number:
                        type: string
                      account_type:
                        type: string
                      account_holder:
                        type: string
                      branch_code:
                        type: string
                      bank_country:
                        type: string
                      payment_method:
                        type: string
                  auto_cashout:
                    type: boolean
    post:
      summary: create bank account
      operationId: createConsumerBankAccount
      tags:
      - Bank Account
      description: Creates or updates bank account details for the authenticated user.
      security:
      - oauth2: []
      parameters: []
      responses:
        '422':
          description: unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method:
                  type: string
                  example: Bank transfer
                bank_country:
                  type: string
                  example: South Africa
                bank_name:
                  type: string
                  example: Standard Bank
                account_number:
                  type: string
                  example: '62146101811'
                account_holder:
                  type: string
                  example: John Doe
                branch_code:
                  type: string
                  example: 08067100
                account_type:
                  type: string
                  example: cheque
                auto_cashout:
                  type: boolean
                  example: true
        required: true
    put:
      summary: update bank account
      operationId: updateConsumerBankAccount
      tags:
      - Bank Account
      description: '**Private API**

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

        '
      parameters: []
      responses:
        '302':
          description: successful with redirect context
        '200':
          description: failed
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
              required: []
        required: true
  /bank_account/refresh_form:
    post:
      summary: refresh bank account form layout
      operationId: refreshConsumerBankAccountForm
      tags:
      - Bank Account
      description: '**Private API**

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

        '
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_type:
                    type: string
                  fields:
                    type: array
                    items:
                      type: object
                required:
                - account_type
                - fields
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                bank_account:
                  type: object
                  properties:
                    bank_account_attributes:
                      type: object
                  required:
                  - bank_account_attributes
                country:
                  type: string
                account_type:
                  type: string
              required:
              - bank_account
        required: true
components:
  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