Stripe Terminal API

openapi: 3.2.0
info:
  title: Stripe Accounts Account Terminal API
  description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Terminal
paths:
  /v1/terminal/locations:
    get:
      summary: Stripe List Terminal Locations
      description: <p>Returns a list of Location objects.</p>
      operationId: GetTerminalLocations
      parameters:
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/terminal.location'
                  has_more:
                    type: boolean
                  url:
                    type: string
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    post:
      summary: Stripe Create Terminal Location
      description: <p>Creates a new Location object.</p>
      operationId: PostTerminalLocations
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - address
              - display_name
              properties:
                address:
                  type: object
                  required:
                  - country
                  properties:
                    city:
                      type: string
                    country:
                      type: string
                    line1:
                      type: string
                    line2:
                      type: string
                    postal_code:
                      type: string
                    state:
                      type: string
                display_name:
                  type: string
                  maxLength: 1000
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                configuration_overrides:
                  type: string
                  maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.location'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
  /v1/terminal/locations/{location}:
    get:
      summary: Stripe Retrieve Terminal Location
      description: <p>Retrieves a Location object.</p>
      operationId: GetTerminalLocationsLocation
      parameters:
      - name: location
        in: path
        required: true
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.location'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    post:
      summary: Stripe Update Terminal Location
      description: <p>Updates a Location object by setting the values of the parameters passed.</p>
      operationId: PostTerminalLocationsLocation
      parameters:
      - name: location
        in: path
        required: true
        schema:
          type: string
          maxLength: 5000
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                address:
                  type: object
                display_name:
                  type: string
                  maxLength: 1000
                metadata:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.location'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    delete:
      summary: Stripe Delete Terminal Location
      description: <p>Deletes a Location object.</p>
      operationId: DeleteTerminalLocationsLocation
      parameters:
      - name: location
        in: path
        required: true
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                  deleted:
                    type: boolean
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
  /v1/terminal/readers:
    get:
      summary: Stripe List Terminal Readers
      description: <p>Returns a list of Reader objects.</p>
      operationId: GetTerminalReaders
      parameters:
      - name: device_type
        in: query
        required: false
        schema:
          type: string
      - name: location
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - offline
          - online
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/terminal.reader'
                  has_more:
                    type: boolean
                  url:
                    type: string
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    post:
      summary: Stripe Create Terminal Reader
      description: <p>Creates a new Reader object.</p>
      operationId: PostTerminalReaders
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - registration_code
              properties:
                registration_code:
                  type: string
                  maxLength: 5000
                label:
                  type: string
                  maxLength: 5000
                location:
                  type: string
                  maxLength: 5000
                metadata:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
  /v1/terminal/readers/{reader}:
    get:
      summary: Stripe Retrieve Terminal Reader
      description: <p>Retrieves a Reader object.</p>
      operationId: GetTerminalReadersReader
      parameters:
      - name: reader
        in: path
        required: true
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    post:
      summary: Stripe Update Terminal Reader
      description: <p>Updates a Reader object by setting the values of the parameters passed.</p>
      operationId: PostTerminalReadersReader
      parameters:
      - name: reader
        in: path
        required: true
        schema:
          type: string
          maxLength: 5000
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                label:
                  type: string
                  maxLength: 5000
                metadata:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    delete:
      summary: Stripe Delete Terminal Reader
      description: <p>Deletes a Reader object.</p>
      operationId: DeleteTerminalReadersReader
      parameters:
      - name: reader
        in: path
        required: true
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                  deleted:
                    type: boolean
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
  /v1/terminal/configurations:
    get:
      summary: Stripe List Terminal Configurations
      description: <p>Returns a list of Configuration objects.</p>
      operationId: GetTerminalConfigurations
      parameters:
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/terminal.configuration'
                  has_more:
                    type: boolean
                  url:
                    type: string
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
    post:
      summary: Stripe Create Terminal Configuration
      description: <p>Creates a new Configuration object.</p>
      operationId: PostTerminalConfigurations
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                tipping:
                  type: object
                offline:
                  type: object
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.configuration'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
  /v1/terminal/connection_tokens:
    post:
      summary: Stripe Create Connection Token
      description: <p>Creates a short-lived connection token for use with Stripe Terminal.</p>
      operationId: PostTerminalConnectionTokens
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                location:
                  type: string
                  maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.connection_token'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      tags:
      - Terminal
  /v1/terminal/configurations/{configuration}:
    delete:
      description: <p>Deletes a <code>Configuration</code> object.</p>
      operationId: DeleteTerminalConfigurationsConfiguration
      parameters:
      - in: path
        name: configuration
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/DeleteTerminalConfigurationsConfigurationRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deleted_terminal.configuration'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
    get:
      description: <p>Retrieves a <code>Configuration</code> object.</p>
      operationId: GetTerminalConfigurationsConfiguration
      parameters:
      - in: path
        name: configuration
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetTerminalConfigurationsConfigurationRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/terminal.configuration_2'
                - $ref: '#/components/schemas/deleted_terminal.configuration'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
    post:
      description: <p>Updates a new <code>Configuration</code> object.</p>
      operationId: PostTerminalConfigurationsConfiguration
      parameters:
      - in: path
        name: configuration
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              bbpos_wisepos_e:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              offline:
                explode: true
                style: deepObject
              tipping:
                explode: true
                style: deepObject
              verifone_p400:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTerminalConfigurationsConfigurationRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/terminal.configuration_2'
                - $ref: '#/components/schemas/deleted_terminal.configuration'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
  /v1/terminal/readers/{reader}/cancel_action:
    post:
      description: <p>Cancels the current reader action.</p>
      operationId: PostTerminalReadersReaderCancelAction
      parameters:
      - in: path
        name: reader
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTerminalReadersReaderCancelActionRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader_2'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
  /v1/terminal/readers/{reader}/process_payment_intent:
    post:
      description: <p>Initiates a payment flow on a Reader.</p>
      operationId: PostTerminalReadersReaderProcessPaymentIntent
      parameters:
      - in: path
        name: reader
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              process_config:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTerminalReadersReaderProcessPaymentIntentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader_2'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
  /v1/terminal/readers/{reader}/process_setup_intent:
    post:
      description: <p>Initiates a setup intent flow on a Reader.</p>
      operationId: PostTerminalReadersReaderProcessSetupIntent
      parameters:
      - in: path
        name: reader
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              process_config:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTerminalReadersReaderProcessSetupIntentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader_2'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
  /v1/terminal/readers/{reader}/refund_payment:
    post:
      description: <p>Initiates a refund on a Reader</p>
      operationId: PostTerminalReadersReaderRefundPayment
      parameters:
      - in: path
        name: reader
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTerminalReadersReaderRefundPaymentRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader_2'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
  /v1/terminal/readers/{reader}/set_reader_display:
    post:
      description: <p>Sets reader display to show cart details.</p>
      operationId: PostTerminalReadersReaderSetReaderDisplay
      parameters:
      - in: path
        name: reader
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              cart:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTerminalReadersReaderSetReaderDisplayRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/terminal.reader_2'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
          description: Error response.
      tags:
      - Terminal
components:
  schemas:
    PostTerminalReadersReaderProcessSetupIntentRequest:
      type: object
      required:
      - customer_consent_collected
      - setup_intent
      properties:
        customer_consent_collected:
          description: Customer Consent Collected
          type: boolean
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        process_config:
          description: Configuration overrides
          properties: {}
          title: process_setup_config
          type: object
        setup_intent:
          description: SetupIntent ID
          maxLength: 5000
          type: string
    terminal.reader:
      type: object
      properties:
        id:
          type: string
          maxLength: 5000
        object:
          type: string
          enum:
          - terminal.reader
        action:
          type:
          - object
          - 'null'
        device_sw_version:
          type:
          - string
          - 'null'
        device_type:
          type: string
        ip_address:
          type:
          - string
          - 'null'
        label:
          type: string
        livemode:
          type: boolean
        location:
          type:
          - string
          - 'null'
        metadata:
          type: object
          additionalProperties:
            type: string
        serial_number:
          type: string
        status:
          type:
          - string
          - 'null'
      required:
      - id
      - object
      - device_type
      - label
      - livemode
      - metadata
      - serial_number
    error_2:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    PostTerminalReadersReaderProcessPaymentIntentRequest:
      type: object
      required:
      - payment_intent
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        payment_intent:
          description: PaymentIntent ID
          maxLength: 5000
          type: string
        process_config:
          description: Configuration overrides
          properties:
            skip_tipping:
              type: boolean
            tipping:
              properties:
                amount_eligible:
                  type: integer
              title: tipping_config
              type: object
          title: process_config
          type: object
    GetTerminalConfigurationsConfigurationRequest:
      type: object
      properties: {}
    terminal.location_2:
      description: 'A Location represents a grouping of readers.


        Related guide: [Fleet management](https://stripe.com/docs/terminal/fleet/locations)'
      properties:
        address:
          $ref: '#/components/schemas/address'
        configuration_overrides:
          description: The ID of a configuration that will be used to customize all readers in this location.
          maxLength: 5000
          type: string
        display_name:
          description: The display name of the location.
          maxLength: 5000
          type: string
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        livemode:
          description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
          type: boolean
        metadata:
          additionalProperties:
            maxLength: 500
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          type: object
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - terminal.location
          type: string
      required:
      - address
      - display_name
      - id
      - livemode
      - metadata
      - object
      title: TerminalLocationLocation
      type: object
      x-expandableFields:
      - address
      x-resourceId: terminal.location
    terminal.reader_2:
      description: 'A Reader represents a physical device for accepting payment details.


        Related guide: [Connecting to a reader](https://stripe.com/docs/terminal/payments/connect-reader)'
      properties:
        action:
          anyOf:
          - $ref: '#/components/schemas/terminal_reader_reader_resource_reader_action'
          description: The most recent action performed by the reader.
        device_sw_version:
          description: The current software version of the reader.
          maxLength: 5000
          type:
          - string
          - 'null'
        device_type:
          description: Type of reader, one of `bbpos_wisepad3`, `stripe_m2`, `bbpos_chipper2x`, `bbpos_wisepos_e`, `verifone_P400`, or `simulated_wisepos_e`.
          enum:
          - bbpos_chipper2x
          - bbpos_wisepad3
          - bbpos_wisepos_e
          - simulated_wisepos_e
          - stripe_m2
          - verifone_P400
          type: string
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        ip_address:
          description: The local IP address of the reader.
          maxLength: 5000
          type:
          - string
          - 'null'
        label:
          description: Custom label given to the reader for easier identification.
          maxLength: 5000
          type: string
        livemode:
          description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
          type: boolean
        location:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/terminal.location_2'
          description: The location identifier of the reader.
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/terminal.location_2'
        metadata:
          additionalProperties:
            maxLength: 500
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          type: object
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - terminal.reader
          type: string
        serial_number:
          description: Serial number of the reader.
          maxLength: 5000
          type: string
        status:
          description: The networking status of the reader.
          maxLength: 5000
          type:
          - string
          - 'null'
      required:
      - device_type
      - id
      - label
      - livemode
      - metadata
    

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