Flipdish CardReaders API

openapi: 3.0.3
info:
  title: Flipdish API - Apps Accounts CardReaders API
  version: v1.0
  description: Flipdish Open API v1.0 — Apps operations. Flipdish is an online ordering and branded-app platform for restaurants and takeaways. This specification was derived from the official Flipdish Swagger document and grouped by resource domain.
  contact:
    name: Flipdish Support
    email: help@flipdish.com
    url: https://help.flipdish.com
  x-generated-from: https://api.flipdish.co/swagger/docs/v1.0
  x-last-validated: '2026-06-02'
servers:
- url: https://api.flipdish.co
  description: Flipdish production API
security:
- oauth2:
  - api
tags:
- name: CardReaders
  description: Operations for Card Readers.
paths:
  /api/v1.0/{appId}/stripeterminal/connectiontoken:
    get:
      tags:
      - CardReaders
      operationId: GetStripeConnectionToken
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_StripeTerminalConnectionToken_'
              examples:
                GetStripeConnectionToken200Example:
                  summary: Default GetStripeConnectionToken 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      Token: string
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetStripeConnectionToken400Example:
                  summary: Default GetStripeConnectionToken 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetStripeConnectionToken401Example:
                  summary: Default GetStripeConnectionToken 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetStripeConnectionToken403Example:
                  summary: Default GetStripeConnectionToken 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetStripeConnectionToken500Example:
                  summary: Default GetStripeConnectionToken 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Get Stripe Connection Token
      description: Get Stripe Connection Token via the Flipdish Open API v1.0 (GET /api/v1.0/{appId}/stripeterminal/connectiontoken).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/payments/terminals/stripe/{readerId}:
    get:
      tags:
      - CardReaders
      operationId: CardReaders_GetReader
      parameters:
      - name: readerId
        in: path
        required: true
        schema:
          type: string
        description: The reader id path parameter.
        example: '500123'
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_CardReader_'
              examples:
                CardReaders_GetReader200Example:
                  summary: Default CardReaders_GetReader 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      Id: '500123'
                      DeviceSoftwareVersion: string
                      SerialNumber: string
                      Status: Active
                      RegistrationCode: string
                      DeviceType: string
                      Deleted: true
                      Action:
                        ActionState: string
                        FailureCode: string
                        FailureMessage: string
                        Type: string
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CardReaders_GetReader400Example:
                  summary: Default CardReaders_GetReader 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CardReaders_GetReader401Example:
                  summary: Default CardReaders_GetReader 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CardReaders_GetReader403Example:
                  summary: Default CardReaders_GetReader 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CardReaders_GetReader500Example:
                  summary: Default CardReaders_GetReader 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Card Readers_Get Reader
      description: Card Readers_Get Reader via the Flipdish Open API v1.0 (GET /api/v1.0/{appId}/payments/terminals/stripe/{readerId}).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/cardreaders/kiosk/{deviceId}/bluetooth/status:
    get:
      tags:
      - CardReaders
      operationId: GetBluetoothTerminalStatus
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      - name: deviceId
        in: path
        required: true
        schema:
          type: string
        description: The device id path parameter.
        example: '500123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_BluetoothTerminalStatus_'
              examples:
                GetBluetoothTerminalStatus200Example:
                  summary: Default GetBluetoothTerminalStatus 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      SerialNumber: string
                      SoftwareVersion: string
                      DeviceType: CHIPPER_2X
                      Status: Not_Connected
                      BatteryLevel: 1.0
                      UpdateTime: '2026-06-02T12:00:00Z'
                      ReaderId: '500123'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetBluetoothTerminalStatus400Example:
                  summary: Default GetBluetoothTerminalStatus 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetBluetoothTerminalStatus401Example:
                  summary: Default GetBluetoothTerminalStatus 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetBluetoothTerminalStatus403Example:
                  summary: Default GetBluetoothTerminalStatus 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GetBluetoothTerminalStatus500Example:
                  summary: Default GetBluetoothTerminalStatus 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Get Bluetooth Terminal Status
      description: Get Bluetooth Terminal Status via the Flipdish Open API v1.0 (GET /api/v1.0/{appId}/cardreaders/kiosk/{deviceId}/bluetooth/status).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/stripeterminal/location:
    post:
      tags:
      - CardReaders
      operationId: GenerateStripeTerminalLocation
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeoPointRequest'
            examples:
              GenerateStripeTerminalLocationRequestExample:
                summary: Default GenerateStripeTerminalLocation request
                x-microcks-default: true
                value:
                  Latitude: 1.0
                  Longitude: 1.0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_StripeTerminalLocation_'
              examples:
                GenerateStripeTerminalLocation200Example:
                  summary: Default GenerateStripeTerminalLocation 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      Location: string
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GenerateStripeTerminalLocation400Example:
                  summary: Default GenerateStripeTerminalLocation 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GenerateStripeTerminalLocation401Example:
                  summary: Default GenerateStripeTerminalLocation 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GenerateStripeTerminalLocation403Example:
                  summary: Default GenerateStripeTerminalLocation 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                GenerateStripeTerminalLocation500Example:
                  summary: Default GenerateStripeTerminalLocation 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Generate Stripe Terminal Location
      description: Generate Stripe Terminal Location via the Flipdish Open API v1.0 (POST /api/v1.0/{appId}/stripeterminal/location).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/payments/terminals/stripe/register:
    post:
      tags:
      - CardReaders
      operationId: RegisterStripeTerminal
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardReaderRegistrationRequest'
            examples:
              RegisterStripeTerminalRequestExample:
                summary: Default RegisterStripeTerminal request
                x-microcks-default: true
                value:
                  RegistrationCode: string
                  KioskDeviceId: '500123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_CardReader_'
              examples:
                RegisterStripeTerminal200Example:
                  summary: Default RegisterStripeTerminal 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      Id: '500123'
                      DeviceSoftwareVersion: string
                      SerialNumber: string
                      Status: Active
                      RegistrationCode: string
                      DeviceType: string
                      Deleted: true
                      Action:
                        ActionState: string
                        FailureCode: string
                        FailureMessage: string
                        Type: string
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                RegisterStripeTerminal400Example:
                  summary: Default RegisterStripeTerminal 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                RegisterStripeTerminal401Example:
                  summary: Default RegisterStripeTerminal 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                RegisterStripeTerminal403Example:
                  summary: Default RegisterStripeTerminal 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                RegisterStripeTerminal500Example:
                  summary: Default RegisterStripeTerminal 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Register Stripe Terminal
      description: Register Stripe Terminal via the Flipdish Open API v1.0 (POST /api/v1.0/{appId}/payments/terminals/stripe/register).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/payments/terminals/stripe/{readerId}/cancel_action:
    post:
      tags:
      - CardReaders
      operationId: CancelReaderAction
      parameters:
      - name: readerId
        in: path
        required: true
        schema:
          type: string
        description: The reader id path parameter.
        example: '500123'
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_CardReader_'
              examples:
                CancelReaderAction200Example:
                  summary: Default CancelReaderAction 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      Id: '500123'
                      DeviceSoftwareVersion: string
                      SerialNumber: string
                      Status: Active
                      RegistrationCode: string
                      DeviceType: string
                      Deleted: true
                      Action:
                        ActionState: string
                        FailureCode: string
                        FailureMessage: string
                        Type: string
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CancelReaderAction400Example:
                  summary: Default CancelReaderAction 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CancelReaderAction401Example:
                  summary: Default CancelReaderAction 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CancelReaderAction403Example:
                  summary: Default CancelReaderAction 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                CancelReaderAction500Example:
                  summary: Default CancelReaderAction 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Cancel Reader Action
      description: Cancel Reader Action via the Flipdish Open API v1.0 (POST /api/v1.0/{appId}/payments/terminals/stripe/{readerId}/cancel_action).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/payments/terminals/stripe/{readerId}/processPaymentIntent:
    post:
      tags:
      - CardReaders
      operationId: InitiateReaderProcessPaymentIntent
      parameters:
      - name: readerId
        in: path
        required: true
        schema:
          type: string
        description: The reader id path parameter.
        example: '500123'
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessPaymentIntentRequest'
            examples:
              InitiateReaderProcessPaymentIntentRequestExample:
                summary: Default InitiateReaderProcessPaymentIntent request
                x-microcks-default: true
                value:
                  PaymentIntentId: '500123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiResult_CardReader_'
              examples:
                InitiateReaderProcessPaymentIntent200Example:
                  summary: Default InitiateReaderProcessPaymentIntent 200 response
                  x-microcks-default: true
                  value:
                    Data:
                      Id: '500123'
                      DeviceSoftwareVersion: string
                      SerialNumber: string
                      Status: Active
                      RegistrationCode: string
                      DeviceType: string
                      Deleted: true
                      Action:
                        ActionState: string
                        FailureCode: string
                        FailureMessage: string
                        Type: string
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                InitiateReaderProcessPaymentIntent400Example:
                  summary: Default InitiateReaderProcessPaymentIntent 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                InitiateReaderProcessPaymentIntent401Example:
                  summary: Default InitiateReaderProcessPaymentIntent 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '403':
          description: Successful authentication, but authorization has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                InitiateReaderProcessPaymentIntent403Example:
                  summary: Default InitiateReaderProcessPaymentIntent 403 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                InitiateReaderProcessPaymentIntent500Example:
                  summary: Default InitiateReaderProcessPaymentIntent 500 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
      security:
      - oauth2:
        - api
      summary: Flipdish Initiate Reader Process Payment Intent
      description: Initiate Reader Process Payment Intent via the Flipdish Open API v1.0 (POST /api/v1.0/{appId}/payments/terminals/stripe/{readerId}/processPaymentIntent).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1.0/{appId}/cardreaders/kiosk/{deviceId}/bluetooth/{terminalType}/pair:
    post:
      tags:
      - CardReaders
      operationId: InitiateKioskBluetoothPairingMode
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
        description: The app id path parameter.
        example: '500123'
      - name: deviceId
        in: path
        required: true
        schema:
          type: string
        description: The device id path parameter.
        example: '500123'
      - name: terminalType
        in: path
        required: true
        schema:
          type: string
          enum:
          - CHIPPER_2X
          - COTS_DEVICE
          - VERIFONE_P400
          - WISEPAD_3
          - WISEPOS_E
        description: The terminal type path parameter.
        example: CHIPPER_2X
      responses:
        '200':
          description: OK
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                InitiateKioskBluetoothPairingMode400Example:
                  summary: Default InitiateKioskBluetoothPairingMode 400 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage: Invalid or missing parameters.
                      errorCode: BadRequest
                      details: Validation failed for field 'storeId'.
        '401':
          description: Authentication has been denied for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlipdishError'
              examples:
                InitiateKioskBluetoothPairingMode401Example:
                  summary: Default InitiateKioskBluetoothPairingMode 401 response
                  x-microcks-default: true
                  value:
                    error:
                      errorMessage:

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flipdish/refs/heads/main/openapi/flipdish-cardreaders-api-openapi.yml