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: description: 'The card type of the card used for the transaction. Is is required only for some countries (e.g: Brazil). ' type: string example: credit enum: - credit - debit description: description: Description of the checkout to be shown in the Merchant Sales type: string installments: description: 'Number of installments for the transaction. It may vary according to the merchant country. For example, in Brazil, the maximum number of installments is 12. Omit if the merchant country does support installments. Otherwise, the checkout will be rejected. ' type: integer example: 1 minimum: 1 nullable: true return_url: description: 'Webhook URL to which the payment result will be sent. It must be a HTTPS url. ' type: string format: uri example: https://www.example.com tip_rates: description: 'List of tipping rates to be displayed to the cardholder. The rates are in percentage and should be between 0.01 and 0.99. The list should be sorted in ascending order. ' type: array items: format: float multipleOf: 0.01 type: number tip_timeout: description: 'Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds. It can only be set if `tip_rates` is provided. **Note**: If the target device is a Solo, it must be in version 3.3.38.0 or higher. ' type: integer example: 30 default: 30 maximum: 120 minimum: 30 total_amount: description: 'Amount structure. The amount is represented as an integer value altogether with the currency and the minor unit. For example, EUR 1.00 is represented as value 100 with minor unit of 2. ' type: object example: currency: EUR minor_unit: 2 value: 1000 properties: currency: description: Currency ISO 4217 code type: string example: EUR minor_unit: description: 'The minor units of the currency. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0. ' type: integer example: 2 minimum: 0 value: description: Integer value of the amount. type: integer example: 1000 minimum: 0 required: - currency - minor_unit - value title: Money example: aade: provider_id: '123' signature: QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5 signature_data: B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039 affiliate: app_id: com.example.app foreign_transaction_id: '123456' key: ef7b684a-d6f4-4e93-9b1b-6acdd6564a8e tags: {} card_type: debit description: This is a description... installments: 1 return_url: https://webhook.site/e21ddbb0-42c4-4358-a981-f5a95cd86fb5 tip_rates: - 0.05 - 0.1 - 0.15 tip_timeout: 60 total_amount: currency: EUR minor_unit: 2 value: 5033 required: - total_amount title: CreateReaderCheckoutRequest ReaderCheckoutStatusChange: description: The callback payload containing the status change of the Reader Checkout. type: object properties: event_type: description: Type of event. type: string example: solo.transaction.updated id: description: Unique identifier for the event. type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 payload: description: The event payload. type: object properties: client_transaction_id: description: The unique client transaction id. It is the same returned by the Checkout. type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 merchant_code: description: The merchant code associated with the transaction. type: string example: M1234567 status: description: The current status of the transaction. type: string example: successful enum: - successful - failed transaction_id: description: 'The transaction id. Deprecated: use `client_transaction_id` instead.' type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 deprecated: true required: - client_transaction_id - merchant_code - status timestamp: description: Timestamp of the event. type: string format: date-time example: 2023-10-05 14:48:00+00:00 required: - id - event_type - payload - timestamp title: ReaderCheckoutStatusChange 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: The timestamp of when the reader was last updated. type: string format: date-time example: 2023-01-20 15:16:17+00:00 required: - id - name - status - device - created_at - updated_at title: Reader 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 StatusResponse: description: Status of a device type: object properties: data: type: object properties: battery_level: description: Battery level percentage type: number format: float example: 10.5 maximum: 100 minimum: 0 battery_temperature: description: Battery temperature in Celsius type: integer example: 35 connection_type: description: Type of connection used by the device type: string example: Wi-Fi enum: - btle - edge - gprs - lte - umts - usb - Wi-Fi firmware_version: description: Firmware version of the device type: string example: 3.3.3.21 last_activity: description: Timestamp of the last activity from the device type: string format: date-time example: 2025-09-25 15:20:00+00:00 state: description: Latest state of the device type: string example: IDLE enum: - IDLE - SELECTING_TIP - WAITING_FOR_CARD - WAITING_FOR_PIN - WAITING_FOR_SIGNATURE - UPDATING_FIRMWARE status: description: Status of a device type: string example: ONLINE enum: - ONLINE - OFFLINE required: - status example: data: battery_level: 10 battery_temperature: 35 connection_type: Wi-Fi firmware_version: 3.3.3.21 last_activity: 2025-09-25 15:20:00+00:00 state: IDLE status: ONLINE required: - data title: StatusResponse 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 ReaderName: description: Custom human-readable, user-defined name for easier identification of the reader. type: string example: Frontdesk maxLength: 500 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 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 CreateReaderTerminateUnprocessableEntity: description: Unprocessable entity type: object properties: errors: type: object additionalProperties: true example: ReaderOffline: description: Error returned when the target device is not online. value: errors: detail: The device is offline. type: READER_OFFLINE required: - errors title: CreateReaderTerminateUnprocessableEntity securitySchemes: apiKey: description: API keys allow you easily interact with SumUp APIs. API keys are static tokens. You can create API keys from the [Dashboard](https://me.sumup.com/settings/api-keys) type: http scheme: Bearer oauth2: type: oauth2 description: 'SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users. To integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications). To maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.' flows: authorizationCode: authorizationUrl: https://api.sumup.com/authorize tokenUrl: https://api.sumup.com/token refreshUrl: https://api.sumup.com/token scopes: payments: Make payments by creating and processing checkouts. transactions.history: View transactions and transaction history. user.profile_readonly: View user profile details. user.profile: View and manage your user profile. user.app-settings: View and manage the SumUp mobile application settings. payment_instruments: Manage customers and their payment instruments. user.payout-settings: View and manage your payout settings. user.subaccounts: View and manage the user profile details of your employees. clientCredentials: tokenUrl: https://api.sumup.com/token scopes: payments: Make payments by creating and processing checkouts. transactions.history: View transactions and transaction history. user.profile_readonly: View user profile details. user.profile: View and manage your user profile. user.app-settings: View and manage the SumUp mobile application settings. payment_instruments: Manage customers and their payment instruments. user.payout-settings: View and manage your payout settings. user.subaccounts: View and manage the user profile details of your employee.