diff --git a/openapi.json b/openapi.json index a841579..1a0f896 100644 --- a/openapi.json +++ b/openapi.json @@ -1,4 +1,13 @@ { + "x-tagGroups": [ + { + "name": "Readers", + "tags": [ + "ReaderCheckouts", + "ReaderSettings" + ] + } + ], "openapi": "3.1.0", "info": { "title": "SumUp REST API", @@ -114,6 +123,16 @@ ], "x-displayName": "Sales" }, + { + "description": "Create, retrieve, and terminate payments on a card reader.", + "name": "ReaderCheckouts", + "x-displayName": "Checkouts" + }, + { + "description": "Retrieve and update card reader settings.", + "name": "ReaderSettings", + "x-displayName": "Settings" + }, { "name": "Tokens", "description": "Merchant tokens let your application accept card-present payments with SumUp SDKs that support token-based authentication. Use them when you want users to sign in to your application with your own authentication, then accept payments for a SumUp merchant account.\n\nCreate tokens on your backend using one of the [supported authentication methods](https://developer.sumup.com/api/authentication). Keep your authentication credentials on your backend. Return only the short-lived merchant token to your application and pass its `access_token` to the SDK.\n\nBefore returning a token, authenticate the user in your application and check that they can accept payments for the requested merchant account. A merchant token is limited to that account and the requested actions, and does not grant permissions beyond those of the identity that created it.\n\nTokens expire 15 minutes after creation. Use `expires_in` to determine the remaining lifetime and create a new token when needed. This endpoint does not return a refresh token. Treat merchant tokens as secrets: send them over HTTPS and keep them out of URLs, logs, and source code.", @@ -2365,8 +2384,7 @@ "amount": { "type": "integer", "description": "Amount to refund in minor units of the transaction's currency, for example `500` for EUR 5.00. It must be greater than zero and cannot exceed the amount eligible for a refund. Eligibility depends on the transaction and country/currency rules. If omitted, the system requests a full refund.", - "example": 500, - "minimum": 0 + "example": 500 } } }, @@ -6254,6 +6272,16 @@ "description": "Creates a Checkout for a Reader.\n\nThis process is asynchronous and the actual transaction may take some time to be started on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise checkout won't be accepted\n* 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.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.\n\n\nOptionally include an `affiliate` object to attach integrator metadata to the payment.\nProvide both `app_id` and `key` when including this object.\n", "operationId": "CreateReaderCheckout", "parameters": [ + { + "description": "Merchant for this request when the access token's user has an accepted membership for more than one merchant. Send the same value on every request in the flow. When the header is absent or blank, the merchant on the access token is used. A code with no accepted membership returns 422.", + "example": "M1234AB6", + "in": "header", + "name": "x-sumup-merchant-code", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Merchant Code", "example": "MC0X0ABC", @@ -6282,7 +6310,6 @@ "return_url": "https://example.com/sumup/webhook", "total_amount": { "currency": "EUR", - "minor_unit": 2, "value": 1500 } }, @@ -6420,10 +6447,10 @@ ], "summary": "Create a Reader Checkout", "tags": [ - "Readers" + "ReaderCheckouts" ], "x-codegen": { - "method_name": "create_checkout" + "method_name": "create" }, "x-permissions": [ "readers.checkouts.create" @@ -6439,6 +6466,16 @@ "description": "Provides the last known status for a Reader.\n\nThis 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).\n\nSupported States\n\n* `IDLE` – Reader ready for next transaction\n* `SELECTING_TIP` – Waiting for tip input\n* `WAITING_FOR_CARD` – Awaiting card insert/tap\n* `WAITING_FOR_PIN` – Waiting for PIN entry\n* `WAITING_FOR_SIGNATURE` – Waiting for customer signature\n* `UPDATING_FIRMWARE` – Firmware update in progress\n\nDevice Status\n\n* `ONLINE` – Device connected and operational\n* `OFFLINE` – Device disconnected (last state persisted)\n\n**Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher.\n", "operationId": "GetReaderStatus", "parameters": [ + { + "description": "Merchant for this request when the access token's user has an accepted membership for more than one merchant. Send the same value on every request in the flow. When the header is absent or blank, the merchant on the access token is used. A code with no accepted membership returns 422.", + "example": "M1234AB6", + "in": "header", + "name": "x-sumup-merchant-code", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Merchant Code", "example": "MC0X0ABC", @@ -6566,6 +6603,16 @@ "description": "Returns the menu lock settings for a Solo reader.\n\nFor an online reader, returns the current settings. For an offline reader,\nreturns the last saved settings, which may differ from its current configuration.\nReturns `404` if the reader is offline and no saved settings are available.\n\nThe response may include the menu lock PIN.\n", "operationId": "GetReaderSettings", "parameters": [ + { + "description": "Merchant for this request when the access token's user has an accepted membership for more than one merchant. Send the same value on every request in the flow. When the header is absent or blank, the merchant on the access token is used. A code with no accepted membership returns 422.", + "example": "M1234AB6", + "in": "header", + "name": "x-sumup-merchant-code", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "The merchant code of the account that owns the reader.", "example": "MC0X0ABC", @@ -6674,10 +6721,10 @@ ], "summary": "Get Reader Settings", "tags": [ - "Readers" + "ReaderSettings" ], "x-codegen": { - "method_name": "get_reader_settings" + "method_name": "get" }, "x-permissions": [ "readers.checkouts.view" @@ -6691,6 +6738,16 @@ "description": "Updates the menu lock settings for a Solo reader. The reader must be online.\nA successful response confirms that the reader applied the update.\n\nInclude at least one of `menu_lock.enabled` or `menu_lock.passcode`.\nOmitted settings keep their current values. The response contains only the\nsettings included in the request.\n\nWhen enabling menu lock for a reader without a PIN, include a four-digit PIN\nin `menu_lock.passcode` in the same request.\n", "operationId": "UpdateReaderSettings", "parameters": [ + { + "description": "Merchant for this request when the access token's user has an accepted membership for more than one merchant. Send the same value on every request in the flow. When the header is absent or blank, the merchant on the access token is used. A code with no accepted membership returns 422.", + "example": "M1234AB6", + "in": "header", + "name": "x-sumup-merchant-code", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "The merchant code of the account that owns the reader.", "example": "MC0X0ABC", @@ -6837,10 +6894,10 @@ ], "summary": "Update Reader Settings", "tags": [ - "Readers" + "ReaderSettings" ], "x-codegen": { - "method_name": "update_reader_settings" + "method_name": "update" }, "x-permissions": [ "readers.checkouts.create" @@ -6856,6 +6913,16 @@ "description": "Terminate a Reader Checkout stops the current transaction on the target device.\n\nThis process is asynchronous and the actual termination may take some time to be performed on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise terminate won't be accepted\n* The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.\n* There is no confirmation of the termination.\n\nIf a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher.\n", "operationId": "CreateReaderTerminate", "parameters": [ + { + "description": "Merchant for this request when the access token's user has an accepted membership for more than one merchant. Send the same value on every request in the flow. When the header is absent or blank, the merchant on the access token is used. A code with no accepted membership returns 422.", + "example": "M1234AB6", + "in": "header", + "name": "x-sumup-merchant-code", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Merchant Code", "example": "MC0X0ABC", @@ -6988,10 +7055,10 @@ ], "summary": "Terminate a Reader Checkout", "tags": [ - "Readers" + "ReaderCheckouts" ], "x-codegen": { - "method_name": "terminate_checkout" + "method_name": "terminate" }, "x-permissions": [ "readers.checkouts.delete" @@ -7007,6 +7074,16 @@ "description": "Get a Checkout for a Reader.\n", "operationId": "GetReaderCheckout", "parameters": [ + { + "description": "Merchant for this request when the access token's user has an accepted membership for more than one merchant. Send the same value on every request in the flow. When the header is absent or blank, the merchant on the access token is used. A code with no accepted membership returns 422.", + "example": "M1234AB6", + "in": "header", + "name": "x-sumup-merchant-code", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Merchant Code", "example": "MC0X0ABC", @@ -7104,10 +7181,10 @@ ], "summary": "Get a Reader Checkout", "tags": [ - "Readers" + "ReaderCheckouts" ], "x-codegen": { - "method_name": "get_checkout" + "method_name": "get" }, "x-permissions": [ "readers.checkouts.view" @@ -9301,6 +9378,7 @@ "ALELO", "AMEX", "BANCOMAT", + "CARNET", "CONECS", "CUP", "DINERS", @@ -13015,7 +13093,6 @@ "status": "pending", "total_amount": { "currency": "EUR", - "minor_unit": 2, "value": 10000 }, "updated_at": "2026-07-07T20:42:18.117244Z", @@ -13099,10 +13176,9 @@ "type": "string" }, "total_amount": { - "description": "Amount structure.\n\nThe amount is represented as an integer value altogether with the currency and the minor unit.\n\nFor example, EUR 1.00 is represented as value 100 with minor unit of 2.\n", + "description": "The checkout amount. The value uses two decimal places, even for currencies\nsuch as CLP that use zero decimal places in the create request.\n\nFor example, EUR 10.00 is returned as `1000` and CLP 1000 as `100000`.\n", "example": { "currency": "EUR", - "minor_unit": 2, "value": 1000 }, "properties": { @@ -13111,12 +13187,6 @@ "example": "EUR", "type": "string" }, - "minor_unit": { - "description": "The minor units of the currency.\nIt represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.\n", - "example": 2, - "minimum": 0, - "type": "integer" - }, "value": { "description": "Integer value of the amount.", "example": 1000, @@ -13126,10 +13196,8 @@ }, "required": [ "currency", - "minor_unit", "value" ], - "title": "Money", "type": "object" }, "updated_at": { @@ -13601,7 +13669,6 @@ "tip_timeout": 60, "total_amount": { "currency": "EUR", - "minor_unit": 2, "value": 5033 } }, @@ -13731,10 +13798,9 @@ "type": "integer" }, "total_amount": { - "description": "Amount structure.\n\nThe amount is represented as an integer value altogether with the currency and the minor unit.\n\nFor example, EUR 1.00 is represented as value 100 with minor unit of 2.\n", + "description": "Amount to charge in minor units. Use the decimal places for the currency.\nCLP, COP, and HUF use zero decimal places.\n\nFor example, send `1234` for EUR 12.34 or `1000` for CLP 1000.\n", "example": { "currency": "EUR", - "minor_unit": 2, "value": 1000 }, "properties": { @@ -13743,12 +13809,6 @@ "example": "EUR", "type": "string" }, - "minor_unit": { - "description": "The minor units of the currency.\nIt represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.\n", - "example": 2, - "minimum": 0, - "type": "integer" - }, "value": { "description": "Integer value of the amount.", "example": 1000, @@ -13758,10 +13818,8 @@ }, "required": [ "currency", - "minor_unit", "value" ], - "title": "Money", "type": "object" } }, @@ -14106,8 +14164,7 @@ "amount": { "type": "integer", "description": "Amount to refund in minor units of the transaction's currency, for example `500` for EUR 5.00. It must be greater than zero and cannot exceed the amount eligible for a refund. Eligibility depends on the transaction and country/currency rules. If omitted, the system requests a full refund.", - "example": 500, - "minimum": 0 + "example": 500 } } },