SumUp Readers API
A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.
OpenAPI Specification
openapi: 3.0.1
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:
ReaderPairingCode:
description: The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing.
type: string
example: 4WLFDSBF
maxLength: 9
minLength: 8
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
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
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
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
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
Metadata:
description: Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.
type: object
example: {}
additionalProperties: true
maxProperties: 64
BadRequest:
description: 400 Bad Request
type: object
properties:
errors:
type: object
properties:
detail:
description: Fuller message giving context to error
type: string
type:
description: Key indicating type of error
type: string
enum:
- INVALID_BEARER_TOKEN
- INVALID_USER_AGENT
- NOT_ENOUGH_UNPAID_PAYOUTS
- DUPLICATE_HEADERS
required:
- type
example:
errors:
detail: Bad request
type: INVALID_BEARER_TOKEN
required:
- errors
title: BadRequest
ReaderDevice:
description: Information about the underlying physical device.
type: object
properties:
identifier:
description: A unique identifier of the physical device (e.g. serial number).
type: string
example: U1DT3NA00-CN
model:
description: Identifier of the model of the device.
type: string
example: solo
enum:
- solo
- virtual-solo
required:
- identifier
- model
CreateReaderCheckoutRequest:
description: Reader Checkout
type: object
properties:
aade:
description: 'Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol.
When such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider.
'
type: object
properties:
provider_id:
description: The identifier of the AADE signature provider.
type: string
example: '123'
signature:
description: The base64 encoded signature of the transaction data.
type: string
example: QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5
signature_data:
description: The string containing the signed transaction data.
type: string
example: B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039
required:
- provider_id
- signature
- signature_data
affiliate:
description: 'Affiliate metadata for the transaction.
It is a field that allow for integrators to track the source of the transaction.
'
type: object
nullable: true
properties:
app_id:
description: 'Application ID of the affiliate.
It is a unique identifier for the application and should be set by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.
'
type: string
example: com.example.app
foreign_transaction_id:
description: 'Foreign transaction ID of the affiliate.
It is a unique identifier for the transaction.
It can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).
'
type: string
example: 19e12390-72cf-4f9f-80b5-b0c8a67fa43f
key:
description: 'Key of the affiliate.
It is a unique identifier for the key and should be generated by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.
'
type: string
example: 123e4567-e89b-12d3-a456-426614174000
tags:
description: 'Additional metadata for the transaction.
It is key-value object that can be associated with the transaction.
'
type: object
example:
custom_key_1: custom_value_1
custom_key_2: custom_value_2
additionalProperties: true
required:
- app_id
- key
- foreign_transaction_id
title: Affiliate
card_type:
# --- 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