SumUp Readers API

openapi: 3.2.0
info:
  title: SumUp REST Checkouts Readers API
  version: 1.0.0
  description: 'SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status).


    You can experiment and work on your integration in a sandbox that doesn''t affect your regular data and doesn''t process real transactions. To create a sandbox merchant account visit the [dashboard](https://me.sumup.com/settings/developer). To use the sandbox when interacting with SumUp APIs [create an API](https://me.sumup.com/settings/api-keys) key and use it for [authentication](https://developer.sumup.com/api/authentication).'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.sumup.com
  description: Production server
tags:
- name: Readers
  description: A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.
  x-core-objects:
  - $ref: '#/components/schemas/Reader'
paths:
  /v0.1/merchants/{merchant_code}/readers:
    get:
      operationId: ListReaders
      summary: List Readers
      description: List all readers of the merchant.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      responses:
        '200':
          description: Returns a list Reader objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reader'
                required:
                - items
        '401':
          description: Authentication failed or missing required scope.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/unauthorized
                title: Unauthorized
                status: 401
                detail: Authentication credentials are missing or invalid.
      security:
      - apiKey: []
      - oauth2:
        - readers.read
      tags:
      - Readers
      x-codegen:
        method_name: list
      x-permissions:
      - relation: readers_list
        object_type: merchant
        object_id_param: merchant_code
      x-scopes:
      - readers.read
    post:
      operationId: CreateReader
      summary: Create a Reader
      description: Create a new Reader for the merchant account.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pairing_code:
                  $ref: '#/components/schemas/ReaderPairingCode'
                name:
                  $ref: '#/components/schemas/ReaderName'
                metadata:
                  $ref: '#/components/schemas/Metadata'
              required:
              - pairing_code
              - name
      responses:
        '201':
          description: Returns the Reader object if the creation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reader'
              examples:
                created:
                  summary: A reader that waits for the physical device to acknowledge the pairing.
                  value:
                    id: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
                    name: Frontdesk
                    status: processing
                    device:
                      identifier: U1DT3NA00-CN
                      model: solo
                    created_at: 2023-05-09 14:50:20.214000+00:00
                    updated_at: 2023-05-09 14:52:58.714000+00:00
          links:
            UpdateReaderByID:
              operationId: UpdateReader
              parameters:
                reader_id: $response.body#/id
              description: Update the reader object. This can be used to set a name after using this endpoint to verify the pairing code.
            DeleteReaderByID:
              operationId: DeleteReader
              parameters:
                reader_id: $response.body#/id
              description: Delete the reader.
        '400':
          description: The request is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        '404':
          description: There's no pending reader for the submitted pairing code.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
        '409':
          description: The Reader is not in a pending state.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
      security:
      - apiKey: []
      - oauth2:
        - readers.write
      tags:
      - Readers
      x-codegen:
        method_name: create
      x-permissions:
      - relation: readers_create
        object_type: merchant
        object_id_param: merchant_code
      x-scopes:
      - readers.write
  /v0.1/merchants/{merchant_code}/readers/{reader_id}:
    get:
      operationId: GetReader
      summary: Retrieve a Reader
      description: Retrieve a Reader.
      parameters:
      - name: If-Modified-Since
        in: header
        description: "Return the reader only if it has been modified after the specified timestamp given in the headers.\n\nTimestamps are accepted in the following formats:\n\n - HTTP Standard: [IMF format (RFC 5322)](https://www.rfc-editor.org/rfc/rfc5322#section-3.3), sometimes also referred to as [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1).\n - RFC 3339: Used for timestamps in JSON payloads on this API."
        required: false
        schema:
          type: string
          oneOf:
          - format: httpdate
            type: string
            example: Tue, 03 May 2022 14:46:44 GMT
          - format: date-time
            type: string
            example: 2023-05-30 10:38:01+00:00
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      - name: reader_id
        in: path
        description: The unique identifier of the reader.
        required: true
        schema:
          $ref: '#/components/schemas/ReaderID'
      responses:
        '200':
          description: Returns a Reader object for a valid identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reader'
        '404':
          description: The requested Reader resource does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      security:
      - apiKey: []
      - oauth2:
        - readers.read
      tags:
      - Readers
      x-codegen:
        method_name: get
      x-permissions:
      - relation: readers_view
        object_type: merchant
        object_id_param: merchant_code
      x-scopes:
      - readers.read
    delete:
      operationId: DeleteReader
      summary: Delete a reader
      description: Delete a reader.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      - name: reader_id
        in: path
        description: The unique identifier of the reader.
        required: true
        schema:
          $ref: '#/components/schemas/ReaderID'
      responses:
        '200':
          description: Returns an empty response if the deletion succeeded.
        '404':
          description: The requested Reader resource does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      security:
      - apiKey: []
      - oauth2:
        - readers.write
      tags:
      - Readers
      x-codegen:
        method_name: delete
      x-permissions:
      - relation: readers_delete
        object_type: merchant
        object_id_param: merchant_code
      x-scopes:
      - readers.write
    patch:
      operationId: UpdateReader
      summary: Update a Reader
      description: Update a Reader.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      - name: reader_id
        in: path
        description: The unique identifier of the reader.
        required: true
        schema:
          $ref: '#/components/schemas/ReaderID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/ReaderName'
                metadata:
                  $ref: '#/components/schemas/Metadata'
      responses:
        '200':
          description: Returns the updated Reader object if the update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reader'
        '403':
          description: The request isn't sufficiently authorized to modify the reader.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to perform this action.
        '404':
          description: The requested Reader resource does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      security:
      - apiKey: []
      - oauth2:
        - readers.write
      tags:
      - Readers
      x-codegen:
        method_name: update
      x-permissions:
      - relation: readers_update
        object_type: merchant
        object_id_param: merchant_code
      x-scopes:
      - readers.write
  /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout:
    post:
      operationId: CreateReaderCheckout
      summary: Create a Reader Checkout
      description: 'Creates a Checkout for a Reader.


        This process is asynchronous and the actual transaction may take some time to be started on the device.



        There are some caveats when using this endpoint:

        * The target device must be online, otherwise checkout won''t be accepted

        * After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.



        **Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.

        '
      parameters:
      - name: merchant_code
        in: path
        description: Merchant Code
        required: true
        schema:
          type: string
        example: MC0X0ABC
      - name: reader_id
        in: path
        description: The unique identifier of the Reader
        required: true
        schema:
          type: string
        example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
      requestBody:
        description: A checkout initial attributes
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReaderCheckoutRequest'
      responses:
        '201':
          description: The Checkout got successfully created for the given reader.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderCheckoutResponse'
        '400':
          description: Response when given params (or one of them) are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderCheckoutError'
            application/problem+json:
              example:
                detail: Bad Request
                status: 400
                title: Bad Request
                type: https://developer.sumup.com/problem/bad-request
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderCheckoutError'
            application/problem+json:
              example:
                detail: Unauthorized
                status: 401
                title: Unauthorized
                type: https://developer.sumup.com/problem/unauthorized
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Response when given reader is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
            application/problem+json:
              example:
                detail: The requested resource doesn't exist or does not belong to you.
                status: 404
                title: Requested resource couldn't be found.
                type: https://developer.sumup.com/problem/not-found
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Response when given params (or one of them) are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderCheckoutUnprocessableEntity'
            application/problem+json:
              example:
                detail: Validation failed
                status: 422
                title: Unprocessable Entity
                type: https://developer.sumup.com/problem/validation-error
              schema:
                $ref: '#/components/schemas/Problem'
      callbacks:
        ReaderCheckoutStatusChange:
          '{$request.body#/return_url}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ReaderCheckoutStatusChange'
              responses:
                '200':
                  description: 'Your server returns this code if it accepts the callback.

                    If the server returns any other code, the callback will be retried up to 5 times with exponential backoff.

                    '
              callbacks: {}
      security:
      - apiKey: []
      - oauth2:
        - readers.write
      tags:
      - Readers
      x-codegen:
        method_name: create_checkout
      x-permissions:
      - readers_checkout_create
      x-scopes:
      - readers.write
  /v0.1/merchants/{merchant_code}/readers/{reader_id}/status:
    get:
      operationId: GetReaderStatus
      summary: Get a Reader Status
      description: 'Provides the last known status for a Reader.


        This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state).


        Supported States


        * `IDLE` – Reader ready for next transaction

        * `SELECTING_TIP` – Waiting for tip input

        * `WAITING_FOR_CARD` – Awaiting card insert/tap

        * `WAITING_FOR_PIN` – Waiting for PIN entry

        * `WAITING_FOR_SIGNATURE` – Waiting for customer signature

        * `UPDATING_FIRMWARE` – Firmware update in progress


        Device Status


        * `ONLINE` – Device connected and operational

        * `OFFLINE` – Device disconnected (last state persisted)


        **Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher.

        '
      parameters:
      - name: merchant_code
        in: path
        description: Merchant Code
        required: true
        schema:
          type: string
        example: MC0X0ABC
      - name: reader_id
        in: path
        description: The unique identifier of the Reader
        required: true
        schema:
          type: string
        example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
      responses:
        '200':
          description: Response with the device status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '400':
          description: Response when given params (or one of them) are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
            application/problem+json:
              example:
                detail: Bad Request
                status: 400
                title: Bad Request
                type: https://developer.sumup.com/problem/bad-request
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Response when given merchant's token is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
            application/problem+json:
              example:
                detail: Unauthorized
                status: 401
                title: Unauthorized
                type: https://developer.sumup.com/problem/unauthorized
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Response when given reader is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
            application/problem+json:
              example:
                detail: The requested resource doesn't exist or does not belong to you.
                status: 404
                title: Requested resource couldn't be found.
                type: https://developer.sumup.com/problem/not-found
              schema:
                $ref: '#/components/schemas/Problem'
      callbacks: {}
      security:
      - apiKey: []
      - oauth2:
        - readers.read
      tags:
      - Readers
      x-codegen:
        method_name: get_status
      x-permissions:
      - readers_view
      x-scopes:
      - readers.read
  /v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate:
    post:
      operationId: CreateReaderTerminate
      summary: Terminate a Reader Checkout
      description: 'Terminate a Reader Checkout stops the current transaction on the target device.


        This process is asynchronous and the actual termination may take some time to be performed on the device.



        There are some caveats when using this endpoint:

        * The target device must be online, otherwise terminate won''t be accepted

        * The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.

        * There is no confirmation of the termination.


        If a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL.



        **Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher.

        '
      parameters:
      - name: merchant_code
        in: path
        description: Merchant Code
        required: true
        schema:
          type: string
        example: MC0X0ABC
      - name: reader_id
        in: path
        description: The unique identifier of the Reader
        required: true
        schema:
          type: string
        example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
      requestBody:
        description: A checkout initial attributes
        required: false
        content:
          application/json: {}
      responses:
        '202':
          description: The Terminate action was successfully dispatched for the given reader.
          content:
            application/json: {}
        '400':
          description: Response when given params (or one of them) are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderTerminateError'
            application/problem+json:
              example:
                detail: Bad Request
                status: 400
                title: Bad Request
                type: https://developer.sumup.com/problem/bad-request
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderTerminateError'
            application/problem+json:
              example:
                detail: Unauthorized
                status: 401
                title: Unauthorized
                type: https://developer.sumup.com/problem/unauthorized
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Response when given reader is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
            application/problem+json:
              example:
                detail: The requested resource doesn't exist or does not belong to you.
                status: 404
                title: Requested resource couldn't be found.
                type: https://developer.sumup.com/problem/not-found
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Response when given params (or one of them) are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReaderTerminateUnprocessableEntity'
            application/problem+json:
              example:
                detail: The device is offline.
                status: 422
                title: Reader Offline
                type: https://developer.sumup.com/problem/reader-offline
              schema:
                $ref: '#/components/schemas/Problem'
      callbacks: {}
      security:
      - apiKey: []
      - oauth2:
        - readers.write
      tags:
      - Readers
      x-codegen:
        method_name: terminate_checkout
      x-permissions:
      - readers_checkout_create
      x-scopes:
      - readers.write
components:
  schemas:
    ReaderStatus:
      description: 'The status of the reader object gives information about the current state of the reader.


        Possible values:


        - `unknown` - The reader status is unknown.

        - `processing` - The reader is created and waits for the physical device to confirm the pairing.

        - `paired` - The reader is paired with a merchant account and can be used with SumUp APIs.

        - `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated.'
      type: string
      example: paired
      enum:
      - unknown
      - processing
      - paired
      - expired
    Problem:
      description: 'A RFC 9457 problem details object.


        Additional properties specific to the problem type may be present.'
      type: object
      properties:
        type:
          description: A URI reference that identifies the problem type.
          type: string
          format: uri
          example: https://developer.sumup.com/problem/not-found
        title:
          description: A short, human-readable summary of the problem type.
          type: string
          example: Requested resource couldn't be found.
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          type: integer
          example: 404
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
          example: The requested resource doesn't exist or does not belong to you.
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          type: string
          format: uri
      additionalProperties: true
      required:
      - type
      title: Problem
    NotFound:
      description: 404 Not Found
      type: object
      properties:
        errors:
          type: object
          properties:
            detail:
              description: Fuller message giving context to error
              type: string
          required:
          - detail
      example:
        errors:
          detail: Not Found
      required:
      - errors
      title: NotFound
    CreateReaderCheckoutError:
      description: Error description
      type: object
      properties:
        errors:
          type: object
          properties:
            detail:
              description: Error message
              type: string
            type:
              description: Error code
              type: string
          required:
          - type
      required:
      - errors
      title: CreateReaderCheckoutError
    CreateReaderCheckoutResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            client_transaction_id:
              description: 'The client transaction ID is a unique identifier for the transaction that is generated for the client.


                It can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).

                '
              type: string
              example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          required:
          - client_transaction_id
      example:
        data:
          client_transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      required:
      - data
      title: CreateReaderCheckoutResponse
    ReaderID:
      description: 'Unique identifier of the object.


        Note that this identifies the instance of the physical devices pairing with your SumUp account. If you [delete](https://developer.sumup.com/api/readers/delete-reader) a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.'
      type: string
      example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
      maxLength: 30
      minLength: 30
    CreateReaderCheckoutUnprocessableEntity:
      description: Unprocessable entity
      type: object
      properties:
        errors:
          type: object
          additionalProperties: true
      example:
        DataValidation:
          description: Validation errors for the informed fields.
          value:
            errors:
              card_type:
              - is invalid
              installments:
              - not allowed
              return_url:
              - must be a valid URL
              tip_rates:
              - must be between 0.01 and 0.99
              total_amount:
              - must be greater than 0
        InstallmentsTooLow:
          description: Error returned when installments is not within the allowed range.
          value:
            errors:
              installments:
              - is invalid
        ReaderBusy:
          description: Error returned when a checkout was requested in the last 60 seconds.
          value:
            errors:
              detail: There is a pending checkout for the device.
              type: READER_BUSY
        ReaderOffline:
          description: Error returned when the target device is not online.
          value:
            errors:
              detail: The device is offline.
              type: READER_OFFLINE
      required:
      - errors
      title: CreateReaderCheckoutUnprocessableEntity
    CreateReaderTerminateError:
      description: Error description
      type: object
      properties:
        errors:
          type: object
          properties:
            detail:
              description: Error message
              type: string
            type:
              description: Error code
              type: string
          required:
          - type
      required:
      - errors
      title: CreateReaderTerminateError
    ReaderName:
      description: Custom human-readable, user-defined name for easier identification of the reader.
      type: string
      example: Frontdesk
      maxLength: 500
    Unauthorized:
      description: 401 Unauthorized
      type: object
      properties:
        errors:
          type: object
          properties:
            detail:
              description: Fuller message giving context to error
              type: string
            type:
              description: Key indicating type of error. Present only for typed 401 responses (e.g. invalid token, invalid password). Absent for generic unauthorized responses.
              type: string
              enum:
              - INVALID_ACCESS_TOKEN
              - INVALID_PASSWORD
          required:
          - detail
      example:
        errors:
          detail: Unauthorized
      required:
      - errors
      title: Unauthorized
    Reader:
      description: A physical card reader device that can accept in-person payments.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ReaderID'
        name:
          $ref: '#/components/schemas/ReaderName'
        status:
          $ref: '#/components/schemas/ReaderStatus'
        device:
          $ref: '#/components/schemas/ReaderDevice'
        metadata:
          $ref: '#/components/schemas/Metadata'
        service_account_id:
          description: 'Identifier of the system-managed service account associated with this reader.

            Present only for readers that are already paired.

            This field is currently in beta and may change.'
          type: string
          format: uuid
          x-beta: true
        created_at:
          description: The timestamp of when the reader was created.
          type: string
          format: date-time
          example: 2023-01-18 15:16:17+00:00
        updated_at:
          description: Th

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