Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 94 additions & 37 deletions openapi.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,13 @@
{
"x-tagGroups": [
{
"name": "Readers",
"tags": [
"ReaderCheckouts",
"ReaderSettings"
]
}
],
"openapi": "3.1.0",
"info": {
"title": "SumUp REST API",
Expand Down Expand Up @@ -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.",
Expand Down Expand Up @@ -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
}
}
},
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -6282,7 +6310,6 @@
"return_url": "https://example.com/sumup/webhook",
"total_amount": {
"currency": "EUR",
"minor_unit": 2,
"value": 1500
}
},
Expand Down Expand Up @@ -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"
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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"
Expand All @@ -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",
Expand Down Expand Up @@ -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"
Expand All @@ -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",
Expand Down Expand Up @@ -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"
Expand All @@ -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",
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -9301,6 +9378,7 @@
"ALELO",
"AMEX",
"BANCOMAT",
"CARNET",
"CONECS",
"CUP",
"DINERS",
Expand Down Expand Up @@ -13015,7 +13093,6 @@
"status": "pending",
"total_amount": {
"currency": "EUR",
"minor_unit": 2,
"value": 10000
},
"updated_at": "2026-07-07T20:42:18.117244Z",
Expand Down Expand Up @@ -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": {
Expand All @@ -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,
Expand All @@ -13126,10 +13196,8 @@
},
"required": [
"currency",
"minor_unit",
"value"
],
"title": "Money",
"type": "object"
},
"updated_at": {
Expand Down Expand Up @@ -13601,7 +13669,6 @@
"tip_timeout": 60,
"total_amount": {
"currency": "EUR",
"minor_unit": 2,
"value": 5033
}
},
Expand Down Expand Up @@ -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": {
Expand All @@ -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,
Expand All @@ -13758,10 +13818,8 @@
},
"required": [
"currency",
"minor_unit",
"value"
],
"title": "Money",
"type": "object"
}
},
Expand Down Expand Up @@ -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
}
}
},
Expand Down
Loading