{ "openapi": "3.1.0", "info": { "title": "SumUp REST API", "version": "1.0.0", "description": "SumUp's REST API lets you create and process payments, manage saved customers and payment instruments, and retrieve transactions, payouts, and receipt details. It uses resource-oriented URLs and standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status). Send request bodies as [JSON](https://www.json.org/json-en.html) with `Content-Type: application/json`, unless an endpoint specifies another format.\n\nYou 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": "Checkouts", "description": "Checkouts represent online payment sessions that you create before attempting to charge a payer. A checkout captures the payment intent, such as the amount, currency, merchant, and optional customer or redirect settings, and then moves through its lifecycle as you process it.\n\nUse this tag to:\n- create a checkout before collecting or confirming payment details\n- process the checkout with a card, saved card, wallet, or supported alternative payment method\n- retrieve or list checkouts to inspect their current state and associated payment attempts\n- deactivate a checkout that should no longer be used\n\nTypical workflow:\n- create a checkout with the order amount, currency, and merchant information\n- process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts)\n- retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record\n\nCheckouts are used to initiate and orchestrate online payments. Transactions remain the authoritative record of the resulting payment outcome.", "x-core-objects": [ { "$ref": "#/components/schemas/Checkout" } ] }, { "name": "Customers", "description": "Customers represent payers in your integration. Create a customer with your own `customer_id` to associate their personal details and saved payment instruments with your business records.\n\nTo save a card, create a checkout for that customer with `purpose = SETUP_RECURRING_PAYMENT`, then process it with the payer's consent and mandate details. See the [tokenization guide](https://developer.sumup.com/online-payments/guides/tokenization-with-payment-sdk/).\n\nUse the Customers endpoints to create, retrieve, or update customer details and to list or deactivate saved payment instruments. For subsequent payments, process a new checkout with the saved instrument's `token` and its associated `customer_id`.", "x-core-objects": [ { "$ref": "#/components/schemas/Customer" } ] }, { "name": "Transactions", "description": "Transactions represent completed or attempted payment operations processed for a merchant account. A transaction contains the core payment result, such as the amount, currency, payment method, creation time, and current high-level status.\n\nIn addition to the main payment outcome, a transaction can contain related events that describe what happened after the original payment attempt. These events provide visibility into the financial lifecycle of the transaction, for example:\n- `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant\n- `REFUND`: money returned to the payer\n- `CHARGE_BACK`: money reversed after the original payment\n- `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback\n\nFrom an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to:\n- list transactions for reporting, reconciliation, and customer support workflows\n- retrieve a single transaction when you need the latest payment details\n- inspect `simple_status` for the current merchant-facing outcome of the payment\n- inspect `events` or `transaction_events` when you need refund, payout, or chargeback history\n\nTypical workflow:\n- create and process payments through the Checkouts endpoints\n- use the Transactions endpoints to read the resulting payment records\n- use the returned statuses and events to update your own order, accounting, or support systems" }, { "name": "Payouts", "description": "The Payouts model will allow you to track funds you’ve received from SumUp.\n\nYou can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint.", "x-core-objects": [ { "$ref": "#/components/schemas/FinancialPayouts" } ] }, { "name": "Receipts", "description": "Retrieve structured receipt data for a transaction, including payment, merchant, and acquirer details. Use this data to display a receipt in your application. The response is JSON, rather than a rendered receipt document.", "x-core-objects": [ { "$ref": "#/components/schemas/Receipt" } ] }, { "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" } ] }, { "name": "Members", "description": "Endpoints to manage account members. Members are users that have membership within merchant accounts.", "x-core-objects": [ { "$ref": "#/components/schemas/Member" } ], "x-beta": true }, { "name": "Memberships", "description": "Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.", "x-core-objects": [ { "$ref": "#/components/schemas/Membership" } ], "x-beta": true }, { "name": "Roles", "description": "Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.", "x-core-objects": [ { "$ref": "#/components/schemas/Role" } ], "x-beta": true }, { "name": "Merchants", "description": "A Merchant represents a single business which can use SumUp products like payment processing.", "x-core-objects": [ { "$ref": "#/components/schemas/Merchant" } ] }, { "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.", "x-core-objects": [ { "$ref": "#/components/schemas/Token" } ] } ], "paths": { "/v0.1/merchants/{merchant_code}/payment-methods": { "get": { "operationId": "GetPaymentMethods", "summary": "Get available payment methods", "description": "Lists the payment methods available to the merchant for checkout payments. Use the optional amount and currency filters to check eligibility for a particular payment before presenting payment options to the payer.", "tags": [ "Checkouts" ], "x-codegen": { "method_name": "list_available_payment_methods" }, "x-scopes": [], "parameters": [ { "in": "path", "name": "merchant_code", "required": true, "description": "Short unique identifier for the merchant.", "schema": { "type": "string", "example": "MH4H92C7" } }, { "in": "query", "name": "amount", "required": false, "description": "Payment amount in major units, for example `9.99` for EUR 9.99. When filtering by `amount`, also provide `currency`.", "schema": { "type": "number", "example": 9.99 } }, { "in": "query", "name": "currency", "required": false, "description": "Three-letter ISO 4217 currency code for which the payment methods should be eligible, for example `EUR`.", "schema": { "type": "string", "example": "EUR" } } ], "responses": { "200": { "description": "Available payment methods", "content": { "application/json": { "schema": { "type": "object", "properties": { "available_payment_methods": { "type": "array", "description": "Payment methods available to the merchant for the checkout.", "example": [ { "id": "apple_pay" }, { "id": "blik" } ], "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the payment method.", "example": "qr_code_pix" } } } } } }, "examples": { "success": { "description": "Available payment methods", "value": { "available_payment_methods": [ { "id": "apple_pay" }, { "id": "blik" } ] } } } } } }, "400": { "description": "The request is invalid for the submitted query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailsError" }, "examples": { "Invalid_Parameter": { "description": "One or more of the parameters are invalid.", "value": { "failed_constraints": [ { "message": "Currency must also be specified when filtering by amount", "reference": "currency" } ], "status": 400, "title": "Bad Request" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ] } }, "/v0.1/checkouts": { "post": { "operationId": "CreateCheckout", "summary": "Create a checkout", "description": "Creates a payment checkout for the specified merchant, amount, and currency. Supply a `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout does not charge a payment instrument.\n\nSet `hosted_checkout.enabled` to `true` to receive a [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL where the customer can complete the payment.\nUse `redirect_url` for redirect-based payment and 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback URL.\n\nComplete the payment through [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget).", "tags": [ "Checkouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "checkouts.write" ] } ], "x-codegen": { "method_name": "create" }, "x-scopes": [ "payments", "checkouts.write" ], "requestBody": { "required": true, "description": "Details for creating a checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCreateRequest" }, "examples": { "Checkout": { "description": "Standard request body for creating a checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "valid_until": "2030-12-31T23:59:59Z", "redirect_url": "https://sumup.com" } }, "Checkout3DS": { "description": "Create a 3DS checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com/", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase" } }, "CheckoutAPM": { "description": "Create an Alternative Payment Method checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "redirect_url": "https://mysite.com/completed_purchase" } }, "HostedCheckout": { "description": "Create a checkout with a SumUp-hosted payment page", "x-beta": true, "value": { "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d", "amount": 12, "currency": "EUR", "merchant_code": "MCXXXXXX", "description": "A sample checkout", "hosted_checkout": { "enabled": true } } } } } } }, "responses": { "201": { "description": "Returns the created checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "examples": { "Checkout": { "description": "Standard response body for a successfully created checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "merchant_country": "DE", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MH4H92C7" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ] } }, "Checkout3DS": { "description": "Response body for a successfully created 3DS checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ] } }, "CheckoutAPM": { "description": "Response body for APMs, including Blik, iDeal, ...", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2021-06-29T11:08:36.000+00:00", "merchant_name": "My company", "merchant_country": "DE", "redirect_url": "https://sumup.com", "purpose": "CHECKOUT", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ] } }, "HostedCheckout": { "description": "Response body for a checkout with a SumUp-hosted payment page", "value": { "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d", "amount": 12, "currency": "EUR", "merchant_code": "MCXXXXXX", "merchant_country": "DE", "merchant_name": "Sample Shop", "description": "A sample checkout", "id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91", "status": "PENDING", "date": "2000-01-01T12:49:24.899+00:00", "purpose": "CHECKOUT", "hosted_checkout": { "enabled": true }, "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676", "transactions": [] } } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorExtended" }, "examples": { "Missing_Parameter": { "description": "A required parameter is missing.", "value": { "message": "Validation error", "error_code": "MISSING", "param": "merchant_code" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "403": { "description": "The request isn't sufficiently authorized to create a checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have the required permission for making this request.", "value": { "error_message": "checkout_payments_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "409": { "description": "A checkout already exists for the provided unique parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Existing_Checkout": { "description": "A resource with the specified parameters already exists on the server.", "value": { "error_code": "DUPLICATED_CHECKOUT", "message": "Checkout with this checkout reference and pay to email already exists" } } } } } } } }, "get": { "operationId": "ListCheckouts", "summary": "List checkouts", "description": "Lists created checkout resources according to the applied `checkout_reference`.", "tags": [ "Checkouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "checkouts.read" ] } ], "x-codegen": { "method_name": "list" }, "x-scopes": [ "payments", "checkouts.read" ], "parameters": [ { "name": "checkout_reference", "in": "query", "description": "Filters checkouts by the merchant-defined `checkout_reference` supplied when creating the checkout. This is separate from the SumUp-generated checkout `id`.", "required": false, "schema": { "type": "string", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" } } ], "responses": { "200": { "description": "Returns a list of checkout resources.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSuccess" } }, "example": [ { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00" } ] } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } } } } }, "/v0.1/checkouts/{checkout_id}": { "parameters": [ { "name": "checkout_id", "in": "path", "required": true, "description": "SumUp-generated `id` returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.", "schema": { "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" } } ], "get": { "operationId": "GetCheckout", "summary": "Retrieve a checkout", "description": "Retrieves a checkout by its SumUp `checkout_id`. After processing a payment, returning from a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current `status` before updating your order or displaying the payment outcome to the payer.", "tags": [ "Checkouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "checkouts.read" ] } ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "payments", "checkouts.read" ], "responses": { "200": { "description": "Returns the requested checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSuccess" }, "example": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } }, "patch": { "operationId": "UpdateCheckout", "summary": "Update a checkout", "description": "Updates the amount, currency, description, reference, expiration, or customer associated with an existing checkout. Only the supplied fields are updated.\n\nThis request changes the checkout details; it does not charge a payment instrument. Process the checkout separately to attempt a payment.", "tags": [ "Checkouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "checkouts.write" ] } ], "x-codegen": { "method_name": "update" }, "x-scopes": [ "payments", "checkouts.write" ], "requestBody": { "required": true, "description": "Details for updating a checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutUpdateRequest" }, "example": { "amount": 12.5, "currency": "EUR", "description": "Updated purchase", "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670" } } } }, "responses": { "200": { "description": "Returns the updated checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "example": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 12.5, "currency": "EUR", "merchant_code": "MH4H92C7", "merchant_country": "DE", "description": "Updated purchase", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "transactions": [] } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } }, "put": { "operationId": "ProcessCheckout", "summary": "Process a checkout", "description": ":::caution[PCI DSS compliance required]\nWhen you submit raw card details directly to the Checkout API, your systems store, process, or transmit cardholder data and are therefore subject to applicable [PCI DSS requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this integration if your environment is appropriately PCI DSS compliant.\n:::\n\nProcessing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the `Create a checkout` endpoint.\n\nA processing response can require an additional payer action, such as a 3DS challenge or a payment-provider redirect. If `next_step` is returned, follow its instructions to continue the payment flow.\n\nRetrieve the checkout afterwards to confirm its payment status. Acceptance of the processing request does not by itself mean the checkout is paid.", "tags": [ "Checkouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "checkouts.write" ] } ], "x-codegen": { "method_name": "process" }, "x-scopes": [ "payments", "checkouts.write" ], "requestBody": { "required": true, "description": "Details of the payment instrument for processing the checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessCheckout" }, "examples": { "ProcessCard": { "description": "Process a checkout with a card", "value": { "payment_type": "card", "installments": 1, "mandate": { "type": "recurrent", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36", "user_ip": "172.217.169.174" }, "card": { "type": "VISA", "name": "John Doe", "number": "1234567890123456", "expiry_year": "2023", "expiry_month": "01", "cvv": "123", "zip_code": "12345" } } }, "ProcessToken": { "description": "Process a checkout with a token", "value": { "payment_type": "card", "installments": 1, "token": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50", "customer_id": "MEDKHDTI" } }, "ProcessBoleto": { "description": "Process a checkout with Boleto", "value": { "payment_type": "boleto", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "tax_id": "423.378.593-47", "address": { "country": "BR", "city": "São Paulo", "line1": "Rua Gilberto Sabino, 215", "state": "SP", "postal_code": "05425-020" } } } }, "ProcessiDeal": { "description": "Process a checkout with iDeal", "value": { "payment_type": "ideal", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "address": { "country": "NL" } } } }, "ProcessBancontact": { "description": "Process a checkout with Bancontact", "value": { "payment_type": "bancontact", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "address": { "country": "BE" } } } } } } } }, "responses": { "200": { "description": "Returns the checkout resource after a processing attempt.", "content": { "application/json": { "schema": { "title": "Checkout Success", "description": "Checkout resource returned after a synchronous processing attempt. In addition to the base checkout fields, it can include the resulting transaction identifiers and any newly created payment instrument token.", "allOf": [ { "$ref": "#/components/schemas/Checkout" }, { "type": "object", "properties": { "transaction_code": { "type": "string", "description": "Transaction code of the successful transaction with which the payment for the checkout is completed.", "readOnly": true, "example": "TEENSK4W2K" }, "transaction_id": { "type": "string", "description": "Unique identifier of the successful transaction that completed payment for the checkout.", "readOnly": true, "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" }, "merchant_name": { "type": "string", "description": "Name of the merchant.", "example": "Sample Merchant" }, "redirect_url": { "type": "string", "example": "https://mysite.com/completed_purchase", "description": "URL where the payer is redirected after a redirect-based payment or SCA flow completes." }, "payment_instrument": { "type": "object", "description": "Details of the saved payment instrument created or reused during checkout processing.", "properties": { "token": { "type": "string", "description": "Unique token of the saved payment instrument.", "example": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" } } } } } ] }, "examples": { "CheckoutSuccessCard": { "description": "Successfully processed checkout with a card", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PAID", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MH4H92C7" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201" } ], "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } }, "CheckoutSuccessToken": { "description": "Successfully processed checkout with a token", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase with token", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PAID", "date": "2020-02-29T10:56:56+00:00", "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "merchant_name": "Sample Merchant", "redirect_url": "https://mysite.com/completed_purchase", "customer_id": "831ff8d4cd5958ab5670", "payment_instrument": { "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201" } ] } }, "CheckoutSuccessBoleto": { "description": "Boleto payment initiated, awaiting payment by the payer", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "BRL", "merchant_code": "MH4H92C7", "description": "Boleto checkout", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2021-07-06T12:34:02.000+00:00", "merchant_name": "Sample shop", "boleto": { "barcode": "34191090081790614310603072340007886840000000200", "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto" }, "redirect_url": "https://website.com", "purpose": "CHECKOUT", "transactions": [ { "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679", "transaction_code": "TEN3E696NP", "merchant_code": "MH4H92C9", "amount": 10.1, "vat_amount": 6, "tip_amount": 3, "currency": "BRL", "timestamp": "2021-07-06T12:34:16.460+00:00", "status": "PENDING", "payment_type": "BOLETO", "entry_mode": "BOLETO", "installments_count": 1 } ] } }, "CheckoutSuccessiDeal": { "description": "iDEAL processing response requiring a payer redirect", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simideal", "method": "GET", "payload": { "tx": "961473700", "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz", "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5" }, "full": "https://r3.girogate.de/ti/simideal?tx=961473700\u0026rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz\u0026cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", "mechanism": [ "browser" ] } } }, "CheckoutSuccessBancontact": { "description": "Bancontact processing response requiring a payer redirect", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simbcmc", "method": "GET", "payload": { "tx": "624788471", "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB", "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc" }, "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471\u0026rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB\u0026cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", "mechanism": [ "browser" ] } } } } } } }, "202": { "description": "Returns the next required action for asynchronous checkout processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccepted" } } } }, "400": { "description": "The request body is invalid for processing the checkout.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorExtended" }, { "type": "array", "description": "List of error messages.", "items": { "$ref": "#/components/schemas/ErrorExtended" } } ] }, "examples": { "Invalid_Parameter": { "description": "A required parameter has an invalid value.", "value": { "message": "Validation error", "error_code": "INVALID", "param": "card.expiry_year" } }, "Multiple_Invalid_Parameters": { "description": "Multiple required parameters have invalid values.", "value": [ { "error_code": "INVALID", "message": "Validation error", "param": "card.name" }, { "error_code": "INVALID", "message": "Validation error", "param": "card.number" }, { "error_code": "INVALID", "message": "Validation error", "param": "card.expiry_year" } ] } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "409": { "description": "The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Checkout_Processed": { "description": "The identified checkout resource is already processed.", "value": { "error_code": "CHECKOUT_PROCESSED", "message": "Checkout is already processed" } } } } } } } }, "delete": { "operationId": "DeactivateCheckout", "summary": "Deactivate a checkout", "description": "Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.", "tags": [ "Checkouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "checkouts.write" ] } ], "x-codegen": { "method_name": "deactivate" }, "x-scopes": [ "payments", "checkouts.write" ], "responses": { "200": { "description": "Returns the checkout object after successful deactivation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "example": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "id": "817340ce-f1d9-4609-b90a-6152f8ee267a", "amount": 2, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Deletion example", "purpose": "CHECKOUT", "status": "EXPIRED", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "merchant_name": "Sample Merchant", "transactions": [] } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "409": { "description": "The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Checkout_Processed": { "description": "The identified checkout resource is already processed.", "value": { "error_code": "CHECKOUT_PROCESSED", "message": "Checkout is already processed" } } } } } } } } }, "/v0.2/checkouts/{checkout_id}/apple-pay-session": { "put": { "operationId": "CreateApplePaySession", "summary": "Create an Apple Pay session", "description": "Creates an Apple Pay merchant session for the specified checkout.\n\nUse this endpoint after the customer selects Apple Pay and before calling\n`ApplePaySession.completeMerchantValidation(...)` in the browser.\nSumUp validates the merchant session request and returns the Apple Pay\nsession object that your frontend should pass to Apple's JavaScript API.\n", "tags": [ "Checkouts" ], "parameters": [ { "name": "checkout_id", "in": "path", "required": true, "description": "SumUp-generated `id` returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.", "schema": { "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" } } ], "x-codegen": { "method_name": "create_apple_pay_session" }, "x-scopes": [], "requestBody": { "description": "Merchant validation details from the Apple Pay session in the payer's browser.", "content": { "application/json": { "schema": { "type": "object", "required": [ "context", "target" ], "properties": { "context": { "type": "string", "description": "Hostname of the website displaying the Apple Pay payment sheet, without a URL scheme or path. Use the domain registered for Apple Pay.", "format": "hostname", "example": "example.com" }, "target": { "type": "string", "description": "Apple Pay validation URL received as `validationURL` in the browser's `onvalidatemerchant` event.", "format": "uri", "example": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession" } } } } } }, "responses": { "200": { "description": "Successful request. Returns the Apple Pay merchant session object\nthat should be forwarded to the Apple Pay JS SDK to complete merchant\nvalidation and continue the payment flow.\n", "content": { "application/json": { "schema": { "type": "object" }, "example": { "displayName": "Test Account", "domainName": "pay.sumup.com", "epochTimestamp": 1775323532665, "expiresAt": 1775327132665, "merchantIdentifier": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB", "merchantSessionIdentifier": "SSH92CC412E5FCF4FAB88684914C953C0D4_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24", "nonce": "a968a2bf", "operationalAnalyticsIdentifier": "Test Account:7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB", "pspId": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB", "retries": 0, "signature": "\u003capple-pay-signature\u003e" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "array", "description": "List of error messages.", "items": { "$ref": "#/components/schemas/Error" } } ] }, "example": { "error_code": "INVALID", "message": "Bad Request" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ] } }, "/v0.1/customers": { "post": { "operationId": "CreateCustomer", "summary": "Create a customer", "description": "Creates a customer using the `customer_id` you supply. Choose an identifier that maps to the payer in your own system and reuse it when retrieving the customer or associating checkouts and saved payment instruments with them.", "tags": [ "Customers" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments", "customers.write" ] } ], "x-codegen": { "method_name": "create" }, "x-scopes": [ "payment_instruments", "customers.write" ], "requestBody": { "required": true, "description": "Details of the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "201": { "description": "Returns the customer resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "The request body is invalid.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorExtended" }, { "$ref": "#/components/schemas/CustomerValidationError" } ] }, "examples": { "Missing_Customer_ID": { "description": "The required customer identifier is missing.", "value": { "error_code": "INVALID", "message": "Validation error", "param": "customer_id" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "403": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "409": { "description": "A customer with the provided identifier already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Existing_Customer": { "description": "A resource with the specified identifier already exists on the server.", "value": { "message": "Customer already exists", "error_code": "CUSTOMER_ALREADY_EXISTS" } } } } } } } } }, "/v0.1/customers/{customer_id}": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" } } ], "get": { "operationId": "GetCustomer", "summary": "Retrieve a customer", "description": "Retrieves a saved customer using the `customer_id` you supplied when creating the customer.", "tags": [ "Customers" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments", "customers.read" ] } ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "payment_instruments", "customers.read" ], "responses": { "200": { "description": "Returns the customer resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "403": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } }, "put": { "operationId": "UpdateCustomer", "summary": "Update a customer", "description": "Updates an identified saved customer resource's personal details.\n\nThe request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.", "tags": [ "Customers" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments", "customers.write" ] } ], "x-codegen": { "method_name": "update" }, "x-scopes": [ "payment_instruments", "customers.write" ], "requestBody": { "required": true, "description": "Customer fields to update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } } } } } }, "responses": { "200": { "description": "Returns the customer resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "403": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } } }, "/v0.1/customers/{customer_id}/payment-instruments": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" } } ], "get": { "operationId": "ListPaymentInstruments", "summary": "List payment instruments", "description": "Lists all payment instrument resources that are saved for an identified customer.", "tags": [ "Customers" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments", "customers.read" ] } ], "x-codegen": { "method_name": "list_payment_instruments" }, "x-scopes": [ "payment_instruments", "customers.read" ], "responses": { "200": { "description": "Returns the list of saved payment instruments for the customer.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstrumentResponse" } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "403": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } } }, "/v0.1/customers/{customer_id}/payment-instruments/{token}": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" } }, { "name": "token", "in": "path", "required": true, "description": "Unique token identifying the card saved as a payment instrument resource.", "schema": { "type": "string", "example": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3" } } ], "delete": { "operationId": "DeactivatePaymentInstrument", "summary": "Deactivate a payment instrument", "description": "Deactivates an identified card payment instrument resource for a customer.", "tags": [ "Customers" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments", "customers.write" ] } ], "x-codegen": { "method_name": "deactivate_payment_instrument" }, "x-scopes": [ "payment_instruments", "customers.write" ], "responses": { "204": { "description": "Returns an empty response body when the operation succeeds." }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Request": { "description": "The request cannot be processed.", "value": { "error_code": "INVALID_REQUEST", "message": "bad request" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "403": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } } }, "/v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds": { "parameters": [ { "name": "merchant_code", "in": "path", "description": "Short unique identifier for the merchant.", "required": true, "schema": { "type": "string", "example": "MH4H92C7" } }, { "name": "transaction_id", "in": "path", "required": true, "description": "Unique identifier of the transaction.", "schema": { "type": "string", "example": "4ffb8dfc-7f2b-413d-a497-2ad00766585e" } } ], "post": { "operationId": "RefundTransaction", "summary": "Refund a transaction", "description": "Refunds a transaction identified by its SumUp transaction ID. Omit the request body to request a full refund, or provide `amount` for a partial refund in the transaction's currency.\n\nRetrieve the transaction afterwards to inspect its refunded amount and refund events. The transaction must be eligible for a refund; see the error responses for invalid amounts, permissions, and processing failures.", "tags": [ "Transactions" ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "refunds.write" ] } ], "x-codegen": { "method_name": "refund" }, "x-scopes": [ "payments", "refunds.write" ], "requestBody": { "description": "Optional amount for partial refunds.", "content": { "application/json": { "example": { "amount": 5 }, "schema": { "type": "object", "description": "Optional amount for partial refunds of transactions.", "properties": { "amount": { "type": "number", "format": "float", "description": "Amount to refund in major units of the transaction's currency, for example `5` 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": 5 } } } } } }, "responses": { "201": { "description": "The transaction was refunded in full or partially based on the request.", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "400": { "description": "The refund request is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Invalid_Amount": { "description": "The refund amount is invalid.", "value": { "type": "https://developer.sumup.com/problem/bad-request", "title": "Bad Request", "status": 400, "detail": "amount must be greater than zero" } } } } } }, "403": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Forbidden": { "description": "The authenticated user is not allowed to refund this transaction.", "value": { "type": "https://developer.sumup.com/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "users is not allowed to make a refund" } } } } } }, "404": { "description": "The requested transaction does not exist or does not belong to the merchant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Transaction_Not_Found": { "description": "The identified transaction was not found.", "value": { "type": "https://developer.sumup.com/problem/not-found", "title": "Not Found", "status": 404, "detail": "Transaction not found" } } } } } }, "409": { "description": "The transaction cannot be refunded due to business constraints.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Transaction_Not_Refundable": { "description": "The state of the identified transaction resource does not permit the requested operation.", "value": { "type": "https://developer.sumup.com/problem/conflict", "title": "Conflict", "status": 409, "detail": "The transaction is not refundable in its current state" } } } } } }, "422": { "description": "The refund could not be processed by the payment processor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Refund_Failed": { "description": "The payment processor rejected the refund.", "value": { "type": "https://developer.sumup.com/problem/unprocessable-entity", "title": "Unprocessable Entity", "status": 422, "detail": "Refund failed.", "errors": [ { "code": "INVALID_AMOUNT", "detail": "Amount exceeds the refundable amount", "reason": "amount_too_high", "max_refundable_amount": 1000 } ] } } } } } } } } }, "/v2.1/merchants/{merchant_code}/transactions": { "get": { "operationId": "GetTransactionV2.1", "summary": "Retrieve a transaction", "description": "Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and *one* of following parameters is required:\n- `id`\n- `transaction_code`\n- `foreign_transaction_id`\n- `client_transaction_id`", "tags": [ "Transactions" ], "security": [ { "apiKey": [] }, { "oauth2": [ "transactions.history", "transactions.read" ] } ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "transactions.history", "transactions.read" ], "parameters": [ { "name": "merchant_code", "in": "path", "description": "Short unique identifier for the merchant.", "required": true, "schema": { "type": "string", "example": "MH4H92C7" } }, { "name": "id", "in": "query", "description": "Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource).", "required": false, "schema": { "type": "string", "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } }, { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string", "example": "TEENSK4W2K" } }, { "name": "foreign_transaction_id", "in": "query", "description": "External transaction identifier supplied by the client.", "schema": { "type": "string", "example": "J13253253x1" } }, { "name": "client_transaction_id", "in": "query", "description": "Client-supplied identifier of the transaction.", "schema": { "type": "string", "example": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2" } } ], "responses": { "200": { "description": "Returns the requested transaction resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionFull" }, "example": { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201" } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } } } }, "/v2.1/merchants/{merchant_code}/transactions/history": { "get": { "operationId": "ListTransactionsV2.1", "summary": "List transactions", "description": "Lists transaction history for the merchant, with optional filters for payment type, status, and date range. The response contains the current page in `items` and pagination query strings in `links`.\n\nTo request another page, use the query string from the relevant link's `href` with this history endpoint. Use `changes_since` when retrieving transactions modified since a previous synchronization, including transactions created earlier whose status has changed.", "tags": [ "Transactions" ], "security": [ { "apiKey": [] }, { "oauth2": [ "transactions.history", "transactions.read" ] } ], "x-codegen": { "method_name": "list" }, "x-scopes": [ "transactions.history", "transactions.read" ], "parameters": [ { "name": "merchant_code", "in": "path", "description": "Short unique identifier for the merchant.", "required": true, "schema": { "type": "string", "example": "MH4H92C7" } }, { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string", "example": "TEENSK4W2K" } }, { "name": "order", "in": "query", "description": "Sort direction for the transaction history. Use `ascending` or `descending`; the default is `ascending`.", "schema": { "type": "string", "enum": [ "ascending", "descending" ], "default": "ascending" } }, { "name": "limit", "in": "query", "description": "Maximum number of transactions per page. Must be a positive integer. Defaults to `10` when omitted; a page can contain fewer results.", "schema": { "type": "integer", "example": 10 } }, { "name": "users[]", "in": "query", "description": "Filters transactions by user email. For multiple values, repeat the query parameter, for example `users[]=first@example.com\u0026users[]=second@example.com`.", "required": false, "example": [ "merchant@example.com" ], "schema": { "type": "array", "example": [ "merchant@example.com" ], "items": { "type": "string", "format": "email" } } }, { "name": "statuses[]", "in": "query", "description": "Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example `statuses[]=SUCCESSFUL\u0026statuses[]=REFUNDED`.", "required": false, "schema": { "type": "array", "example": [ "SUCCESSFUL", "REFUNDED" ], "items": { "type": "string", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "REFUNDED", "CHARGE_BACK" ] } } }, { "name": "payment_types[]", "in": "query", "description": "Filters the returned results by the specified list of payment types used for the transactions.", "required": false, "schema": { "type": "array", "example": [ "ECOM", "POS" ], "items": { "$ref": "#/components/schemas/PaymentType" } } }, { "name": "entry_modes[]", "in": "query", "description": "Filters the returned results by the specified list of entry modes.", "required": false, "schema": { "type": "array", "example": [ "CUSTOMER_ENTRY", "CHIP" ], "items": { "$ref": "#/components/schemas/EntryMode" } } }, { "name": "types[]", "in": "query", "description": "Filters the returned results by the specified list of transaction types.", "required": false, "schema": { "type": "array", "example": [ "PAYMENT", "REFUND" ], "items": { "type": "string", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ] } } }, { "name": "changes_since", "in": "query", "description": "Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2019-08-28T09:00:00Z" } }, { "name": "newest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2019-08-29T09:00:00Z" } }, { "name": "newest_ref", "in": "query", "description": "Pagination reference that returns results before the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over `newest_time` when both are provided.", "required": false, "schema": { "type": "string", "example": "090df9bf-93b7-40f1-8181-fbdb236568a1" } }, { "name": "oldest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2019-08-28T09:00:00Z" } }, { "name": "oldest_ref", "in": "query", "description": "Pagination reference that returns results after the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over `oldest_time` when both are provided.", "required": false, "schema": { "type": "string", "example": "090df9bf-93b7-40f1-8181-fbdb236568a1" } } ], "responses": { "200": { "description": "Returns a page of transaction history items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Transactions in the current result page.", "example": [ { "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "user": "merchant@example.com", "type": "PAYMENT", "payout_date": "2019-08-28", "payout_type": "BANK_ACCOUNT", "refunded_amount": 0 } ], "items": { "$ref": "#/components/schemas/TransactionHistory" } }, "links": { "type": "array", "description": "Pagination links for navigating the transaction history.", "example": [], "items": { "$ref": "#/components/schemas/TransactionsHistoryLink" } } } }, "example": { "items": [ { "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "user": "merchant@example.com", "type": "PAYMENT", "payout_date": "2019-08-28", "payout_type": "BANK_ACCOUNT", "refunded_amount": 0 } ], "links": [] } } } }, "400": { "description": "The request is invalid for the submitted query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Parameter": { "description": "A request parameter has an invalid value.", "value": { "message": "Validation error", "error_code": "INVALID" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } } } } }, "/v1.0/merchants/{merchant_code}/payouts": { "get": { "summary": "List payouts", "operationId": "ListPayoutsV1", "description": "Lists payout and payout-deduction records for the specified merchant account within the requested date range.\n\nThe response can include:\n- regular payouts (`type = PAYOUT`)\n- deduction records for refunds, chargebacks, direct debit returns, or balance adjustments\n\nResults are sorted by payout date in the requested `order`.", "tags": [ "Payouts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly", "payouts.read" ] } ], "x-codegen": { "method_name": "list" }, "x-scopes": [ "user.profile", "user.profile_readonly", "payouts.read" ], "parameters": [ { "name": "merchant_code", "in": "path", "description": "Short unique identifier for the merchant.", "required": true, "schema": { "type": "string", "example": "MH4H92C7" } }, { "in": "query", "name": "start_date", "description": "Start date of the payout period filter, inclusive, in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) `date` format (`YYYY-MM-DD`).", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-02-01" } }, { "in": "query", "name": "end_date", "description": "End date of the payout period filter, inclusive, in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) `date` format (`YYYY-MM-DD`). Must be greater than or equal to `start_date`.", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-02-29" } }, { "in": "query", "name": "format", "description": "Response format for the payout list.", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json", "example": "json" } }, { "in": "query", "name": "limit", "description": "Maximum number of payout records to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9999, "example": 10 } }, { "in": "query", "name": "order", "description": "Sort direction for the returned payouts.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "example": "desc" } } ], "responses": { "200": { "description": "Returns the list of payout and deduction records for the requested period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialPayouts" }, "example": [ { "amount": 132.45, "currency": "EUR", "date": "2024-02-29", "fee": 3.12, "id": 123456789, "reference": "payout-2024-02-29", "status": "SUCCESSFUL", "transaction_code": "TEENSK4W2K", "type": "PAYOUT" } ] }, "text/plain": { "schema": { "type": "string", "description": "CSV-formatted payout export returned when `format=csv`." }, "example": "id,type,amount,date,currency,fee,status,reference,transaction_code\n123456789,PAYOUT,132.45,2024-02-29,EUR,3.12,SUCCESSFUL,payout-2024-02-29,TEENSK4W2K" } } }, "400": { "description": "The request is invalid for the submitted query parameters.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorExtended" } }, "examples": { "Missing required dates": { "description": "Required date filters are missing.", "value": [ { "error_code": "MISSING", "message": "Validation error: required", "param": "start_date" }, { "error_code": "MISSING", "message": "Validation error: required", "param": "end_date" } ] }, "Invalid date range": { "description": "`start_date` cannot be later than `end_date`.", "value": [ { "error_code": "INVALID", "message": "negative date range" } ] } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } } } } }, "/v1.1/receipts/{transaction_id}": { "get": { "operationId": "GetReceipt", "summary": "Retrieve receipt details", "description": "Retrieves structured receipt data for a transaction belonging to the merchant specified by `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide `tx_event_id` to include a specific transaction event, such as a refund, on the receipt.", "tags": [ "Receipts" ], "security": [ { "apiKey": [] }, { "oauth2": [ "receipts.read", "transactions.history" ] } ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "receipts.read", "transactions.history" ], "parameters": [ { "in": "path", "name": "transaction_id", "description": "SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD.", "required": true, "schema": { "type": "string", "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } }, { "in": "query", "name": "mid", "description": "Short unique identifier for the merchant.", "required": true, "schema": { "type": "string", "example": "MH4H92C7" } }, { "in": "query", "name": "tx_event_id", "description": "Unique identifier of the transaction event to include on the receipt.", "required": false, "schema": { "type": "integer", "example": 9567461191 } } ], "responses": { "200": { "description": "Returns receipt details for the requested transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "transaction_data": { "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "merchant_code": "MH4H92C7", "amount": "10.10", "vat_amount": "6.00", "tip_amount": "3.00", "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "entry_mode": "CUSTOMER_ENTRY", "installments_count": 1, "process_as": "CREDIT" }, "merchant_data": { "merchant_profile": { "merchant_code": "MH4H92C7" } }, "acquirer_data": { "authorization_code": "053201" } } } } }, "400": { "description": "The request is invalid for the submitted parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Merchant_Code": { "description": "The provided merchant code is invalid.", "value": { "message": "is not a valid merchant code", "error_code": "INVALID" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "404": { "description": "The requested transaction event does not exist for the provided transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Event_Not_Found": { "description": "The provided transaction event ID cannot be found for this transaction.", "value": { "message": "No such tx event (ID=9567461191) for transaction 4ffb8dfc-7f2b-413d-a497-2ad00766585e", "error_code": "NOT_FOUND" } } } } } } } } }, "/v0/merchants/{merchant_code}/readers/{reader_id}/go-checkout": { "post": { "description": "Initiates a payment on the SumUp Go terminal identified by the reader ID.\n\nUse `client_transaction_id` as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate.", "operationId": "CreateGoReaderCheckout", "requestBody": { "required": true, "description": "Payment details to initiate on the reader.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReaderPaymentRequestParams" } } } }, "responses": { "200": { "description": "Returns the result of the payment initiated on the reader.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReaderPaymentResponse" } } } }, "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." } } } }, "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." } } } }, "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." } } } }, "422": { "description": "The request could not be processed as it violates a business rule.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://developer.sumup.com/problem/validation-error", "title": "Unprocessable Entity", "status": 422, "detail": "Validation failed." } } } } }, "summary": "Create a Go Reader Payment", "tags": [ "Readers" ], "x-scopes": [ "payments", "readers.write" ], "x-permissions": [ "readers_checkout_create" ], "x-codegen": { "method_name": "create_go_checkout", "ignore": true }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "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" } } ], "security": [ { "apiKey": [] }, { "oauth2": [ "payments", "readers.write" ] } ] } }, "/v0.1/memberships": { "get": { "summary": "List memberships", "description": "List memberships of the current user.", "tags": [ "Memberships" ], "operationId": "ListMemberships", "x-codegen": { "method_name": "list" }, "x-scopes": [ "user.profile", "user.profile_readonly" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "parameters": [ { "name": "offset", "in": "query", "description": "Offset of the first member to return.", "schema": { "type": "integer", "default": 0, "minimum": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of members to return.", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 25, "example": 10 } }, { "name": "kind", "in": "query", "description": "Filter memberships by resource kind.", "schema": { "$ref": "#/components/schemas/ResourceType" } }, { "name": "status", "in": "query", "description": "Filter the returned memberships by the membership status.", "schema": { "$ref": "#/components/schemas/MembershipStatus" } }, { "name": "resource.type", "in": "query", "description": "Filter memberships by resource kind.", "schema": { "$ref": "#/components/schemas/ResourceType" } }, { "name": "resource.attributes.sandbox", "in": "query", "description": "Filter memberships by the sandbox status of the resource the membership is in.", "schema": { "type": "boolean" } }, { "name": "resource.name", "in": "query", "description": "Filter memberships by the name of the resource the membership is in.", "schema": { "type": "string" } }, { "name": "resource.id", "in": "query", "description": "Filter memberships by the ID of the resource the membership is in.", "schema": { "type": "string" } }, { "name": "resource.parent.id", "in": "query", "allowEmptyValue": true, "description": "Filter memberships by the parent of the resource the membership is in.\nOmit both `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.", "schema": { "type": "string" } }, { "name": "resource.parent.type", "in": "query", "allowEmptyValue": true, "description": "Filter memberships by the parent of the resource the membership is in.\nOmit both `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.", "schema": { "$ref": "#/components/schemas/ResourceType" } }, { "name": "roles", "in": "query", "description": "Filter the returned memberships by role.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "role_employee", "role_accountant" ] }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Returns a list of Membership objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_count", "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "total_count": { "type": "integer", "example": 3 } } } } } }, "400": { "description": "Invalid query parameter combination.", "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." } } } }, "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." } } } } } } }, "/v0.1/merchants/{merchant_code}/members": { "get": { "parameters": [ { "name": "offset", "in": "query", "description": "Offset of the first member to return.", "schema": { "type": "integer", "default": 0, "minimum": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of members to return.", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 25, "example": 10 } }, { "name": "scroll", "in": "query", "description": "Indicates to skip count query.", "x-document": false, "schema": { "type": "boolean", "default": false, "example": true } }, { "name": "email", "in": "query", "description": "Filter the returned members by email address prefix.", "schema": { "type": "string", "example": "user" } }, { "name": "user.id", "in": "query", "description": "Search for a member by user id.", "schema": { "type": "string", "format": "uuid", "example": "245b2ead-85bf-45ff-856f-311a88a5d454" } }, { "name": "status", "in": "query", "description": "Filter the returned members by the membership status.", "schema": { "$ref": "#/components/schemas/MembershipStatus" } }, { "name": "roles", "in": "query", "description": "Filter the returned members by role.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "role_employee", "role_accountant" ] }, "style": "form", "explode": true }, { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ], "summary": "List members", "description": "Lists merchant members.", "tags": [ "Members" ], "operationId": "ListMerchantMembers", "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "merchant_read", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "members.read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "members.read" ] } ], "responses": { "200": { "description": "Returns a list of Member objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "total_count": { "type": "integer", "example": 3 } } } } } }, "404": { "description": "Merchant not found.", "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." } } } } } }, "post": { "operationId": "CreateMerchantMember", "summary": "Create a member", "description": "Adds a member to the merchant account with the specified roles.\n\nBy default, sends an invitation email to the provided address. The recipient must accept the invitation to join the account.\nWhen `is_managed_user` is `true`, creates a managed user with the provided password and optional nickname and assigns the roles directly, without sending an invitation.", "tags": [ "Members" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "members.write" ] } ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "members_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "members.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "roles" ], "properties": { "is_managed_user": { "type": "boolean", "description": "True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname." }, "email": { "type": "string", "format": "email", "description": "Email address of the member to add.", "maxLength": 256 }, "password": { "type": "string", "minLength": 8, "format": "password", "description": "Password of the member to add. Only used if `is_managed_user` is true. In the case of service accounts, the password is not used and can not be defined by the caller." }, "nickname": { "type": "string", "example": "Test User", "description": "Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only.", "maxLength": 64 }, "roles": { "type": "array", "description": "List of roles to assign to the new member.", "minItems": 1, "maxItems": 124, "items": { "type": "string", "maxLength": 64 } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" } }, "example": { "email": "karl.berg@example.com", "roles": [ "role_employee" ] } } } } }, "responses": { "201": { "description": "Returns the Member object if the creation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid request.", "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": "Merchant not found.", "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." } } } }, "429": { "description": "Too many invitations were sent to that user and the rate limit was exceeded. The Retry-After header indicates when the client can retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://developer.sumup.com/problem/too-many-requests", "title": "Too Many Requests", "status": 429, "detail": "Too many requests were sent. Please try again later." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] } }, "/v0.1/merchants/{merchant_code}/members/{member_id}": { "get": { "summary": "Retrieve a member", "description": "Retrieve a merchant member.", "tags": [ "Members" ], "operationId": "GetMerchantMember", "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "members_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "members.read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "members.read" ] } ], "responses": { "200": { "description": "Returns the Member object for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "404": { "description": "Merchant or member not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "in": "path", "name": "member_id", "description": "The ID of the member to retrieve.", "required": true, "schema": { "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ] }, "put": { "summary": "Update a member", "description": "Updates a merchant member and returns the updated member.\n\nProviding `roles` replaces the member's assigned roles and can grant or revoke access. Providing `metadata` replaces the entire metadata object.\nFor managed users, `user.nickname` changes the display name and `user.password` replaces the password. Updating the password also enables the managed user account.", "tags": [ "Members" ], "operationId": "UpdateMerchantMember", "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "members_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "members.write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "members.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "minItems": 1, "maxItems": 124, "items": { "type": "string", "maxLength": 64 } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" }, "user": { "type": "object", "description": "Allows you to update user data of managed users.", "properties": { "nickname": { "type": "string", "example": "Test User", "description": "User's nickname. Used for display purposes only.", "maxLength": 64 }, "password": { "type": "string", "format": "password", "minLength": 8, "description": "Password of the member to add. Only used if `is_managed_user` is true." } } } }, "example": { "Update member's role": { "roles": [ "role_manager" ] }, "Update managed user": { "user": { "nickname": "New Employee Name" } } } } } } }, "responses": { "200": { "description": "Returns the updated Member object if the update succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Cannot set password or nickname for an invited user.", "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." } } } }, "403": { "description": "Cannot change password for managed user. Password was already used before.", "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": "Merchant or member not found.", "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": "Cannot update member as some data conflict with existing members.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "in": "path", "name": "member_id", "description": "The ID of the member to retrieve.", "required": true, "schema": { "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ] }, "delete": { "summary": "Delete a member", "description": "Deletes a merchant member.", "tags": [ "Members" ], "operationId": "DeleteMerchantMember", "x-codegen": { "method_name": "delete" }, "x-permissions": [ { "relation": "members_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "members.write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "members.write" ] } ], "responses": { "200": { "description": "Returns an empty response if the deletion succeeded." }, "403": { "description": "Member deletion was forbidden.", "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": "Merchant or member not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "in": "path", "name": "member_id", "description": "The ID of the member to retrieve.", "required": true, "schema": { "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ] } }, "/v0.1/merchants/{merchant_code}/roles": { "get": { "summary": "List roles", "description": "List merchant's custom roles.", "tags": [ "Roles" ], "operationId": "ListMerchantRoles", "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "roles_list", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "roles.read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "roles.read" ] } ], "responses": { "200": { "description": "Returns a list of Role objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } } } }, "404": { "description": "Merchant not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] }, "post": { "operationId": "CreateMerchantRole", "summary": "Create a role", "description": "Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.", "tags": [ "Roles" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "roles.write" ] } ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "roles_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "roles.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "permissions" ], "properties": { "name": { "type": "string", "example": "Senior Shop Manager II", "description": "User-defined name of the role." }, "permissions": { "type": "array", "description": "User's permissions.", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "example": [ "catalog_access", "taxes_access", "members_access" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "description": { "type": "string", "example": "Manges the shop and the employees.", "description": "User-defined description of the role." } } } } } }, "responses": { "201": { "description": "Returns the Role object after successful custom role creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Invalid request.", "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": "Merchant not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] } }, "/v0.1/merchants/{merchant_code}/roles/{role_id}": { "get": { "summary": "Retrieve a role", "description": "Retrieve a custom role by ID.", "tags": [ "Roles" ], "operationId": "GetMerchantRole", "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "roles_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "roles.read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "roles.read" ] } ], "responses": { "200": { "description": "Returns the Role object for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "404": { "description": "Merchant or role not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "in": "path", "name": "role_id", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ] }, "delete": { "operationId": "DeleteMerchantRole", "summary": "Delete a role", "description": "Delete a custom role.", "tags": [ "Roles" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "roles.write" ] } ], "x-codegen": { "method_name": "delete" }, "x-permissions": [ { "relation": "roles_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "roles.write" ], "responses": { "200": { "description": "Returns an empty response if the role deletion succeeded." }, "400": { "description": "Invalid request.", "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": "Merchant not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "in": "path", "name": "role_id", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ] }, "patch": { "operationId": "UpdateMerchantRole", "summary": "Update a role", "description": "Updates a custom role's name, description, or permissions and returns the updated role.\n\nProviding `permissions` replaces the role's permission list and changes the access granted to members assigned to that role. Omitted fields remain unchanged.", "tags": [ "Roles" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.subaccounts", "roles.write" ] } ], "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "roles_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", "roles.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Senior Shop Manager II", "description": "User-defined name of the role." }, "permissions": { "type": "array", "description": "User's permissions.", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "example": [ "catalog_access", "taxes_access", "members_access" ] }, "description": { "type": "string", "example": "Manges the shop and the employees.", "description": "User-defined description of the role." } }, "example": { "name": "Senior Shop Manager III", "permissions": [ "catalog_edit", "taxes_access", "members_edit" ] } } } } }, "responses": { "200": { "description": "Returns the updated Role object if the update succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Invalid request.", "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": "Merchant not found.", "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "in": "path", "name": "role_id", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ] } }, "/v1/merchants/{merchant_code}": { "get": { "operationId": "GetMerchant", "summary": "Get Merchant", "description": "Returns a Merchant for a valid Merchant code.", "tags": [ "Merchants" ], "externalDocs": { "description": "Merchant documentation", "url": "https://developer.sumup.com/tools/models/merchant" }, "x-codegen": { "method_name": "get" }, "x-scopes": [ "user.profile", "user.profile_readonly" ], "x-permissions": [ "merchant_read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "responses": { "200": { "description": "Returns a Merchant for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } } }, "404": { "description": "The requested Merchant does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] } }, "/v1/merchants/{merchant_code}/persons": { "get": { "operationId": "ListPersons", "summary": "List Persons", "description": "Returns the Persons related to a Merchant.", "tags": [ "Merchants" ], "externalDocs": { "description": "Persons documentation", "url": "https://developer.sumup.com/tools/models/merchant#persons" }, "x-scopes": [ "user.profile", "user.profile_readonly" ], "x-permissions": [ "persons_read" ], "x-codegen": { "method_name": "list_persons" }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "responses": { "200": { "description": "Returns a list of Persons for a valid Merchant identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPersonsResponseBody" } } } }, "404": { "description": "The requested Merchant does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] } }, "/v1/merchants/{merchant_code}/persons/{person_id}": { "get": { "operationId": "GetPerson", "summary": "Get Person", "description": "Returns a single Person related to a Merchant.", "tags": [ "Merchants" ], "externalDocs": { "description": "Persons documentation", "url": "https://developer.sumup.com/tools/models/merchant#persons" }, "x-scopes": [ "user.profile", "user.profile_readonly" ], "x-permissions": [ "persons_read" ], "x-codegen": { "method_name": "get_person" }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "responses": { "200": { "description": "Returns a Person for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "404": { "description": "The requested Person does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } }, { "name": "person_id", "description": "Person ID", "in": "path", "required": true, "schema": { "type": "string", "example": "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z" } } ] } }, "/v0.1/merchants/{merchant_code}/readers": { "get": { "summary": "List Readers", "description": "List all readers of the merchant.", "operationId": "ListReaders", "tags": [ "Readers" ], "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "readers.list", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.read", "terminals.read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read", "terminals.read" ] } ], "responses": { "200": { "description": "Returns a list Reader objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Reader" } } } } } } }, "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] }, "post": { "summary": "Create a Reader", "operationId": "CreateReader", "description": "Create a new Reader for the merchant account.", "tags": [ "Readers" ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "readers.create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.write", "terminals.write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write", "terminals.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pairing_code", "name" ], "properties": { "pairing_code": { "$ref": "#/components/schemas/ReaderPairingCode" }, "name": { "$ref": "#/components/schemas/ReaderName" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "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-09T14:50:20.214Z", "updated_at": "2023-05-09T14:52:58.714Z" } } } } }, "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "required": true, "schema": { "type": "string", "example": "MK10CL2A" } } ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}": { "get": { "summary": "Retrieve a Reader", "description": "Retrieve a Reader.", "operationId": "GetReader", "tags": [ "Readers" ], "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "readers.view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.read", "terminals.read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read", "terminals.read" ] } ], "parameters": [ { "in": "header", "name": "If-Modified-Since", "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-30T10:38:01Z" } ] } }, { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "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." } } } } } }, "delete": { "summary": "Delete a reader", "description": "Delete a reader.", "operationId": "DeleteReader", "tags": [ "Readers" ], "x-codegen": { "method_name": "delete" }, "x-permissions": [ { "relation": "readers.delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.write", "terminals.write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write", "terminals.write" ] } ], "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "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" } } ] }, "patch": { "summary": "Update a Reader", "description": "Updates a reader's name or metadata and returns the updated reader.\n\nProviding `metadata` replaces the entire metadata object; include all entries that should be retained. Omitted fields remain unchanged.", "operationId": "UpdateReader", "tags": [ "Readers" ], "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "readers.update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.write", "terminals.write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write", "terminals.write" ] } ], "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." } } } } }, "parameters": [ { "name": "merchant_code", "description": "Short unique identifier for the merchant.", "in": "path", "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" } } ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout": { "post": { "callbacks": { "ReaderCheckoutStatusChange": { "{$request.body#/return_url}": { "post": { "callbacks": {}, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReaderCheckoutStatusChange" } } }, "required": true }, "responses": { "200": { "description": "Your server returns this code if it accepts the callback.\nIf the server returns any other code, the callback will be retried up to 5 times with exponential backoff.\n" } } } } } }, "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 Code", "example": "MC0X0ABC", "in": "path", "name": "merchant_code", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the Reader", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "in": "path", "name": "reader_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutRequest" } } }, "description": "A checkout initial attributes", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutResponse" } } }, "description": "The Checkout got successfully created for the given reader." }, "400": { "content": { "application/json": { "example": { "errors": { "detail": "Invalid affiliate key.", "type": "INVALID_AFFILIATE_KEY" } }, "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutError" } }, "application/problem+json": { "example": { "detail": "Invalid affiliate key.", "status": 400, "title": "Invalid Affiliate Key", "type": "https://developer.sumup.com/problem/invalid-affiliate-key" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Response when given params (or one of them) are invalid" }, "401": { "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" } } }, "description": "Unauthorized" }, "404": { "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" } } }, "description": "Response when given reader is not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutUnprocessableEntity" } }, "application/problem+json": { "examples": { "PaymentMethodNotAllowed": { "value": { "detail": "Payment method not allowed for this merchant.", "status": 422, "title": "Payment Method Not Allowed", "type": "https://developer.sumup.com/problem/payment-method-not-allowed" } }, "ValidationError": { "value": { "detail": "Validation failed", "status": 422, "title": "Unprocessable Content", "type": "https://developer.sumup.com/problem/validation-error" } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Response when given params (or one of them) are invalid" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "summary": "Create a Reader Checkout", "tags": [ "Readers" ], "x-codegen": { "method_name": "create_checkout" }, "x-permissions": [ "readers.checkouts.create" ], "x-scopes": [ "readers.write" ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/status": { "get": { "callbacks": {}, "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 Code", "example": "MC0X0ABC", "in": "path", "name": "merchant_code", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the Reader", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "in": "path", "name": "reader_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } }, "description": "Response with the device status." }, "400": { "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" } } }, "description": "Response when given params (or one of them) are invalid" }, "401": { "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" } } }, "description": "Response when given merchant's token is invalid" }, "404": { "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" } } }, "description": "Response when given reader is not found" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read" ] } ], "summary": "Get a Reader Status", "tags": [ "Readers" ], "x-codegen": { "method_name": "get_status" }, "x-permissions": [ "readers.view" ], "x-scopes": [ "readers.read" ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/settings": { "get": { "callbacks": {}, "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": "The merchant code of the account that owns the reader.", "example": "MC0X0ABC", "in": "path", "name": "merchant_code", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the reader.", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "in": "path", "name": "reader_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReaderSettingsResponse" } } }, "description": "Reader settings retrieved successfully." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsError" } }, "application/problem+json": { "example": { "detail": "Unauthorized", "status": 401, "title": "Unauthorized", "type": "https://developer.sumup.com/problem/unauthorized" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unauthorized" }, "404": { "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" } } }, "description": "The reader was not found, or it is offline and has no saved settings." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsUnprocessableEntity" } }, "application/problem+json": { "example": { "detail": "Reader settings are only supported for Solo readers.", "status": 422, "title": "Unsupported Device Model", "type": "https://developer.sumup.com/problem/unsupported-device-model" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The reader model is not supported, or the reader could not return its settings." } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read" ] } ], "summary": "Get Reader Settings", "tags": [ "Readers" ], "x-codegen": { "method_name": "get_reader_settings" }, "x-permissions": [ "readers.checkouts.view" ], "x-scopes": [ "readers.read" ] }, "patch": { "callbacks": {}, "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": "The merchant code of the account that owns the reader.", "example": "MC0X0ABC", "in": "path", "name": "merchant_code", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the reader.", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "in": "path", "name": "reader_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsRequest" } } }, "description": "Menu lock settings to update.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsResponse" } } }, "description": "Reader settings updated successfully." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsError" } }, "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" } } }, "description": "The request body is malformed." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsError" } }, "application/problem+json": { "example": { "detail": "Unauthorized", "status": 401, "title": "Unauthorized", "type": "https://developer.sumup.com/problem/unauthorized" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unauthorized" }, "404": { "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" } } }, "description": "The reader was not found." }, "422": { "content": { "application/json": { "example": { "errors": { "detail": "The device is offline.", "type": "READER_OFFLINE" } }, "schema": { "$ref": "#/components/schemas/UpdateReaderSettingsUnprocessableEntity" } }, "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" } } }, "description": "The settings are invalid, the reader is offline, the reader model is not supported, or the reader could not apply the update." } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "summary": "Update Reader Settings", "tags": [ "Readers" ], "x-codegen": { "method_name": "update_reader_settings" }, "x-permissions": [ "readers.checkouts.create" ], "x-scopes": [ "readers.write" ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate": { "post": { "callbacks": {}, "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 Code", "example": "MC0X0ABC", "in": "path", "name": "merchant_code", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the Reader", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "in": "path", "name": "reader_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} }, "description": "A checkout initial attributes", "required": false }, "responses": { "202": { "content": { "application/json": {} }, "description": "The Terminate action was successfully dispatched for the given reader." }, "400": { "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" } } }, "description": "Response when given params (or one of them) are invalid" }, "401": { "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" } } }, "description": "Unauthorized" }, "404": { "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" } } }, "description": "Response when given reader is not found" }, "422": { "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" } } }, "description": "Response when given params (or one of them) are invalid" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "summary": "Terminate a Reader Checkout", "tags": [ "Readers" ], "x-codegen": { "method_name": "terminate_checkout" }, "x-permissions": [ "readers.checkouts.delete" ], "x-scopes": [ "readers.write" ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout/{checkout_id}": { "get": { "callbacks": {}, "description": "Get a Checkout for a Reader.\n", "operationId": "GetReaderCheckout", "parameters": [ { "description": "Merchant Code", "example": "MC0X0ABC", "in": "path", "name": "merchant_code", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the Reader", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "in": "path", "name": "reader_id", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the Checkout", "example": "74ecff66-1655-43ed-8ce3-193f49fa602f", "in": "path", "name": "checkout_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReaderCheckoutResponse" } } }, "description": "The Checkout got successfully retrieved for the given reader." }, "401": { "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" } } }, "description": "Unauthorized" }, "404": { "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" } } }, "description": "Response when given reader or checkout is not found" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read" ] } ], "summary": "Get a Reader Checkout", "tags": [ "Readers" ], "x-codegen": { "method_name": "get_checkout" }, "x-permissions": [ "readers.checkouts.view" ], "x-scopes": [ "readers.read" ] } }, "/v0.1/merchants/{merchant_code}/tokens": { "post": { "summary": "Create a merchant token", "description": "Creates a short-lived token for the merchant account identified by `merchant_code` and the requested actions.\n\nCall this endpoint from your backend using a [supported authentication method](https://developer.sumup.com/api/authentication). You must have access to the merchant account. Before returning the token, check that the user signed in to your application is allowed to accept payments for that account.\n\nPass the returned `access_token` to the SDK. The token expires 15 minutes after creation; use `expires_in` for its remaining lifetime. To continue after it expires, create a new token through this endpoint.", "operationId": "CreateMerchantToken", "tags": [ "Tokens" ], "security": [ { "apiKey": [] }, { "oauth2": [] } ], "x-scopes": [], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "tokens.create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "parameters": [ { "in": "path", "name": "merchant_code", "description": "Unique code of the merchant account that will receive the payments.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "requestBody": { "description": "Actions the merchant token should allow.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "description": "Actions the token allows for this merchant account.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "checkout" ] }, "example": [ "checkout" ] } } }, "example": { "actions": [ "checkout" ] } } } }, "responses": { "200": { "description": "Merchant token created. Pass its access_token to the SDK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" }, "example": { "access_token": "MERCHANT_TOKEN", "token_type": "Bearer", "expires_in": 899 } } } }, "400": { "description": "The request body is invalid or contains unsupported or duplicate actions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://developer.sumup.com/problem/bad-request", "title": "Bad Request", "status": 400, "detail": "The request contains an unsupported action." } } } }, "401": { "description": "Authentication is missing, invalid, or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://developer.sumup.com/problem/unauthorized", "title": "Unauthorized", "status": 401 } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://developer.sumup.com/problem/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Token is invalid or expired." } } } }, "403": { "description": "The authenticated identity does not have permission to create tokens for this merchant account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://developer.sumup.com/problem/forbidden", "title": "Forbidden", "status": 403 } } } } } } } }, "components": { "schemas": { "AddressLegacy": { "title": "Address Legacy", "type": "object", "description": "Profile's personal address information.", "properties": { "city": { "type": "string", "description": "City name from the address.", "example": "Berlin" }, "country": { "type": "string", "description": "Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "DE" }, "line_1": { "type": "string", "description": "First line of the address with details of the street name and number.", "example": "Sample street" }, "line_2": { "type": "string", "description": "Second line of the address with details of the building, unit, apartment, and floor numbers.", "example": "ap. 5" }, "postal_code": { "type": "string", "description": "Postal code from the address.", "example": "10115" }, "state": { "type": "string", "description": "State name or abbreviation from the address.", "example": "Berlin" } } }, "Card": { "title": "Card", "type": "object", "description": "__Required when payment type is `card`.__ Details of the payment card.", "properties": { "name": { "type": "string", "description": "Name of the cardholder as it appears on the payment card.", "writeOnly": true, "example": "FIRSTNAME LASTNAME" }, "number": { "type": "string", "description": "Number of the payment card (without spaces).", "writeOnly": true, "example": "1234567890123456" }, "expiry_year": { "type": "string", "description": "Two- or four-digit expiration year in `YY` or `YYYY` format.", "writeOnly": true, "pattern": "^[0-9]{2}([0-9]{2})?$", "example": "2030" }, "expiry_month": { "type": "string", "description": "Two-digit expiration month, from `01` through `12`.", "writeOnly": true, "minLength": 2, "maxLength": 2, "pattern": "^(0[1-9]|1[0-2])$", "example": "12" }, "cvv": { "type": "string", "description": "Three or four-digit card verification value (security code) of the payment card.", "writeOnly": true, "maxLength": 4, "minLength": 3, "example": "123" }, "zip_code": { "type": "string", "description": "Required five-digit ZIP code. Applicable only to merchant users in the USA.", "writeOnly": true, "maxLength": 5, "minLength": 5, "example": "12345" }, "type": { "$ref": "#/components/schemas/CardType" } }, "required": [ "name", "number", "expiry_month", "expiry_year", "cvv", "type" ] }, "CardResponse": { "title": "Card Response", "type": "object", "description": "Details of the payment card.", "properties": { "last_4_digits": { "type": "string", "description": "Last 4 digits of the payment card number.", "readOnly": true, "minLength": 4, "maxLength": 4, "example": "3456" }, "type": { "$ref": "#/components/schemas/CardType" }, "payment_account_reference": { "type": "string", "description": "Payment Account Reference (PAR) defined by [EMVCo](https://www.emvco.com/emv-technologies/payment-tokenisation/). It links a card's primary account number (PAN) with its affiliated payment tokens, allowing transactions made with the physical card and tokenized versions of that card, such as digital wallets, to be correlated when PAR is available.\n\nThis reference cannot be used to initiate a payment and is separate from the saved payment instrument `token` used to process checkouts. Returned only when available for the card; integrations must handle its absence.", "example": "5665ABCDEFGHIJKLMNOPQRSTUVWXY" } } }, "Device": { "title": "Device", "description": "Details of the device used to create the transaction.", "type": "object", "properties": { "name": { "type": "string", "description": "Device name.", "example": "m0xx" }, "system_name": { "type": "string", "description": "Device OS.", "example": "Android" }, "model": { "type": "string", "description": "Device model.", "example": "GT-I9300" }, "system_version": { "type": "string", "description": "Device OS version.", "example": "4.3" }, "uuid": { "type": "string", "description": "Device UUID.", "example": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2" } } }, "ElvCardAccount": { "title": "ELV Card Account", "description": "Details of the ELV card account associated with the transaction.", "type": "object", "properties": { "sort_code": { "type": "string", "description": "ELV card sort code.", "example": "87096214" }, "last_4_digits": { "type": "string", "description": "ELV card account number last 4 digits.", "example": "5674" }, "sequence_no": { "type": "integer", "description": "ELV card sequence number.", "example": 1 }, "iban": { "type": "string", "description": "ELV IBAN.", "example": "DE60870962140012345674" } } }, "HostedCheckout": { "title": "Hosted Checkout", "type": "object", "description": "Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response.", "properties": { "enabled": { "type": "boolean", "description": "Whether the checkout should include a SumUp-hosted payment page.", "example": true } }, "required": [ "enabled" ] }, "Checkout": { "type": "object", "title": "Checkout", "description": "Core checkout resource returned by the Checkouts API. A checkout is created before payment processing and then updated as payment attempts, redirects, and resulting transactions are attached to it.", "properties": { "checkout_reference": { "type": "string", "maxLength": 64, "description": "Merchant-defined reference for the checkout. Use it to correlate the SumUp checkout with your own order, cart, subscription, or payment attempt in your systems.", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "amount": { "type": "number", "format": "float", "description": "Amount to be charged to the payer, expressed in major units.", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "merchant_code": { "type": "string", "description": "Short unique identifier for the merchant that receives the payment.", "example": "MH4H92C7" }, "description": { "type": "string", "description": "Short merchant-defined description shown in SumUp tools and reporting. Use it to make the checkout easier to recognize in dashboards, support workflows, and reconciliation.", "example": "Purchase" }, "return_url": { "type": "string", "format": "uri", "description": "Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.", "example": "http://example.com" }, "id": { "type": "string", "description": "Unique SumUp identifier of the checkout resource.", "readOnly": true, "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" }, "status": { "type": "string", "description": "Current high-level state of the checkout. `PENDING` means the checkout exists but is not yet completed, `PAID` means a payment succeeded, `FAILED` means the latest processing attempt failed, and `EXPIRED` means the checkout can no longer be processed.", "enum": [ "PENDING", "FAILED", "PAID", "EXPIRED" ], "example": "PENDING" }, "date": { "type": "string", "example": "2020-02-29T10:56:56+00:00", "format": "date-time", "description": "The timestamp of when the checkout was created." }, "valid_until": { "type": [ "string", "null" ], "example": "2030-12-31T23:59:59Z", "format": "date-time", "description": "Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time." }, "customer_id": { "type": "string", "description": "Merchant-scoped identifier of the customer associated with the checkout. Use it when storing payment instruments or reusing saved customer context for recurring and returning-payer flows.", "example": "831ff8d4cd5958ab5670" }, "mandate": { "$ref": "#/components/schemas/MandateResponse" }, "hosted_checkout_url": { "type": "string", "format": "uri", "description": "URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.", "readOnly": true, "example": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676" }, "transactions": { "type": "array", "description": "Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.", "example": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ], "uniqueItems": true, "items": { "allOf": [ { "$ref": "#/components/schemas/TransactionBase" }, { "$ref": "#/components/schemas/TransactionCheckoutInfo" } ] } } } }, "CheckoutCreateRequest": { "title": "Checkout Create Request", "type": "object", "description": "Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here.", "properties": { "checkout_reference": { "type": "string", "maxLength": 64, "description": "Merchant-defined reference for the new checkout, up to 64 characters. Use it to correlate the checkout with an order or payment attempt in your own system. If a checkout already exists for the supplied unique parameters, creation returns `409` with `DUPLICATED_CHECKOUT`; see the conflict response.", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "amount": { "type": "number", "format": "float", "description": "Amount to be charged to the payer, expressed in major units.", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "merchant_code": { "type": "string", "description": "Short unique identifier for the merchant that should receive the payment.", "example": "MH4H92C7" }, "description": { "type": "string", "description": "Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.", "example": "Purchase" }, "return_url": { "type": "string", "format": "uri", "description": "Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.", "example": "http://example.com/" }, "customer_id": { "type": "string", "description": "Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.", "example": "831ff8d4cd5958ab5670" }, "purpose": { "type": "string", "description": "Business purpose of the checkout. Use `CHECKOUT` for a standard payment and `SETUP_RECURRING_PAYMENT` when collecting consent and payment details for future recurring charges.", "default": "CHECKOUT", "enum": [ "CHECKOUT", "SETUP_RECURRING_PAYMENT" ] }, "valid_until": { "type": [ "string", "null" ], "example": "2030-12-31T23:59:59Z", "format": "date-time", "description": "Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time." }, "redirect_url": { "type": "string", "example": "https://mysite.com/completed_purchase", "description": "URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and recommended for card checkouts that may require [3DS](https://developer.sumup.com/online-payments/features/3ds). If it is omitted, the [Payment Widget](https://developer.sumup.com/online-payments/checkouts) can render the challenge in an iframe instead of using a full-page redirect." }, "hosted_checkout": { "$ref": "#/components/schemas/HostedCheckout" } }, "required": [ "checkout_reference", "amount", "currency", "merchant_code" ] }, "CheckoutUpdateRequest": { "title": "Checkout Update Request", "type": "object", "description": "Request body for updating an existing checkout. Include only the fields that should be changed.", "properties": { "amount": { "type": "number", "format": "float", "description": "Updated amount to be charged to the payer, expressed in major units.", "example": 12.5 }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { "type": "string", "description": "Updated short merchant-defined description shown in SumUp tools and reporting.", "example": "Updated purchase" }, "checkout_reference": { "type": "string", "maxLength": 64, "description": "Updated merchant-defined reference for the checkout.", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "valid_until": { "type": [ "string", "null" ], "example": "2030-12-31T23:59:59Z", "format": "date-time", "description": "Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable." }, "customer_id": { "type": "string", "description": "Updated merchant-scoped customer identifier associated with the checkout.", "example": "831ff8d4cd5958ab5670" } } }, "ProcessCheckout": { "title": "Process Checkout", "type": "object", "description": "Request body for attempting payment on an existing checkout. The required companion fields depend on the selected `payment_type`, for example card details, saved-card data, or payer information required by a specific payment method.", "properties": { "payment_type": { "type": "string", "description": "Payment method used for this processing attempt. It determines which additional request fields are required.", "enum": [ "card", "boleto", "ideal", "blik", "bancontact", "google_pay", "apple_pay" ], "example": "card" }, "installments": { "type": "integer", "description": "Number of installments for deferred payments. Available only to merchant users in Brazil.", "minimum": 1, "maximum": 12, "example": 1 }, "mandate": { "$ref": "#/components/schemas/MandatePayload" }, "card": { "$ref": "#/components/schemas/Card" }, "google_pay": { "type": "object", "description": "Raw `PaymentData` object received from Google Pay. Send the Google Pay response payload as-is.", "example": { "apiVersionMinor": 0, "apiVersion": 2, "paymentMethodData": { "description": "Visa •••• 1111", "tokenizationData": { "type": "PAYMENT_GATEWAY", "token": "token-data" }, "type": "CARD", "info": { "cardNetwork": "VISA", "cardDetails": "1111" } } } }, "apple_pay": { "type": "object", "description": "Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is.", "example": { "token": { "paymentData": { "data": "si2xuT2ArQo689SfE-long-token", "signature": "MIAGCSqGSIb3DQEHA-long-signature", "header": { "publicKeyHash": "PWfjDi3TSwgZ20TY/A7f3V6J/1rhHyRDCspbeljM0io=", "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaBtz7UN2MNV0qInJVEEhXy10PU0KfO6KxFjXm93oKWL6lCsxZZGDl/EKioUHVSlKgpsKGin0xvgldfxeJVgy0g==", "transactionId": "62e0568bc9258e9d0e059d745650fc8211d05ef7a7a1589a6411bf9b12cdfd04" }, "version": "EC_v1" }, "paymentMethod": { "displayName": "MasterCard 8837", "network": "MasterCard", "type": "debit" }, "transactionIdentifier": "62E0568BC9258E9D0E059D745650FC8211D05EF7A7A1589A6411BF9B12CDFD04" } } }, "token": { "type": "string", "description": "Token of a saved payment instrument returned by checkout processing or the customer's payment-instruments endpoint. To charge a saved card, set `payment_type` to `card` and provide both this `token` and the associated `customer_id` instead of raw card details.", "example": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50" }, "customer_id": { "type": "string", "description": "Customer identifier associated with the saved payment instrument. Required when `token` is provided.", "example": "MEDKHDTI" }, "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } }, "required": [ "payment_type" ] }, "CheckoutSuccess": { "title": "Checkout Success", "description": "Checkout resource returned after a synchronous processing attempt. In addition to the base checkout fields, it can include the resulting transaction identifiers and any newly created payment instrument token.", "allOf": [ { "$ref": "#/components/schemas/Checkout" }, { "type": "object", "properties": { "transaction_code": { "type": "string", "description": "Transaction code of the successful transaction with which the payment for the checkout is completed.", "readOnly": true, "example": "TEENSK4W2K" }, "transaction_id": { "type": "string", "description": "Unique identifier of the successful transaction that completed payment for the checkout.", "readOnly": true, "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" }, "merchant_name": { "type": "string", "description": "Name of the merchant.", "example": "Sample Merchant" }, "redirect_url": { "type": "string", "example": "https://mysite.com/completed_purchase", "description": "URL where the payer is redirected after a redirect-based payment or SCA flow completes." }, "payment_instrument": { "type": "object", "description": "Details of the saved payment instrument created or reused during checkout processing.", "properties": { "token": { "type": "string", "description": "Unique token of the saved payment instrument.", "example": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" } } } } } ] }, "CheckoutAccepted": { "title": "Checkout Accepted", "type": "object", "description": "Response returned when checkout processing requires an additional payer action, such as a 3DS challenge or a redirect to an external payment method page.", "properties": { "next_step": { "type": "object", "description": "Instructions for the next action the payer or client must take.", "properties": { "url": { "type": "string", "example": "https://dummy-3ds-gateway.com/cap?RID=1233\u0026VAA=A", "description": "URL to open or submit in order to continue processing." }, "method": { "type": "string", "example": "POST", "description": "HTTP method to use when following the next step." }, "redirect_url": { "type": "string", "example": "https://mysite.com/completed_purchase", "description": "Merchant URL where the payer returns after the external flow finishes." }, "mechanism": { "type": "array", "items": { "type": "string", "enum": [ "iframe", "browser" ] }, "description": "Allowed presentation mechanisms for the next step. `iframe` means the flow can be embedded, while `browser` means it can be completed through a full-page redirect.", "example": [ "iframe" ] }, "payload": { "type": "object", "description": "Parameters required to complete the next step. The exact keys depend on the payment provider and flow type.", "additionalProperties": { "type": "string" }, "example": { "PaReq": "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw==", "MD": "b1a536c0-29b9-11eb-adc1-0242ac120002", "TermUrl": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment" } } } } } }, "Customer": { "type": "object", "title": "Customer", "description": "Saved payer details identified by the `customer_id` supplied by your integration. A customer can have saved payment instruments for subsequent payments.", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "description": "Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.", "example": "831ff8d4cd5958ab5670" }, "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } } }, "CustomerValidationError": { "title": "Customer Validation Error", "description": "Details of a customer validation error.", "type": "object", "required": [ "instance", "error_code", "error_message" ], "properties": { "instance": { "type": "string", "description": "Unique identifier of this error occurrence.", "example": "32a44c6c-85d3-49e8-86bf-a5bba98c4621" }, "error_code": { "type": "string", "description": "Platform code for the error.", "example": "INVALID" }, "error_message": { "type": "string", "description": "Short description of the error.", "example": "customer_id" } } }, "Error": { "title": "Error", "type": "object", "description": "Details of an API error.", "properties": { "message": { "type": "string", "description": "Short description of the error.", "example": "Resource not found" }, "error_code": { "type": "string", "description": "Platform code for the error.", "example": "NOT_FOUND" } } }, "Problem": { "description": "A RFC 9457 problem details object.\n\nAdditional 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", "example": "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99" } }, "additionalProperties": true, "required": [ "type" ], "title": "Problem" }, "ErrorExtended": { "title": "Error Extended", "description": "Error payload with the invalid parameter reference.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "param": { "type": "string", "description": "Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, `card.name` refers to the `name` parameter embedded in the `card` object.", "example": "card.name" } } } ] }, "ErrorForbidden": { "title": "Error Forbidden", "type": "object", "description": "Details of an error returned for a forbidden request.", "properties": { "error_message": { "type": "string", "description": "Short description of the error.", "example": "request_not_allowed" }, "error_code": { "type": "string", "description": "Platform code for the error.", "example": "FORBIDDEN" }, "status_code": { "type": "string", "description": "HTTP status code for the error.", "example": "403" } } }, "DetailsError": { "title": "Details Error", "type": "object", "description": "Details of a request validation error.", "properties": { "title": { "type": "string", "description": "Short title of the error.", "example": "Bad Request" }, "details": { "type": "string", "description": "Details of the error.", "example": "One or more of the parameters are invalid." }, "status": { "type": "number", "description": "HTTP status code for the error.", "example": 400 }, "failed_constraints": { "type": "array", "description": "List of violated validation constraints.", "example": [ { "message": "Currency must also be specified when filtering by amount", "reference": "currency" } ], "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable description of the violated constraint.", "example": "Currency must also be specified when filtering by amount" }, "reference": { "type": "string", "description": "Name of the field that violated the constraint.", "example": "currency" } } } } } }, "Event": { "title": "Event", "description": "High-level transaction event details.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/TransactionEventID" }, "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "type": { "$ref": "#/components/schemas/TransactionEventType" }, "status": { "$ref": "#/components/schemas/TransactionEventStatus" }, "amount": { "type": "number", "format": "float", "description": "Amount associated with the transaction event, in major units.", "example": 10.1 }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of when the transaction event occurred.", "example": "2020-05-25T10:49:42.784Z" }, "fee_amount": { "type": "number", "format": "float", "description": "Fee associated with the transaction event, in major units.", "example": 0.25 }, "installment_number": { "type": "integer", "description": "Consecutive number of the installment associated with the event.", "example": 1 }, "deducted_amount": { "type": "number", "format": "float", "description": "Amount deducted from the merchant for the event, in major units.", "example": 10.1 }, "deducted_fee_amount": { "type": "number", "format": "float", "description": "Fee deducted from the merchant for the event, in major units.", "example": 0.25 } } }, "FinancialPayouts": { "title": "Financial Payouts", "description": "Ordered list of payout and payout-deduction records.", "type": "array", "items": { "$ref": "#/components/schemas/FinancialPayout" } }, "FinancialPayout": { "title": "Financial Payout", "description": "A single payout-related record.\n\nA record can represent either:\n- an actual payout sent to the merchant (`type = PAYOUT`)\n- a deduction applied against merchant funds for a refund, chargeback, direct debit return, or balance adjustment", "type": "object", "required": [ "id", "type", "amount", "date", "currency", "fee", "status", "reference", "transaction_code" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the payout-related record.", "example": 123456789 }, "type": { "type": "string", "description": "High-level payout record category.", "enum": [ "PAYOUT", "CHARGE_BACK_DEDUCTION", "REFUND_DEDUCTION", "DD_RETURN_DEDUCTION", "BALANCE_DEDUCTION" ], "example": "PAYOUT" }, "amount": { "type": "number", "format": "float", "description": "Amount of the payout or deduction in major units.", "example": 132.45 }, "date": { "type": "string", "format": "date", "description": "Payout date associated with the record, in `YYYY-MM-DD` format.", "example": "2024-02-29" }, "currency": { "type": "string", "description": "Three-letter ISO 4217 currency code of the payout.", "example": "EUR" }, "fee": { "type": "number", "format": "float", "description": "Fee amount associated with the payout record, in major units.", "example": 3.12 }, "status": { "type": "string", "description": "Merchant-facing outcome of the payout record.", "enum": [ "SUCCESSFUL", "FAILED" ], "example": "SUCCESSFUL" }, "reference": { "type": "string", "description": "Processor or payout reference associated with the record.", "example": "payout-2024-02-29" }, "transaction_code": { "type": "string", "description": "Transaction code of the original sale associated with the payout or deduction.", "example": "TEENSK4W2K" } } }, "Link": { "title": "Link", "type": "object", "description": "Details of a link to a related resource.", "properties": { "rel": { "type": "string", "description": "Relation of the linked resource to the current resource.", "example": "refund" }, "href": { "type": "string", "format": "uri", "description": "URL for accessing the related resource.", "example": "https://api.sumup.com/v1.0/merchants/MH4H92C7/payments/4ffb8dfc-7f2b-413d-a497-2ad00766585e/refunds" }, "type": { "type": "string", "description": "Media type of the linked resource.", "example": "application/json" }, "min_amount": { "type": "number", "format": "float", "description": "Minimum amount allowed for a refund, in major units.", "example": 0.01 }, "max_amount": { "type": "number", "format": "float", "description": "Maximum amount allowed for a refund, in major units.", "example": 10.1 } } }, "TransactionsHistoryLink": { "title": "Transactions History Link", "description": "Hypermedia link used for transaction history pagination.", "type": "object", "properties": { "rel": { "type": "string", "description": "Pagination relation indicating which page the link retrieves, for example `next`.", "example": "next" }, "href": { "type": "string", "description": "Query string to use with the transaction history endpoint when requesting the linked page. Preserve the returned pagination references and query parameters.", "example": "limit=10\u0026oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1\u0026order=ascending" } }, "required": [ "rel", "href" ] }, "MandatePayload": { "title": "Mandate Payload", "type": "object", "description": "Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments.", "properties": { "type": { "type": "string", "description": "Type of mandate to create for the saved payment instrument.", "enum": [ "recurrent" ], "example": "recurrent" }, "user_agent": { "type": "string", "description": "Browser or client user agent observed when consent was collected.", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36" }, "user_ip": { "type": "string", "description": "IP address of the payer when the mandate was accepted.", "example": "172.217.169.174" } }, "required": [ "type", "user_agent" ], "example": { "type": "recurrent", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36", "user_ip": "172.217.169.174" } }, "MandateResponse": { "title": "Mandate Response", "type": "object", "description": "Details of the mandate linked to the saved payment instrument.", "properties": { "type": { "type": "string", "description": "Type of mandate stored for the checkout or payment instrument.", "example": "recurrent" }, "status": { "type": "string", "description": "Current lifecycle status of the mandate.", "enum": [ "active", "inactive" ], "example": "active" }, "merchant_code": { "type": "string", "description": "Short unique identifier for the merchant for which the mandate is valid.", "example": "MH4H92C7" } }, "example": { "type": "recurrent", "status": "active", "merchant_code": "MH4H92C7" } }, "PaymentInstrumentResponse": { "title": "Payment Instrument Response", "type": "object", "description": "Details of a saved payment instrument.", "properties": { "token": { "type": "string", "description": "Token identifying the customer's saved payment card. Pass it as `token`, together with the associated `customer_id` and `payment_type = card`, when processing a checkout with this instrument.", "readOnly": true, "example": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3" }, "active": { "type": "boolean", "description": "Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a `DELETE` request to the resource endpoint.", "readOnly": true, "default": true }, "type": { "type": "string", "description": "Type of the payment instrument.", "enum": [ "card" ], "example": "card" }, "card": { "type": "object", "description": "Details of the payment card.", "properties": { "last_4_digits": { "type": "string", "description": "Last 4 digits of the payment card number.", "readOnly": true, "minLength": 4, "maxLength": 4, "example": "3456" }, "type": { "$ref": "#/components/schemas/CardType" } } }, "mandate": { "$ref": "#/components/schemas/MandateResponse" }, "created_at": { "type": "string", "description": "The timestamp of when the payment instrument was created.", "format": "date-time", "example": "2021-03-30T10:06:07.000+00:00" } }, "example": { "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3", "active": true, "type": "card", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MH4H92C7" }, "card": { "last_4_digits": "0001", "type": "VISA" }, "created_at": "2021-03-30T10:06:07.000+00:00" } }, "PersonalDetails": { "title": "Personal Details", "type": "object", "description": "Personal details for the customer.", "properties": { "first_name": { "type": "string", "description": "First name of the customer.", "example": "John" }, "last_name": { "type": "string", "description": "Last name of the customer.", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the customer.", "example": "user@example.com" }, "phone": { "type": "string", "description": "Phone number of the customer.", "example": "+491635559723" }, "birth_date": { "type": "string", "description": "Date of birth of the customer in `YYYY-MM-DD` format, without a time or timezone.", "format": "date", "example": "1993-12-31" }, "tax_id": { "type": "string", "description": "Identification number used for tax purposes, such as a CPF in Brazil.", "maxLength": 255, "example": "423.378.593-47" }, "address": { "$ref": "#/components/schemas/AddressLegacy" } } }, "Product": { "title": "Product", "type": "object", "description": "Product details associated with a transaction.", "properties": { "name": { "type": "string", "description": "Product name.", "example": "Purchase reader for merchant with code ME3FCAVF" }, "price_label": { "type": "string", "description": "Human-readable label for the product price.", "example": "EUR 100.00" }, "price": { "type": "number", "format": "decimal", "description": "Product price.", "example": 100 }, "vat_rate": { "type": "number", "format": "decimal", "description": "VAT rate as a decimal fraction, for example `0.19` for 19%.", "example": 0.19 }, "single_vat_amount": { "type": "number", "format": "decimal", "description": "VAT amount for a single product.", "example": 19 }, "price_with_vat": { "type": "number", "format": "decimal", "description": "Product price including VAT.", "example": 119 }, "vat_amount": { "type": "number", "format": "decimal", "description": "Total VAT amount for the product quantity.", "example": 19 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 }, "total_price": { "type": "number", "format": "decimal", "description": "Total price calculated as the product price multiplied by the quantity.", "example": 100 }, "total_with_vat": { "type": "number", "format": "decimal", "description": "Total product price including VAT.", "example": 119 } } }, "Receipt": { "type": "object", "title": "Receipt", "description": "Structured receipt details for a transaction. The transaction's `amount`, `vat_amount`, and `tip_amount`, as well as event amounts, are returned as decimal strings in major currency units, for example `\"10.10\"` for EUR 10.10.", "properties": { "transaction_data": { "$ref": "#/components/schemas/ReceiptTransaction" }, "merchant_data": { "$ref": "#/components/schemas/ReceiptMerchantData" }, "emv_data": { "type": "object", "description": "EMV-specific metadata returned for card-present payments.", "example": {} }, "acquirer_data": { "type": "object", "description": "Acquirer-specific metadata related to the card authorization.", "example": { "authorization_code": "053201", "return_code": "00" }, "properties": { "tid": { "type": "string", "description": "Identifier of the terminal used for the authorization.", "example": "12345678" }, "authorization_code": { "type": "string", "description": "Authorization code returned by the acquirer.", "example": "053201" }, "return_code": { "type": "string", "description": "Return code reported by the acquirer.", "example": "00" }, "local_time": { "type": "string", "description": "Local timestamp of the card authorization.", "example": "2020-02-29T11:56:56+01:00" } } } } }, "ReceiptEvent": { "title": "Receipt Event", "description": "Transaction event details as rendered on the receipt.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/TransactionEventID" }, "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "type": { "$ref": "#/components/schemas/TransactionEventType" }, "status": { "$ref": "#/components/schemas/TransactionEventStatus" }, "amount": { "type": "string", "format": "double", "description": "Amount associated with the transaction event, in major units.", "example": "10.10" }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of when the transaction event occurred.", "example": "2020-05-25T10:49:42.784Z" }, "receipt_no": { "type": "string", "description": "Receipt number associated with the event.", "example": "123456" } } }, "ReceiptCard": { "title": "Receipt Card", "description": "Payment card details displayed on the receipt.", "type": "object", "properties": { "last_4_digits": { "type": "string", "description": "Last four digits of the payment card number.", "example": "3456" }, "type": { "type": "string", "description": "Issuing card network of the payment card.", "example": "VISA" } } }, "ReceiptReader": { "title": "Receipt Reader", "description": "Card reader details displayed on the receipt.", "type": "object", "properties": { "code": { "type": "string", "description": "Unique identifier of the physical card reader.", "example": "U1DT3NA00-CN" }, "type": { "type": "string", "description": "Model of the physical card reader.", "example": "solo" } } }, "ReceiptMerchantData": { "title": "Receipt Merchant Data", "type": "object", "description": "Merchant details displayed on a transaction receipt.", "properties": { "merchant_profile": { "type": "object", "description": "Merchant profile details displayed on the receipt.", "properties": { "merchant_code": { "type": "string", "description": "Short unique identifier for the merchant.", "example": "MH4H92C7" }, "business_name": { "type": "string", "description": "Business name of the merchant.", "example": "Coffee House" }, "company_registration_number": { "type": "string", "description": "Company registration number of the merchant.", "example": "HRB 123456" }, "vat_id": { "type": "string", "description": "VAT identification number of the merchant.", "example": "DE123456789" }, "website": { "type": "string", "description": "Website of the merchant.", "example": "https://example.com" }, "email": { "type": "string", "description": "Email address of the merchant.", "example": "merchant@example.com" }, "language": { "type": "string", "description": "Language configured for the merchant profile.", "example": "de" }, "address": { "type": "object", "description": "Business address of the merchant.", "properties": { "address_line1": { "type": "string", "description": "First line of the merchant address.", "example": "Sample street 1" }, "address_line2": { "type": "string", "description": "Second line of the merchant address.", "example": "Floor 2" }, "city": { "type": "string", "description": "City of the merchant address.", "example": "Berlin" }, "country": { "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code of the merchant address.", "example": "DE" }, "country_en_name": { "type": "string", "description": "English name of the country in the merchant address.", "example": "Germany" }, "country_native_name": { "type": "string", "description": "Localized name of the country in the merchant address.", "example": "Deutschland" }, "region_name": { "type": "string", "description": "Region or state of the merchant address.", "example": "Berlin" }, "post_code": { "type": "string", "description": "Postal code of the merchant address.", "example": "10115" }, "landline": { "type": "string", "description": "Landline phone number of the merchant.", "example": "+493012345678" } } } } }, "locale": { "type": "string", "description": "Locale used for rendering localized receipt fields.", "example": "de-DE" } } }, "ReceiptTransaction": { "title": "Receipt Transaction", "type": "object", "description": "Transaction details displayed on a receipt.", "example": { "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "merchant_code": "MH4H92C7", "amount": "10.10", "vat_amount": "6.00", "tip_amount": "3.00", "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "entry_mode": "CUSTOMER_ENTRY", "installments_count": 1, "process_as": "CREDIT" }, "properties": { "transaction_code": { "type": "string", "description": "Transaction code returned after processing the transaction.", "example": "TEENSK4W2K" }, "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "merchant_code": { "type": "string", "description": "Short unique identifier for the merchant.", "example": "MH4H92C7" }, "amount": { "type": "string", "description": "Total transaction amount, in major units.", "example": "10.10" }, "vat_amount": { "type": "string", "description": "VAT included in the transaction amount, in major units.", "example": "6.00" }, "tip_amount": { "type": "string", "description": "Tip included in the transaction amount, in major units.", "example": "3.00" }, "currency": { "type": "string", "description": "Three-letter ISO 4217 currency code of the transaction.", "example": "EUR" }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of when the transaction was created.", "example": "2020-02-29T10:56:56.876Z" }, "status": { "type": "string", "description": "Current processing status of the transaction.", "example": "SUCCESSFUL" }, "payment_type": { "type": "string", "description": "Payment type used for the transaction.", "example": "ECOM" }, "entry_mode": { "type": "string", "description": "Entry mode of the payment details.", "example": "CUSTOMER_ENTRY" }, "verification_method": { "type": "string", "description": "Cardholder verification method.", "example": "none" }, "card_reader": { "$ref": "#/components/schemas/ReceiptReader" }, "card": { "$ref": "#/components/schemas/ReceiptCard" }, "installments_count": { "type": "integer", "description": "Number of installments.", "example": 1 }, "process_as": { "type": "string", "description": "Whether the transaction was processed as credit or debit.", "enum": [ "CREDIT", "DEBIT" ], "example": "CREDIT" }, "products": { "type": "array", "description": "Products associated with the transaction.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name.", "example": "Coffee" }, "description": { "type": "string", "description": "Product description.", "example": "Cappuccino" }, "price": { "type": "string", "format": "double", "description": "Product price.", "example": "150.0" }, "vat_rate": { "type": "string", "format": "double", "description": "VAT rate.", "example": "0.0" }, "single_vat_amount": { "type": "string", "format": "double", "description": "VAT amount for a single product.", "example": "0.0" }, "price_with_vat": { "type": "string", "format": "double", "description": "Product price including VAT.", "example": "150.0" }, "vat_amount": { "type": "string", "format": "double", "description": "Total VAT amount for the product quantity.", "example": "0.0" }, "quantity": { "type": "integer", "format": "int64", "description": "Product quantity.", "example": 1 }, "total_price": { "type": "string", "format": "double", "description": "Total price calculated as the product price multiplied by the quantity.", "example": "150.0" }, "total_with_vat": { "type": "string", "format": "double", "description": "Total product price including VAT.", "example": "150.0" } } } }, "vat_rates": { "type": "array", "description": "VAT breakdown for the transaction.", "items": { "type": "object", "properties": { "gross": { "type": "number", "format": "float", "description": "Gross amount to which the VAT rate applies.", "example": 10.1 }, "net": { "type": "number", "format": "float", "description": "Net amount to which the VAT rate applies.", "example": 8.49 }, "rate": { "type": "number", "format": "float", "description": "VAT rate applied to the transaction amount.", "example": 0.19 }, "vat": { "type": "number", "format": "float", "description": "VAT amount included in the gross amount.", "example": 1.61 } } } }, "events": { "type": "array", "description": "Transaction events displayed on the receipt.", "items": { "$ref": "#/components/schemas/ReceiptEvent" } }, "receipt_no": { "type": "string", "description": "Receipt number associated with the transaction.", "example": "123456" } } }, "TransactionEvent": { "title": "Transaction Event", "type": "object", "description": "Detailed information about a transaction event.", "properties": { "id": { "$ref": "#/components/schemas/TransactionEventID" }, "event_type": { "$ref": "#/components/schemas/TransactionEventType" }, "status": { "$ref": "#/components/schemas/TransactionEventStatus" }, "amount": { "type": "number", "format": "decimal", "description": "Amount of the event in major units of the associated transaction's currency.", "example": 58.8 }, "due_date": { "type": "string", "format": "date", "description": "Date when the transaction event is due to occur.", "example": "2020-05-25" }, "date": { "type": "string", "format": "date", "description": "Date when the transaction event occurred.", "example": "2020-05-25" }, "installment_number": { "type": "integer", "description": "Consecutive number of the installment that is paid. Applicable only to payout events, i.e. `event_type = PAYOUT`.", "example": 1 }, "timestamp": { "type": "string", "format": "date-time", "description": "Date and time of the transaction event.", "example": "2020-05-25T10:49:42.784Z" } } }, "TransactionBase": { "title": "Transaction Base", "type": "object", "description": "Core details shared by transaction resources.", "properties": { "id": { "type": "string", "description": "Unique identifier of the transaction.", "example": "6b425463-3e1b-431d-83fa-1e51c2925e99" }, "transaction_code": { "type": "string", "description": "SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the `transaction_code` query parameter. This is separate from the transaction's `id` and the card issuer's `auth_code`.", "example": "TEENSK4W2K" }, "amount": { "type": "number", "format": "float", "description": "Total amount of the transaction in major units of `currency`, for example `10.1` for EUR 10.10.", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "timestamp": { "type": "string", "example": "2020-02-29T10:56:56.876Z", "format": "date-time", "description": "The timestamp of when the transaction was created." }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "payment_type": { "$ref": "#/components/schemas/PaymentType" }, "installments_count": { "type": "integer", "description": "Number of installments for a deferred payment.", "minimum": 1, "example": 1 } } }, "TransactionCheckoutInfo": { "title": "Transaction Checkout Info", "description": "Checkout-specific fields associated with a transaction.", "type": "object", "properties": { "merchant_code": { "type": "string", "description": "Unique code of the registered merchant to whom the payment is made.", "example": "MH4H92C7" }, "vat_amount": { "type": "number", "format": "float", "description": "VAT included in the total transaction amount, in major units of the transaction's currency.", "example": 6 }, "tip_amount": { "type": "number", "format": "float", "description": "Tip included in the total transaction amount, in major units of the transaction's currency.", "example": 3 }, "entry_mode": { "$ref": "#/components/schemas/EntryMode" }, "auth_code": { "type": "string", "description": "Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.", "example": "053201" } } }, "TransactionMixinHistory": { "title": "Transaction Mixin History", "description": "Additional transaction fields used by history and detailed views.", "type": "object", "properties": { "product_summary": { "type": "string", "description": "Short description of the payment. The value is taken from the `description` property of the related checkout resource.", "example": "Purchase" }, "payouts_total": { "type": "integer", "description": "Total number of payouts to the registered user specified in the `user` property.", "example": 1 }, "payouts_received": { "type": "integer", "description": "Number of payouts that are made to the registered user specified in the `user` property.", "example": 1 }, "payout_plan": { "type": "string", "description": "Payout plan of the registered user at the time when the transaction was made.", "enum": [ "SINGLE_PAYMENT", "TRUE_INSTALLMENT", "ACCELERATED_INSTALLMENT" ], "example": "SINGLE_PAYMENT" } } }, "TransactionHistory": { "title": "Transaction History", "description": "Transaction entry returned in history listing responses.", "allOf": [ { "$ref": "#/components/schemas/TransactionBase" }, { "$ref": "#/components/schemas/TransactionMixinHistory" }, { "type": "object", "properties": { "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "client_transaction_id": { "type": "string", "description": "Client-supplied identifier of the transaction.", "example": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2" }, "user": { "type": "string", "format": "email", "description": "Email address of the registered user (merchant) to whom the payment is made.", "example": "merchant@example.com" }, "type": { "type": "string", "description": "Type of the transaction for the registered user specified in the `user` property.", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ], "example": "PAYMENT" }, "card_type": { "$ref": "#/components/schemas/CardType" }, "payout_date": { "type": "string", "format": "date", "description": "Payout date (if paid out at once).", "example": "2019-08-28" }, "payout_type": { "type": "string", "description": "Payout type.", "enum": [ "BANK_ACCOUNT", "PREPAID_CARD" ], "example": "BANK_ACCOUNT" }, "refunded_amount": { "type": "number", "format": "decimal", "description": "Total amount refunded for this transaction, in major units of the transaction's currency.", "example": 0 } } } ] }, "PaymentType": { "title": "Payment Type", "type": "string", "description": "Payment category recorded on a transaction, for example `POS` for a point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. These reporting values are separate from the lowercase `payment_type` values used to process checkouts.", "enum": [ "CASH", "POS", "ECOM", "RECURRING", "BITCOIN", "BALANCE", "MOTO", "BOLETO", "DIRECT_DEBIT", "APM", "UNKNOWN" ], "example": "ECOM" }, "EntryMode": { "title": "Entry Mode", "type": "string", "description": "How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`.", "enum": [ "BOLETO", "SOFORT", "IDEAL", "BANCONTACT", "EPS", "MYBANK", "SATISPAY", "BLIK", "P24", "GIROPAY", "PIX", "QR_CODE_PIX", "APPLE_PAY", "GOOGLE_PAY", "PAYPAL", "TWINT", "NONE", "CHIP", "MANUAL_ENTRY", "CUSTOMER_ENTRY", "MAGSTRIPE_FALLBACK", "MAGSTRIPE", "DIRECT_DEBIT", "CONTACTLESS", "MOTO", "CONTACTLESS_MAGSTRIPE", "N/A" ], "example": "CUSTOMER_ENTRY" }, "CardType": { "title": "Card Type", "type": "string", "description": "Issuing card network of the payment card used for the transaction.", "enum": [ "ALELO", "AMEX", "BANCOMAT", "CONECS", "CUP", "DINERS", "DISCOVER", "EFTPOS", "ELO", "ELV", "GIROCARD", "HIPERCARD", "INTERAC", "JCB", "MAESTRO", "MASTERCARD", "PLUXEE", "SUMUP", "SWILE", "TICKET", "VISA", "VISA_ELECTRON", "VISA_VPAY", "VPAY", "VR", "UNKNOWN" ], "example": "VISA" }, "TransactionFull": { "title": "Transaction Full", "description": "Full transaction resource with checkout, payout, and event details.", "allOf": [ { "$ref": "#/components/schemas/TransactionBase" }, { "$ref": "#/components/schemas/TransactionCheckoutInfo" }, { "$ref": "#/components/schemas/TransactionMixinHistory" }, { "type": "object", "properties": { "foreign_transaction_id": { "type": "string", "description": "External transaction identifier supplied by the client.", "example": "J13253253x1" }, "client_transaction_id": { "type": "string", "description": "Client-supplied identifier of the transaction.", "example": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2" }, "username": { "type": "string", "format": "email", "description": "Email address of the registered user (merchant) to whom the payment is made.", "example": "merchant@example.com" }, "fee_amount": { "type": "number", "format": "decimal", "description": "Total SumUp transaction fee in major units of the transaction's currency.", "example": 8 }, "lat": { "$ref": "#/components/schemas/Lat" }, "lon": { "$ref": "#/components/schemas/Lon" }, "horizontal_accuracy": { "$ref": "#/components/schemas/HorizontalAccuracy" }, "merchant_id": { "type": "integer", "format": "int64", "description": "Internal SumUp identifier of the merchant.", "example": 136902 }, "device_info": { "$ref": "#/components/schemas/Device" }, "simple_payment_type": { "type": "string", "description": "Simple name of the payment type.", "enum": [ "CASH", "CC_SIGNATURE", "ELV", "ELV_WITHOUT_SIGNATURE", "CC_CUSTOMER_ENTERED", "MANUAL_ENTRY", "EMV", "RECURRING", "BALANCE", "MOTO", "BOLETO", "APM", "BITCOIN", "CARD" ], "example": "CARD" }, "verification_method": { "type": "string", "description": "Verification method used for the transaction.", "enum": [ "none", "signature", "offline PIN", "online PIN", "offline PIN + signature", "na" ], "example": "none" }, "card": { "$ref": "#/components/schemas/CardResponse" }, "elv_account": { "$ref": "#/components/schemas/ElvCardAccount" }, "local_time": { "type": "string", "format": "date-time", "description": "Local timestamp of when the transaction was created.", "example": "2020-02-29T11:56:56+01:00" }, "payout_date": { "type": "string", "format": "date", "description": "The date of the payout.", "example": "2019-08-28" }, "payout_type": { "type": "string", "description": "Payout type for the transaction.", "enum": [ "BANK_ACCOUNT", "PREPAID_CARD" ], "example": "BANK_ACCOUNT" }, "process_as": { "type": "string", "description": "Whether the transaction was processed as credit or debit.", "enum": [ "CREDIT", "DEBIT" ], "example": "CREDIT" }, "products": { "type": "array", "description": "List of products from the merchant's catalogue for which the transaction serves as a payment.", "items": { "$ref": "#/components/schemas/Product" } }, "vat_rates": { "type": "array", "description": "List of VAT rates applicable to the transaction.", "items": { "type": "object", "properties": { "rate": { "type": "number", "format": "decimal", "description": "VAT rate.", "example": 0.045 }, "net": { "type": "number", "format": "decimal", "description": "NET amount of products having this VAT rate applied.", "example": 1.36 }, "vat": { "type": "number", "format": "decimal", "description": "VAT amount of this rate applied.", "example": 0.06 }, "gross": { "type": "number", "format": "decimal", "description": "Gross amount of products having this VAT rate applied.", "example": 1.42 } } } }, "transaction_events": { "type": "array", "description": "Detailed list of events related to the transaction.", "items": { "$ref": "#/components/schemas/TransactionEvent" } }, "simple_status": { "type": "string", "description": "High-level status of the transaction from the merchant's perspective.\n\n- `PENDING`: The payment has been initiated and is still being processed. A final outcome is not available yet.\n- `SUCCESSFUL`: The payment was completed successfully.\n- `PAID_OUT`: The payment was completed successfully and the funds have already been included in a payout to the merchant.\n- `FAILED`: The payment did not complete successfully.\n- `CANCELLED`: The payment was cancelled or reversed and is no longer payable or payable to the merchant.\n- `CANCEL_FAILED`: An attempt to cancel or reverse the payment was not completed successfully.\n- `REFUNDED`: The payment was refunded in full or in part.\n- `REFUND_FAILED`: An attempt to refund the payment was not completed successfully.\n- `CHARGEBACK`: The payment was subject to a chargeback.\n- `NON_COLLECTION`: The amount could not be collected from the merchant after a chargeback or related adjustment.", "enum": [ "SUCCESSFUL", "PAID_OUT", "CANCEL_FAILED", "CANCELLED", "CHARGEBACK", "FAILED", "REFUND_FAILED", "REFUNDED", "NON_COLLECTION", "PENDING" ], "example": "SUCCESSFUL" }, "links": { "type": "array", "description": "List of hyperlinks for accessing related resources.", "items": { "$ref": "#/components/schemas/Link" } }, "events": { "type": "array", "description": "Compact list of events related to the transaction.", "items": { "$ref": "#/components/schemas/Event" } }, "location": { "type": "object", "description": "Details of the payment location as received from the payment terminal.", "properties": { "lat": { "$ref": "#/components/schemas/Lat" }, "lon": { "$ref": "#/components/schemas/Lon" }, "horizontal_accuracy": { "$ref": "#/components/schemas/HorizontalAccuracy" } } }, "tax_enabled": { "type": "boolean", "description": "Indicates whether tax deduction is enabled for the transaction.", "example": true } } } ] }, "Currency": { "title": "Currency", "type": "string", "description": "Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount.", "enum": [ "BRL", "CHF", "CLP", "COP", "CZK", "DKK", "EUR", "GBP", "HRK", "HUF", "NOK", "PLN", "RON", "SEK", "USD" ], "example": "EUR" }, "TransactionStatus": { "title": "Transaction Status", "type": "string", "description": "Current status of the transaction.\n\n- `PENDING`: The transaction has been created but its final outcome is not known yet.\n- `SUCCESSFUL`: The transaction completed successfully.\n- `CANCELLED`: The transaction was cancelled or otherwise reversed before completion.\n- `FAILED`: The transaction attempt did not complete successfully.\n- `REFUNDED`: The transaction was refunded in full or in part.", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "PENDING", "REFUNDED" ], "example": "SUCCESSFUL" }, "TransactionEventType": { "title": "Transaction Event Type", "type": "string", "description": "Financial event associated with a transaction.\n\n- `PAYOUT`: Funds from the transaction being prepared for or included in a merchant payout. Check the event status to determine whether they have been paid out.\n- `REFUND`: Money returned to the payer.\n- `CHARGE_BACK`: A reversal of the payment following a chargeback.\n- `PAYOUT_DEDUCTION`: An amount deducted from a merchant payout, for example to cover a refund or chargeback.", "enum": [ "PAYOUT", "CHARGE_BACK", "REFUND", "PAYOUT_DEDUCTION" ], "example": "REFUND" }, "TransactionEventStatus": { "title": "Transaction Event Status", "type": "string", "description": "Status of the transaction event.\n\nNot every value is used for every event type.\n\n- `PENDING`: The event has been created but is not final yet. Used for events that are still being processed and whose final outcome is not known yet.\n- `SCHEDULED`: The event is planned for a future payout cycle but has not been executed yet. This applies to payout events before money is actually sent out.\n- `RECONCILED`: The underlying payment has been matched with settlement data and is ready to continue through payout processing, but the funds have not been paid out yet. This applies to payout events.\n- `PAID_OUT`: The payout event has been completed and the funds were included in a merchant payout.\n- `REFUNDED`: A refund event has been accepted and recorded in the refund flow. This is the status returned for refund events once the transaction amount is being or has been returned to the payer.\n- `SUCCESSFUL`: The event completed successfully. Use this as the generic terminal success status for event types that do not expose a more specific business outcome such as `PAID_OUT` or `REFUNDED`.\n- `FAILED`: The event could not be completed. Typical examples are a payout that could not be executed or an event that was rejected during processing.", "enum": [ "FAILED", "PAID_OUT", "PENDING", "RECONCILED", "REFUNDED", "SCHEDULED", "SUCCESSFUL" ], "example": "SUCCESSFUL" }, "TransactionEventID": { "title": "Transaction Event ID", "type": "integer", "format": "int64", "description": "Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting receipt details for a specific event. This is separate from the transaction ID and the transaction history pagination references.", "example": 9567461191 }, "HorizontalAccuracy": { "title": "Horizontal Accuracy", "type": "number", "format": "float", "description": "Indication of the precision of the geographical position received from the payment terminal.", "example": 5 }, "Lat": { "title": "Latitude", "type": "number", "format": "float", "description": "Latitude value from the coordinates of the payment location (as received from the payment terminal reader).", "minimum": -90, "maximum": 90, "example": 52.520008 }, "Lon": { "title": "Longitude", "type": "number", "format": "float", "description": "Longitude value from the coordinates of the payment location (as received from the payment terminal reader).", "minimum": -180, "maximum": 180, "example": 13.404954 }, "TransactionID": { "title": "Transaction ID", "type": "string", "description": "Unique identifier of the transaction.", "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" }, "Affiliate": { "properties": { "app_id": { "example": "com.example.app", "type": "string" }, "key": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, "required": [ "app_id", "key" ], "type": "object" }, "Amount": { "properties": { "currency": { "description": "Currency ISO 4217 code", "example": "MXN", "type": "string" }, "value": { "description": "Amount in minor units (e.g. cents).", "example": 1000, "type": "integer" } }, "required": [ "currency", "value" ], "type": "object" }, "ReaderID": { "type": "string", "description": "Unique identifier of the reader that the payment is initiated on.", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "minLength": 30, "maxLength": 30 }, "ReaderPaymentRequestParams": { "properties": { "affiliate": { "allOf": [ { "description": "Optional caller-supplied context about the integration initiating the payment.", "type": "object" }, { "$ref": "#/components/schemas/Affiliate" } ] }, "client_transaction_id": { "description": "Caller-supplied correlation identifier, used as the idempotency key.", "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f", "type": "string" }, "tip_amount": { "description": "Portion of total_amount that is a tip, in minor units.", "example": 200, "type": "integer" }, "total_amount": { "allOf": [ { "description": "Amount charged on the reader, including any tip. The amount is represented as an integer value altogether with the currency and the minor unit. For example, MXN 10.00 is represented as value 1000 with minor unit of 2.", "example": { "currency": "MXN", "value": 1000 } }, { "$ref": "#/components/schemas/Amount" } ] } }, "required": [ "total_amount", "client_transaction_id" ], "type": "object" }, "ReaderPaymentResponse": { "properties": { "data": { "$ref": "#/components/schemas/ReaderPaymentResponseData" } }, "type": "object" }, "ReaderPaymentResponseData": { "properties": { "client_transaction_id": { "description": "Caller-supplied correlation identifier that was provided in the request.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string" }, "transaction_code": { "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", "example": "TEENSK4W2K", "type": "string" } }, "type": "object" }, "MembershipStatus": { "type": "string", "description": "The status of the membership.", "enum": [ "accepted", "pending", "expired", "disabled", "unknown" ] }, "ResourceType": { "type": "string", "description": "The type of the membership resource.\nPossible values are:\n* `merchant` - merchant account(s)\n* `organization` - organization(s)", "example": "merchant" }, "Membership": { "title": "Membership", "type": "object", "description": "A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.", "required": [ "id", "resource_id", "type", "roles", "permissions", "created_at", "updated_at", "status", "resource" ], "properties": { "id": { "type": "string", "description": "ID of the membership.", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "resource_id": { "type": "string", "description": "ID of the resource the membership is in.", "example": "M2DDT39A" }, "type": { "$ref": "#/components/schemas/ResourceType" }, "roles": { "type": "array", "description": "User's roles.", "example": [ "role_admin" ], "items": { "type": "string" } }, "permissions": { "type": "array", "description": "User's permissions.", "deprecated": true, "x-deprecation-notice": "Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.", "items": { "type": "string" }, "example": [ "members_read", "members_write", "create_moto_payments", "full_transaction_history_view", "refund_transactions", "create_referral", "developer_settings_edit", "developer_settings_access" ] }, "created_at": { "type": "string", "description": "The timestamp of when the membership was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "type": "string", "description": "The timestamp of when the membership was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "invite": { "$ref": "#/components/schemas/Invite" }, "status": { "$ref": "#/components/schemas/MembershipStatus" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" }, "resource": { "$ref": "#/components/schemas/MembershipResource" } } }, "MembershipResource": { "title": "Resource", "type": "object", "description": "Information about the resource the membership is in.", "required": [ "id", "type", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "ID of the resource the membership is in.", "example": "M2DDT39A" }, "type": { "$ref": "#/components/schemas/ResourceType" }, "name": { "type": "string", "description": "Display name of the resource.", "example": "Acme Corp" }, "logo": { "type": "string", "description": "Logo fo the resource.", "format": "uri", "maxLength": 256, "example": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png" }, "created_at": { "type": "string", "description": "The timestamp of when the membership resource was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "type": "string", "description": "The timestamp of when the membership resource was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "attributes": { "$ref": "#/components/schemas/Attributes" } } }, "Member": { "title": "Member", "type": "object", "description": "A member is user within specific resource identified by resource id, resource type, and associated roles.", "required": [ "id", "roles", "permissions", "created_at", "updated_at", "status" ], "properties": { "id": { "type": "string", "description": "ID of the member.", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "roles": { "type": "array", "description": "User's roles.", "example": [ "role_admin" ], "items": { "type": "string" } }, "permissions": { "type": "array", "description": "User's permissions.", "deprecated": true, "x-deprecation-notice": "Permissions include only legacy permissions, please use roles instead. Member access is based on roles within a given resource and the permissions these roles grant.", "items": { "type": "string" }, "example": [ "members_read", "members_write", "create_moto_payments", "full_transaction_history_view", "refund_transactions", "create_referral", "developer_settings_edit", "developer_settings_access" ] }, "created_at": { "type": "string", "description": "The timestamp of when the member was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "type": "string", "description": "The timestamp of when the member was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "user": { "$ref": "#/components/schemas/MembershipUser" }, "invite": { "$ref": "#/components/schemas/Invite" }, "status": { "$ref": "#/components/schemas/MembershipStatus" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" } }, "example": { "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", "roles": [ "role_admin", "role_owner" ], "permissions": [ "members_read", "members_write", "create_moto_payments", "full_transaction_history_view", "refund_transactions", "create_referral", "developer_settings_edit", "developer_settings_access" ], "created_at": "2023-01-20T15:16:17Z", "updated_at": "2023-02-20T15:16:17Z", "user": { "id": "44ca0f5b-813b-46e1-aee7-e6242010662e", "email": "example@sumup.com", "mfa_on_login_enabled": true, "virtual_user": false, "service_account_user": false }, "status": "accepted" } }, "Invite": { "title": "Invite", "type": "object", "description": "Pending invitation for membership.", "required": [ "email", "expires_at" ], "properties": { "email": { "type": "string", "description": "Email address of the invited user.", "format": "email", "example": "boaty.mcboatface@sumup.com" }, "expires_at": { "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" } } }, "MembershipUser": { "type": "object", "description": "Information about the user associated with the membership.", "required": [ "id", "type", "email", "mfa_on_login_enabled", "virtual_user", "service_account_user" ], "properties": { "id": { "type": "string", "description": "Identifier for the End-User (also called Subject).", "example": "44ca0f5b-813b-46e1-aee7-e6242010662e" }, "type": { "$ref": "#/components/schemas/UserType" }, "email": { "type": "string", "example": "example@sumup.com", "description": "End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead." }, "mfa_on_login_enabled": { "type": "boolean", "example": true, "description": "True if the user has enabled MFA on login." }, "virtual_user": { "type": "boolean", "deprecated": true, "x-deprecation-notice": "Rely on `type` instead.", "example": false, "description": "True if the user is a virtual user (operator)." }, "service_account_user": { "type": "boolean", "deprecated": true, "x-deprecation-notice": "Rely on `type` instead.", "example": false, "description": "True if the user is a service account." }, "disabled_at": { "type": "string", "format": "date-time", "description": "Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`)." }, "nickname": { "type": "string", "example": "Test User", "description": "User's nickname. Used for display purposes only." }, "picture": { "type": "string", "format": "uri", "example": "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png", "description": "URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image." }, "classic": { "$ref": "#/components/schemas/MembershipUserClassic" } } }, "MembershipUserClassic": { "type": "object", "description": "Classic identifiers of the user.", "deprecated": true, "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "minimum": 0, "maximum": 2147483647 } } }, "Role": { "title": "Role", "type": "object", "description": "A custom role that can be used to assign set of permissions to members.", "required": [ "id", "name", "permissions", "is_predefined", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the role.", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "name": { "type": "string", "example": "Senior Shop Manager II", "description": "User-defined name of the role." }, "description": { "type": "string", "example": "Manges the shop and the employees.", "description": "User-defined description of the role." }, "permissions": { "type": "array", "description": "List of permission granted by this role.", "maxItems": 100, "items": { "type": "string" }, "example": [] }, "is_predefined": { "type": "boolean", "example": true, "description": "True if the role is provided by SumUp." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "created_at": { "type": "string", "description": "The timestamp of when the role was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "type": "string", "description": "The timestamp of when the role was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" } } }, "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", "maxProperties": 64, "example": {}, "additionalProperties": true }, "Attributes": { "description": "Object attributes that are modifiable only by SumUp applications.\n", "type": "object", "example": {}, "additionalProperties": true }, "UserType": { "type": "string", "description": "Type of the user account.", "enum": [ "user", "managed_user", "service_account", "system_account" ], "example": "user" }, "Address": { "externalDocs": { "description": "Address documentation", "url": "https://developer.sumup.com/tools/glossary/address" }, "description": "An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, `city` is `post_town`. In the United States, the top-level administrative unit used in addresses is `state`, whereas in Chile it's `region`.\nWhether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.", "type": "object", "required": [ "country" ], "properties": { "street_address": { "type": "array", "maxItems": 2, "items": { "type": "string", "description": "The first line of the address.", "maxLength": 100 }, "example": [ "Paul-Linke-Ufer 39-40", "2. Hinterhof" ] }, "post_code": { "type": "string", "description": "The postal code (aka. zip code) of the address.\n", "maxLength": 10, "example": "10999" }, "country": { "allOf": [ { "description": "The ISO3166-1 Alpha-2 code of the address country.\n", "example": "DE" }, { "$ref": "#/components/schemas/CountryCode" } ] }, "city": { "type": "string", "description": "The city of the address.\n", "maxLength": 60, "example": "Berlin" }, "province": { "type": "string", "description": "The province where the address is located. This may not be relevant in some countries.\n", "maxLength": 60, "example": "Berlin" }, "region": { "type": "string", "description": "The region where the address is located. This may not be relevant in some countries.\n", "maxLength": 60, "example": "Baden Wuerttemberg" }, "county": { "type": "string", "description": "A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.\n", "maxLength": 60, "example": "Dublin County" }, "autonomous_community": { "type": "string", "description": "In Spain, an autonomous community is the first sub-national level of political and administrative division.\n", "maxLength": 60, "example": "Catalonia" }, "post_town": { "type": "string", "description": "A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.\n", "maxLength": 60, "example": "London" }, "state": { "type": "string", "description": "Most often, a country has a single state, with various administrative divisions. The term \"state\" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.\n", "maxLength": 60, "example": "California" }, "neighborhood": { "type": "string", "description": "Locality level of the address. Used in countries such as Brazil or Chile.\n", "maxLength": 60, "example": "Copacabana" }, "commune": { "type": "string", "description": "In many countries, terms cognate with \"commune\" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.\n", "maxLength": 60, "example": "Providencia" }, "department": { "type": "string", "description": "A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.\n", "maxLength": 60, "example": "Antioquia" }, "municipality": { "type": "string", "description": "A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.\n", "maxLength": 60, "example": "Medellín" }, "district": { "type": "string", "description": "A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.\n", "maxLength": 60, "example": "Lisbon District" }, "zip_code": { "type": "string", "description": "A US system of postal codes used by the United States Postal Service (USPS).\n", "maxLength": 10, "example": "94103" }, "eircode": { "type": "string", "description": "A postal address in Ireland.\n", "maxLength": 10, "example": "D02 X285" } }, "example": { "street_address": [ "Paul-Linke-Ufer 39-40", "2. Hinterhof" ], "post_code": "10999", "city": "Berlin", "country": "DE" } }, "CountryCode": { "description": "An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)\ncountry code. This definition users `oneOf` with a two-character string\ntype to allow for support of future countries in client code.", "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "BR" }, "PersonalIdentifiers": { "type": "array", "description": "A list of country-specific personal identifiers.", "items": { "$ref": "#/components/schemas/PersonalIdentifier" }, "maxItems": 32, "example": [ { "ref": "br.cpf", "value": "847.060.136-90" } ] }, "PersonalIdentifier": { "type": "object", "required": [ "ref", "value" ], "properties": { "ref": { "type": "string", "description": "The unique reference for the personal identifier type.", "example": "br.cpf", "maxLength": 32 }, "value": { "type": "string", "description": "The personal identifier value.", "example": "847.060.136-90", "maxLength": 128 } }, "example": { "ref": "br.cpf", "value": "847.060.136-90" } }, "ListPersonsResponseBody": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } } } }, "Merchant": { "title": "Merchant", "externalDocs": { "description": "Merchant documentation", "url": "https://developer.sumup.com/tools/glossary/merchant" }, "allOf": [ { "type": "object", "required": [ "merchant_code", "country", "default_currency", "default_locale" ], "properties": { "merchant_code": { "type": "string", "readOnly": true, "description": "Short unique identifier for the merchant.", "example": "MK01A8C2" }, "organization_id": { "type": "string", "description": "ID of the organization the merchant belongs to (if any).", "example": "G0UZPVAX" }, "business_type": { "type": "string", "description": "The business type.\n* `sole_trader`: The business is run by an self-employed individual.\n* `company`: The business is run as a company with one or more shareholders\n* `partnership`: The business is run as a company with two or more shareholders that can be also other legal entities\n* `non_profit`: The business is run as a nonprofit organization that operates for public or social benefit\n* `government_entity`: The business is state owned and operated\n" }, "company": { "$ref": "#/components/schemas/Company" }, "country": { "$ref": "#/components/schemas/CountryCode" }, "business_profile": { "$ref": "#/components/schemas/BusinessProfile" }, "avatar": { "type": "string", "format": "uri", "description": "A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see `merchant.business_profile.branding`.\n" }, "alias": { "type": "string", "description": "A user-facing name of the merchant account for use in dashboards and other user-facing applications. For customer-facing business name see `merchant.business_profile`.\n" }, "default_currency": { "type": "string", "readOnly": true, "description": "Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account.\n", "example": "EUR", "minLength": 3, "maxLength": 3 }, "default_locale": { "type": "string", "description": "Merchant's default locale, represented as a BCP47 [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646) language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1](https://www.iso.org/iso-639-language-code) language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1](https://www.iso.org/iso-3166-country-codes.html) country code in uppercase, separated by a dash. For example, en-US or fr-CA.\nIn multilingual countries this is the merchant's preferred locale out of those, that are officially spoken in the country. In a countries with a single official language this will match the official language.", "example": "de-DE", "minLength": 2, "maxLength": 5 }, "sandbox": { "type": "boolean", "description": "True if the merchant is a sandbox for testing.", "example": false }, "meta": { "$ref": "#/components/schemas/Meta" }, "classic": { "$ref": "#/components/schemas/ClassicMerchantIdentifiers" }, "version": { "$ref": "#/components/schemas/Version" }, "change_status": { "$ref": "#/components/schemas/ChangeStatus" } } }, { "$ref": "#/components/schemas/Timestamps" } ] }, "Meta": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.\n\n**Warning**: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.", "example": {} }, "BusinessProfile": { "type": "object", "description": "Business information about the merchant. This information will be visible to the merchant's customers.\n", "properties": { "name": { "type": "string", "description": "The customer-facing business name.", "minLength": 1, "maxLength": 150, "example": "Example Coffee" }, "dynamic_descriptor": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z0-9 +'_.-]+$", "description": "The descriptor is the text that your customer sees on their bank account statement.\nThe more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).\n", "example": "Example Coffee" }, "website": { "type": "string", "description": "The business's publicly available website.", "minLength": 1, "maxLength": 255, "example": "https://example.com" }, "email": { "type": "string", "description": "A publicly available email address.", "minLength": 1, "maxLength": 255, "example": "contact@example.com" }, "phone_number": { "$ref": "#/components/schemas/PhoneNumber" }, "address": { "$ref": "#/components/schemas/Address" }, "branding": { "$ref": "#/components/schemas/Branding" } } }, "Person": { "allOf": [ { "$ref": "#/components/schemas/BasePerson" } ] }, "PhoneNumber": { "type": "string", "description": "A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n", "example": "+420123456789", "maxLength": 16 }, "Branding": { "type": "object", "description": "Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.", "properties": { "footer_text": { "type": "string", "description": "Footer text rendered on receipts and other customer-facing products.\n", "minLength": 1, "maxLength": 500, "examples": [ "Thanks for shopping with us." ] }, "icon": { "type": "string", "format": "uri", "description": "An icon for the merchant. Must be square.\n" }, "logo": { "type": "string", "format": "uri", "description": "A logo for the merchant that will be used in place of the icon and without the merchant's name next to it if there's sufficient space.\n" }, "hero": { "type": "string", "format": "uri", "description": "Data-URL encoded hero image for the merchant business.\n" }, "primary_color": { "type": "string", "description": "A hex color value representing the primary branding color of this merchant (your brand color).\n", "examples": [ "#FF4B3A", "#0072C6", "#F68B20" ] }, "primary_color_fg": { "type": "string", "description": "A hex color value representing the color of the text displayed on branding color of this merchant.\n", "examples": [ "#FF4B3A", "#0072C6", "#F68B20" ] }, "secondary_color": { "type": "string", "description": "A hex color value representing the secondary branding color of this merchant (accent color used for buttons).\n", "examples": [ "#FF4B3A", "#0072C6", "#F68B20" ] }, "secondary_color_fg": { "type": "string", "description": "A hex color value representing the color of the text displayed on secondary branding color of this merchant.\n", "examples": [ "#FF4B3A", "#0072C6", "#F68B20" ] }, "background_color": { "type": "string", "description": "A hex color value representing the preferred background color of this merchant.\n", "examples": [ "#FF4B3A", "#0072C6", "#F68B20" ] } } }, "LegalType": { "externalDocs": { "description": "The country SDK documentation for legal types.", "url": "https://developer.sumup.com/tools/glossary/merchant#legal-types" }, "type": "string", "description": "The unique legal type reference as defined in the country SDK. We do not rely on IDs as used by other services. Consumers of this API are expected to use the country SDK to map to any other IDs, translation keys, or descriptions.\n", "minLength": 4, "maxLength": 64, "pattern": "^[a-z]{2}\\.[a-z_]+$", "examples": [ "de.freiberufler", "br.ltda", "gb.partnership", "bg.private_limited_company" ] }, "CompanyIdentifiers": { "type": "array", "description": "A list of country-specific company identifiers.\n", "items": { "$ref": "#/components/schemas/CompanyIdentifier" } }, "CompanyIdentifier": { "externalDocs": { "description": "Company identifier documentation", "url": "https://developer.sumup.com/tools/glossary/merchant#company-identifiers" }, "type": "object", "required": [ "ref", "value" ], "properties": { "ref": { "type": "string", "pattern": "^[a-z]{2}\\.[a-z_]+$", "description": "The unique reference for the company identifier type as defined in the country SDK.\n", "examples": [ "de.gmbh" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The company identifier value.\n", "examples": [ "HRB 123456" ] } }, "examples": [ { "ref": "de.gmbh", "value": "HRB 123456" } ] }, "Ownership": { "type": "object", "required": [ "share" ], "properties": { "share": { "description": "The percent of ownership shares held by the Person expressed in percent mille (1/100000). Only Persons with the relationship `owner` can have ownership.\n", "type": "integer", "format": "int32", "minimum": 25000, "maximum": 100000, "example": 50000 } } }, "Version": { "type": "string", "description": "The version of the resource. The version reflects a specific change submitted to the API via one of the `PATCH` endpoints.\n", "examples": [ "chng_01HS0KG3MPVEVWW85E3KNXH55J" ] }, "ChangeStatus": { "type": "string", "readOnly": true, "description": "Reflects the status of changes submitted through the `PATCH` endpoints for the Merchant or Persons. If some changes have not been applied yet, the status will be `pending`. If all changes have been applied, the status `done`.\nThe status is only returned after write operations or on read endpoints when the `version` query parameter is provided.\n" }, "BasePerson": { "externalDocs": { "description": "Person documentation", "url": "https://developer.sumup.com/tools/glossary/merchant#persons" }, "type": "object", "description": "Base schema for a Person associated with a Merchant. This can be a legal representative, business owner (ultimate beneficial owner), or an officer. A legal representative is the Person who registered the Merchant with SumUp. They should always have a `user_id`.\n", "required": [ "id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the Person. This is a [typeid](https://github.com/sumup/typeid).\n", "examples": [ "pers_2EGQ057R6C8J791RVCG5NWAEAB" ] }, "user_id": { "type": "string", "description": "A corresponding identity user ID for the Person, if they have a user account.\n", "examples": [ "ef263f37-8701-4181-9758-acddbb778ee9" ] }, "birthdate": { "type": "string", "format": "date", "description": "The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.\n", "example": "1980-01-12" }, "given_name": { "type": "string", "description": "The first name(s) of the individual.", "example": "James Herrald", "minLength": 1, "maxLength": 60 }, "family_name": { "type": "string", "description": "The last name(s) of the individual.", "example": "Bond", "minLength": 1, "maxLength": 60 }, "middle_name": { "type": "string", "description": "Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.\n", "example": "Maria Sophie", "minLength": 1, "maxLength": 60 }, "phone_number": { "$ref": "#/components/schemas/PhoneNumber", "description": "The (mobile) phone number of the individual (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n" }, "relationships": { "type": "array", "description": "A list of roles the Person has in the Merchant or towards SumUp. A Merchant must have at least one Person with the relationship `representative`.\n", "minItems": 1, "maxItems": 1, "items": { "type": "string", "description": "* `representative`: The Person is the primary contact for SumUp and has full administrative power over the merchant account.\n* `owner`: The Person is a business owner. If this value is set, the `ownership_percent` should be set as well.\n* `officer`: The Person is an officer at the company.\n", "examples": [ "representative", "owner", "officer" ] } }, "ownership": { "$ref": "#/components/schemas/Ownership", "description": "Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type `owner`.\n" }, "address": { "$ref": "#/components/schemas/Address", "description": "The address of the individual." }, "identifiers": { "$ref": "#/components/schemas/PersonalIdentifiers" }, "citizenship": { "$ref": "#/components/schemas/CountryCode", "description": "The Alpha-2 ISO code of the country where the Person is a citizen.\n" }, "nationality": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The Person's nationality. May be an [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, but legacy data may not conform to this standard.\n" }, "country_of_residence": { "type": [ "string", "null" ], "description": "An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code representing the country where the Person resides.\n", "pattern": "^[A-Z]{2}$" }, "version": { "$ref": "#/components/schemas/Version" }, "change_status": { "$ref": "#/components/schemas/ChangeStatus" } } }, "Company": { "externalDocs": { "description": "Company documentation", "url": "https://developer.sumup.com/tools/glossary/merchant#company" }, "type": "object", "description": "Information about the company or business. This is legal information that is used for verification.\n", "properties": { "name": { "type": "string", "description": "The company's legal name.", "minLength": 1, "maxLength": 150, "example": "Gin \u0026 Doughnuts Bar GmbH" }, "merchant_category_code": { "description": "The merchant category code for the account as specified by [ISO18245](https://www.iso.org/standard/33365.html). MCCs are used to classify businesses based on the goods or services they provide.\n", "type": "string", "example": "1532", "pattern": "^[0-9]{4}$" }, "legal_type": { "$ref": "#/components/schemas/LegalType", "description": "The category identifying the legal structure of the company or legal entity.\n" }, "address": { "$ref": "#/components/schemas/Address", "description": "The company's primary address." }, "trading_address": { "$ref": "#/components/schemas/Address", "description": "A trading address is where your suppliers, banks or customers send you correspondence to. Trading address can be different to the company's registered address (`address`).\n" }, "identifiers": { "$ref": "#/components/schemas/CompanyIdentifiers" }, "phone_number": { "$ref": "#/components/schemas/PhoneNumber", "description": "The company's phone number (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n" }, "website": { "description": "HTTP(S) URL of the company's website.\n", "type": "string", "minLength": 1, "maxLength": 255, "examples": [ "https://www.sumup.com" ] }, "attributes": { "$ref": "#/components/schemas/Attributes" } } }, "ClassicMerchantIdentifiers": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Classic (serial) merchant ID.", "example": 1234, "deprecated": true } } }, "Timestamps": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the resource was created. This is a string as defined in [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).\n", "readOnly": true, "examples": [ "2021-08-31T12:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the resource was last updated. This is a string as defined in [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).\n", "readOnly": true, "examples": [ "2021-08-31T12:00:00Z" ] } }, "required": [ "created_at", "updated_at" ] }, "Reader": { "title": "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": { "type": "string", "format": "uuid", "x-beta": true, "description": "Identifier of the system-managed service account associated with this reader.\nPresent only for readers that are already paired.\nThis field is currently in beta and may change." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp of when the reader was created.", "example": "2023-01-18T15:16:17Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp of when the reader was last updated.", "example": "2023-01-20T15:16:17Z" } }, "required": [ "id", "name", "status", "device", "created_at", "updated_at" ] }, "ReaderName": { "type": "string", "description": "Custom human-readable, user-defined name for easier identification of the reader.", "maxLength": 500, "example": "Frontdesk" }, "ReaderStatus": { "type": "string", "example": "paired", "enum": [ "unknown", "processing", "paired", "expired" ], "description": "The status of the reader object gives information about the current state of the reader.\n\nPossible values:\n\n- `unknown` - The reader status is unknown.\n- `processing` - The reader is created and waits for the physical device to confirm the pairing.\n- `paired` - The reader is paired with a merchant account and can be used with SumUp APIs.\n- `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated." }, "ReaderDevice": { "type": "object", "description": "Information about the underlying physical device.", "properties": { "identifier": { "type": "string", "description": "A unique identifier of the physical device (e.g. serial number).", "example": "U1DT3NA00-CN" }, "model": { "type": "string", "description": "Identifier of the model of the device.", "enum": [ "solo", "virtual-solo" ], "example": "solo" } }, "required": [ "identifier", "model" ] }, "ReaderPairingCode": { "type": "string", "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.", "example": "4WLFDSBF", "minLength": 8, "maxLength": 9 }, "UpdateReaderSettingsError": { "description": "Details of a failed reader settings request.", "properties": { "errors": { "properties": { "detail": { "description": "Error message", "type": "string" }, "type": { "description": "Error code", "type": "string" } }, "required": [ "detail" ], "type": "object" } }, "required": [ "errors" ], "title": "UpdateReaderSettingsError", "type": "object" }, "CreateReaderCheckoutUnprocessableEntity": { "description": "Unprocessable entity", "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": [ "has an invalid entry" ], "total_amount": [ "must be greater than 0" ] } } }, "InstallmentsTooLow": { "description": "Error returned when installments is not within the allowed range.", "value": { "errors": { "installments": [ "is invalid" ] } } }, "PaymentMethodNotAllowed": { "description": "Error returned when the requested payment method is not supported for the merchant (e.g. pix for non-BR merchants).", "value": { "errors": { "detail": "Payment method not allowed for this merchant.", "type": "PAYMENT_METHOD_NOT_ALLOWED" } } }, "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" } } } }, "properties": { "errors": { "additionalProperties": true, "type": "object" } }, "required": [ "errors" ], "title": "CreateReaderCheckoutUnprocessableEntity", "type": "object" }, "CreateReaderCheckoutError": { "description": "Error description", "properties": { "errors": { "properties": { "detail": { "description": "Error message", "type": "string" }, "type": { "description": "Error code", "type": "string" } }, "required": [ "type" ], "type": "object" } }, "required": [ "errors" ], "title": "CreateReaderCheckoutError", "type": "object" }, "GetReaderCheckoutResponse": { "example": { "data": { "card_type": "credit", "checkout_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", "client_transaction_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", "created_at": "2026-07-07T20:41:16.315434Z", "installments": 1, "payment_failure_reason": null, "payment_status": "pending", "payment_type": "card", "reader_firmware_version": "3.3.3.21", "reader_serial_number": "1234567890", "status": "pending", "total_amount": { "currency": "EUR", "minor_unit": 2, "value": 10000 }, "updated_at": "2026-07-07T20:42:18.117244Z", "valid_until": "2026-07-07T20:41:16.315434Z" } }, "properties": { "data": { "properties": { "card_type": { "description": "Type of the card, or null when no card type was specified.", "enum": [ "credit", "debit", null ], "type": [ "string", "null" ] }, "checkout_id": { "description": "Unique identifier for the checkout", "format": "uuid", "type": "string" }, "client_transaction_id": { "description": "Client transaction identifier associated with the checkout", "type": "string" }, "created_at": { "description": "Checkout creation timestamp", "format": "date-time", "type": "string" }, "installments": { "description": "Number of installments for the transaction. Required for some countries.", "type": [ "integer", "null" ] }, "payment_failure_reason": { "description": "Reason for the payment failure, or null when no failure reason is available.", "type": [ "string", "null" ] }, "payment_status": { "description": "Status of the payment, or null when no payment status is available.", "type": [ "string", "null" ] }, "payment_type": { "description": "Type of the payment. Required for some countries", "enum": [ "card", "pix" ], "type": "string" }, "reader_firmware_version": { "description": "Reader firmware version", "type": "string" }, "reader_serial_number": { "description": "Device serial number", "type": "string" }, "status": { "description": "Current status of the checkout", "enum": [ "pending", "successful", "failed", "cancelled" ], "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", "example": { "currency": "EUR", "minor_unit": 2, "value": 1000 }, "properties": { "currency": { "description": "Currency ISO 4217 code", "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, "minimum": 0, "type": "integer" } }, "required": [ "currency", "minor_unit", "value" ], "title": "Money", "type": "object" }, "updated_at": { "description": "Checkout last update timestamp", "format": "date-time", "type": "string" }, "valid_until": { "description": "Checkout expiration timestamp. After this time, the checkout will be automatically cancelled.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "checkout_id", "client_transaction_id", "reader_serial_number", "payment_type", "card_type", "reader_firmware_version", "installments", "payment_status", "payment_failure_reason", "valid_until", "created_at", "updated_at", "status", "total_amount" ], "type": "object" } }, "required": [ "data" ], "title": "GetReaderCheckoutResponse", "type": "object" }, "GetReaderSettingsResponse": { "description": "Menu lock settings reported by the reader, or the last saved settings when offline.\n", "example": { "data": { "menu_lock": { "enabled": true, "passcode": "1234" } } }, "properties": { "data": { "properties": { "menu_lock": { "description": "Menu lock configuration. Fields may be absent if no value is available.", "properties": { "enabled": { "description": "Whether menu lock is enabled.", "example": true, "type": "boolean" }, "passcode": { "description": "Four-digit PIN used to unlock the reader's menu.", "example": "1234", "format": "password", "pattern": "^[0-9]{4}$", "type": "string" } }, "type": "object" } }, "required": [ "menu_lock" ], "type": "object" } }, "required": [ "data" ], "title": "GetReaderSettingsResponse", "type": "object" }, "UpdateReaderSettingsUnprocessableEntity": { "description": "The reader cannot complete the settings request, or the settings are invalid.", "example": { "errors": { "detail": "Reader settings are only supported for Solo readers.", "type": "UNSUPPORTED_DEVICE_MODEL" } }, "properties": { "errors": { "additionalProperties": true, "type": "object" } }, "required": [ "errors" ], "title": "UpdateReaderSettingsUnprocessableEntity", "type": "object" }, "StatusResponse": { "description": "Status of a device", "example": { "data": { "battery_level": 10, "battery_temperature": 35, "connection_type": "Wi-Fi", "firmware_version": "3.3.3.21", "last_activity": "2025-09-25T15:20:00Z", "state": "IDLE", "status": "ONLINE" } }, "properties": { "data": { "properties": { "battery_level": { "description": "Battery level percentage", "example": 10.5, "format": "float", "maximum": 100, "minimum": 0, "type": "number" }, "battery_temperature": { "description": "Battery temperature in Celsius", "example": 35, "type": "integer" }, "connection_type": { "description": "Type of connection used by the device", "enum": [ "btle", "edge", "gprs", "lte", "umts", "usb", "Wi-Fi" ], "example": "Wi-Fi", "type": "string" }, "firmware_version": { "description": "Firmware version of the device", "example": "3.3.3.21", "type": "string" }, "last_activity": { "description": "Timestamp of the last activity from the device", "example": "2025-09-25T15:20:00Z", "format": "date-time", "type": "string" }, "state": { "description": "Latest state of the device", "enum": [ "IDLE", "SELECTING_TIP", "WAITING_FOR_CARD", "WAITING_FOR_PIN", "WAITING_FOR_SIGNATURE", "UPDATING_FIRMWARE" ], "example": "IDLE", "type": "string" }, "status": { "description": "Status of a device", "enum": [ "ONLINE", "OFFLINE" ], "example": "ONLINE", "type": "string" } }, "required": [ "status" ], "type": "object" } }, "required": [ "data" ], "title": "StatusResponse", "type": "object" }, "CreateReaderTerminateUnprocessableEntity": { "description": "Unprocessable entity", "example": { "ReaderOffline": { "description": "Error returned when the target device is not online.", "value": { "errors": { "detail": "The device is offline.", "type": "READER_OFFLINE" } } } }, "properties": { "errors": { "additionalProperties": true, "type": "object" } }, "required": [ "errors" ], "title": "CreateReaderTerminateUnprocessableEntity", "type": "object" }, "CreateReaderTerminateError": { "description": "Error description", "properties": { "errors": { "properties": { "detail": { "description": "Error message", "type": "string" }, "type": { "description": "Error code", "type": "string" } }, "required": [ "type" ], "type": "object" } }, "required": [ "errors" ], "title": "CreateReaderTerminateError", "type": "object" }, "BadRequest": { "description": "400 Bad Request", "example": { "errors": { "detail": "Bad request", "type": "INVALID_BEARER_TOKEN" } }, "properties": { "errors": { "properties": { "detail": { "description": "Fuller message giving context to error", "type": "string" }, "type": { "description": "Key indicating type of error", "enum": [ "INVALID_AFFILIATE_KEY", "APP_OUTDATED", "INVALID_BEARER_TOKEN", "INVALID_USER_AGENT", "NOT_ENOUGH_UNPAID_PAYOUTS", "DUPLICATE_HEADERS" ], "type": "string" } }, "required": [ "type" ], "type": "object" } }, "required": [ "errors" ], "title": "BadRequest", "type": "object" }, "CreateReaderCheckoutResponse": { "example": { "data": { "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "properties": { "data": { "properties": { "checkout_id": { "description": "The checkout ID is a unique identifier for the checkout.\n", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string" }, "client_transaction_id": { "description": "Unique identifier for the transaction associated with this checkout.\nUse this value to match the checkout with payment events and transaction records.\n", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string" } }, "required": [ "client_transaction_id" ], "type": "object" } }, "required": [ "data" ], "title": "CreateReaderCheckoutResponse", "type": "object" }, "UpdateReaderSettingsRequest": { "description": "Menu lock settings to update for a Solo reader.", "example": { "menu_lock": { "enabled": true, "passcode": "1234" } }, "properties": { "menu_lock": { "description": "Menu lock configuration. Provide at least one of `enabled` or `passcode`.", "minProperties": 1, "properties": { "enabled": { "description": "Whether menu lock is enabled.", "example": true, "type": "boolean" }, "passcode": { "description": "Four-digit PIN used to unlock the reader's menu.", "example": "1234", "format": "password", "pattern": "^[0-9]{4}$", "type": "string" } }, "type": "object" } }, "required": [ "menu_lock" ], "title": "UpdateReaderSettingsRequest", "type": "object" }, "UpdateReaderSettingsResponse": { "description": "Menu lock settings applied to the reader.", "example": { "data": { "menu_lock": { "enabled": true, "passcode": "1234" }, "status": "applied" } }, "properties": { "data": { "properties": { "menu_lock": { "description": "Settings included in the update. Omitted fields are not returned.", "properties": { "enabled": { "description": "Whether menu lock is enabled.", "example": true, "type": "boolean" }, "passcode": { "description": "Four-digit PIN used to unlock the reader's menu.", "example": "1234", "format": "password", "pattern": "^[0-9]{4}$", "type": "string" } }, "type": "object" }, "status": { "description": "Indicates that the reader applied the settings update.", "enum": [ "applied" ], "example": "applied", "type": "string" } }, "required": [ "status", "menu_lock" ], "type": "object" } }, "required": [ "data" ], "title": "UpdateReaderSettingsResponse", "type": "object" }, "Unauthorized": { "description": "401 Unauthorized", "example": { "errors": { "detail": "Unauthorized" } }, "properties": { "errors": { "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.", "enum": [ "INVALID_ACCESS_TOKEN", "INVALID_PASSWORD" ], "type": "string" } }, "required": [ "detail" ], "type": "object" } }, "required": [ "errors" ], "title": "Unauthorized", "type": "object" }, "CreateReaderCheckoutRequest": { "description": "Payment details for a Reader Checkout.\n", "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": { "custom_key_1": "custom_value_1", "custom_key_2": "custom_value_2" } }, "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 } }, "properties": { "aade": { "description": "Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol.\nWhen such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider.\n", "properties": { "provider_id": { "description": "The identifier of the AADE signature provider.", "example": "123", "type": "string" }, "signature": { "description": "The base64 encoded signature of the transaction data.", "example": "QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5", "type": "string" }, "signature_data": { "description": "The string containing the signed transaction data.", "example": "B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039", "type": "string" } }, "required": [ "provider_id", "signature", "signature_data" ], "type": "object" }, "affiliate": { "description": "Optional affiliate metadata associated with the checkout's payment.\nProvide both `app_id` and `key` when including this object.\n", "properties": { "app_id": { "description": "Integrator application identifier from the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\nRequired when the affiliate object is provided.\n", "example": "com.example.app", "type": "string" }, "foreign_transaction_id": { "description": "Integrator-owned transaction reference. Optional.\nCan be used to retrieve the transaction via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f", "type": "string" }, "key": { "description": "Affiliate key generated in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\nRequired when the affiliate object is provided.\n", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" }, "tags": { "additionalProperties": true, "description": "Optional key-value metadata associated with the transaction.\n", "example": { "custom_key_1": "custom_value_1", "custom_key_2": "custom_value_2" }, "type": "object" } }, "required": [ "app_id", "key" ], "title": "Affiliate", "type": [ "object", "null" ] }, "card_type": { "description": "The card type of the card used for the transaction.\nIt is required only for some countries (e.g: Brazil).\n", "enum": [ "credit", "debit" ], "example": "credit", "type": "string" }, "description": { "description": "Description of the checkout to be shown in the Merchant Sales", "type": "string" }, "installments": { "description": "Number of installments for the transaction.\nIt may vary according to the merchant country.\nFor example, in Brazil, the maximum number of installments is 12.\n\nOmit if the merchant country does not support installments.\nOtherwise, the checkout will be rejected.\n", "example": 1, "minimum": 1, "type": [ "integer", "null" ] }, "payment_type": { "default": "card", "description": "The payment method type for the transaction. Defaults to `card`.\n\nUse `pix` to initiate a Pix QR-code payment flow on the device.\nPix is only supported for Brazilian merchants; other merchants will receive a 422 error.\n", "enum": [ "card", "pix" ], "example": "card", "type": "string" }, "return_url": { "description": "Webhook URL to which the payment result will be sent.\nIt must be a HTTPS url.\n", "example": "https://www.example.com", "format": "uri", "type": "string" }, "tip_rates": { "description": "Exactly three distinct tipping rates to be displayed to the cardholder.\nEach rate is a fraction between 0.01 and 1.00 in increments of 0.01.\nThe rates are sorted in ascending order by the server.\n", "items": { "format": "float", "maximum": 1, "minimum": 0.01, "multipleOf": 0.01, "type": "number" }, "maxItems": 3, "minItems": 3, "type": "array", "uniqueItems": true }, "tip_timeout": { "default": 30, "description": "Time in seconds the cardholder has to select a tip rate.\nIf not provided, the default value is 30 seconds.\n\nIt can only be set if `tip_rates` is provided.\n\n**Note**: If the target device is a Solo, it must be in version 3.3.38.0 or higher.\n", "example": 30, "maximum": 120, "minimum": 30, "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", "example": { "currency": "EUR", "minor_unit": 2, "value": 1000 }, "properties": { "currency": { "description": "Currency ISO 4217 code", "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, "minimum": 0, "type": "integer" } }, "required": [ "currency", "minor_unit", "value" ], "title": "Money", "type": "object" } }, "required": [ "total_amount" ], "title": "CreateReaderCheckoutRequest", "type": "object" }, "ReaderCheckoutStatusChange": { "description": "The callback payload containing the status change of the Reader Checkout.", "properties": { "event_type": { "description": "Type of event.", "example": "solo.transaction.updated", "type": "string" }, "id": { "description": "Unique identifier for the event.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "format": "uuid", "type": "string" }, "payload": { "description": "The event payload.", "properties": { "client_transaction_id": { "description": "The unique client transaction id. It is the same returned by the Checkout.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "format": "uuid", "type": "string" }, "merchant_code": { "description": "The merchant code associated with the transaction.", "example": "M1234567", "type": "string" }, "status": { "description": "The current status of the transaction.", "enum": [ "successful", "failed" ], "example": "successful", "type": "string" }, "transaction_id": { "deprecated": true, "description": "The transaction id. Deprecated: use `client_transaction_id` instead.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "format": "uuid", "type": "string" } }, "required": [ "client_transaction_id", "merchant_code", "status" ], "type": "object" }, "timestamp": { "description": "Timestamp of the event.", "example": "2023-10-05T14:48:00Z", "format": "date-time", "type": "string" } }, "required": [ "id", "event_type", "payload", "timestamp" ], "title": "ReaderCheckoutStatusChange", "type": "object" }, "NotFound": { "description": "404 Not Found", "example": { "errors": { "detail": "Not Found" } }, "properties": { "errors": { "properties": { "detail": { "description": "Fuller message giving context to error", "type": "string" } }, "required": [ "detail" ], "type": "object" } }, "required": [ "errors" ], "title": "NotFound", "type": "object" }, "Token": { "type": "object", "description": "A short-lived credential for the requested merchant account and actions. Pass access_token to a SumUp SDK that supports merchant tokens.", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "Secret token to pass to the SDK. Treat this value as an opaque string; do not parse it or depend on its format.", "example": "MERCHANT_TOKEN" }, "token_type": { "type": "string", "description": "Authentication scheme used by the token. Always Bearer.", "enum": [ "Bearer" ], "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Remaining lifetime of the token in seconds when the response is created. Tokens expire 15 minutes after creation. Request a new token when needed.", "minimum": 0, "example": 899 } } } }, "requestBodies": { "CheckoutCreate": { "required": true, "description": "Details for creating a checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCreateRequest" }, "examples": { "Checkout": { "description": "Standard request body for creating a checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "valid_until": "2030-12-31T23:59:59Z", "redirect_url": "https://sumup.com" } }, "Checkout3DS": { "description": "Create a 3DS checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com/", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase" } }, "CheckoutAPM": { "description": "Create an Alternative Payment Method checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "redirect_url": "https://mysite.com/completed_purchase" } }, "HostedCheckout": { "description": "Create a checkout with a SumUp-hosted payment page", "x-beta": true, "value": { "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d", "amount": 12, "currency": "EUR", "merchant_code": "MCXXXXXX", "description": "A sample checkout", "hosted_checkout": { "enabled": true } } } } } } }, "CheckoutUpdate": { "required": true, "description": "Details for updating a checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutUpdateRequest" }, "example": { "amount": 12.5, "currency": "EUR", "description": "Updated purchase", "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670" } } } }, "CustomerCreate": { "required": true, "description": "Details of the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "CustomerUpdate": { "required": true, "description": "Customer fields to update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } } } } } }, "Refund": { "description": "Optional amount for partial refunds.", "content": { "application/json": { "example": { "amount": 5 }, "schema": { "type": "object", "description": "Optional amount for partial refunds of transactions.", "properties": { "amount": { "type": "number", "format": "float", "description": "Amount to refund in major units of the transaction's currency, for example `5` 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": 5 } } } } } } }, "responses": { "Checkout": { "description": "Returns the created checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "examples": { "Checkout": { "description": "Standard response body for a successfully created checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "merchant_country": "DE", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MH4H92C7" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ] } }, "Checkout3DS": { "description": "Response body for a successfully created 3DS checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ] } }, "CheckoutAPM": { "description": "Response body for APMs, including Blik, iDeal, ...", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2021-06-29T11:08:36.000+00:00", "merchant_name": "My company", "merchant_country": "DE", "redirect_url": "https://sumup.com", "purpose": "CHECKOUT", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345" } ] } }, "HostedCheckout": { "description": "Response body for a checkout with a SumUp-hosted payment page", "value": { "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d", "amount": 12, "currency": "EUR", "merchant_code": "MCXXXXXX", "merchant_country": "DE", "merchant_name": "Sample Shop", "description": "A sample checkout", "id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91", "status": "PENDING", "date": "2000-01-01T12:49:24.899+00:00", "purpose": "CHECKOUT", "hosted_checkout": { "enabled": true }, "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676", "transactions": [] } } } } } }, "CheckoutUpdate": { "description": "Returns the updated checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "example": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 12.5, "currency": "EUR", "merchant_code": "MH4H92C7", "merchant_country": "DE", "description": "Updated purchase", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "transactions": [] } } } }, "CheckoutList": { "description": "Returns a list of checkout resources.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSuccess" } }, "example": [ { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00" } ] } } }, "CheckoutRetrieve": { "description": "Returns the requested checkout resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSuccess" }, "example": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } } } }, "CheckoutProcessAccepted": { "description": "Returns the next required action for asynchronous checkout processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccepted" } } } }, "Customer": { "description": "Returns the customer resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "PaymentInstrumentList": { "description": "Returns the list of saved payment instruments for the customer.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstrumentResponse" } } } } }, "Transaction": { "description": "Returns the requested transaction resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionFull" }, "example": { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201" } } } }, "NoBodyResponse": { "description": "Returns an empty response body when the operation succeeds." }, "ErrorNotAuthorized": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "Problem_Details": { "description": "Unauthorized response returned by API gateway.", "value": { "detail": "Unauthorized.", "status": 401, "title": "Unauthorized", "trace_id": "3c77294349d3b5647ea2d990f0d8f017", "type": "https://developer.sumup.com/problem/unauthorized" } } } } } }, "ErrorForbidden": { "description": "The request is authenticated but not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "ErrorNotFound": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "ErrorConflict": { "description": "The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Checkout_Processed": { "description": "The identified checkout resource is already processed.", "value": { "error_code": "CHECKOUT_PROCESSED", "message": "Checkout is already processed" } } } } } }, "BadRequest": { "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." } } } }, "Unauthorized": { "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." } } } }, "NotFound": { "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." } } } }, "ListMemberships": { "description": "Returns a list of Membership objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_count", "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "total_count": { "type": "integer", "example": 3 } } } } } }, "ListMembers": { "description": "Returns a list of Member objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "total_count": { "type": "integer", "example": 3 } } } } } }, "ListRoles": { "description": "Returns a list of Role objects.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } } } } }, "parameters": { "CheckoutReference": { "name": "checkout_reference", "in": "query", "description": "Filters checkouts by the merchant-defined `checkout_reference` supplied when creating the checkout. This is separate from the SumUp-generated checkout `id`.", "required": false, "schema": { "type": "string", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" } }, "CheckoutID": { "name": "checkout_id", "in": "path", "required": true, "description": "SumUp-generated `id` returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.", "schema": { "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" } }, "CustomerID": { "name": "customer_id", "in": "path", "required": true, "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" } }, "Token": { "name": "token", "in": "path", "required": true, "description": "Unique token identifying the card saved as a payment instrument resource.", "schema": { "type": "string", "example": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3" } }, "TransactionCode": { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string", "example": "TEENSK4W2K" } }, "OrderFilter": { "name": "order", "in": "query", "description": "Sort direction for the transaction history. Use `ascending` or `descending`; the default is `ascending`.", "schema": { "type": "string", "enum": [ "ascending", "descending" ], "default": "ascending" } }, "LimitFilter": { "name": "limit", "in": "query", "description": "Maximum number of transactions per page. Must be a positive integer. Defaults to `10` when omitted; a page can contain fewer results.", "schema": { "type": "integer", "example": 10 } }, "UsersFilter": { "name": "users[]", "in": "query", "description": "Filters transactions by user email. For multiple values, repeat the query parameter, for example `users[]=first@example.com\u0026users[]=second@example.com`.", "required": false, "example": [ "merchant@example.com" ], "schema": { "type": "array", "example": [ "merchant@example.com" ], "items": { "type": "string", "format": "email" } } }, "StatusesFilter": { "name": "statuses[]", "in": "query", "description": "Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example `statuses[]=SUCCESSFUL\u0026statuses[]=REFUNDED`.", "required": false, "schema": { "type": "array", "example": [ "SUCCESSFUL", "REFUNDED" ], "items": { "type": "string", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "REFUNDED", "CHARGE_BACK" ] } } }, "PaymentTypesFilter": { "name": "payment_types[]", "in": "query", "description": "Filters the returned results by the specified list of payment types used for the transactions.", "required": false, "schema": { "type": "array", "example": [ "ECOM", "POS" ], "items": { "$ref": "#/components/schemas/PaymentType" } } }, "EntryModesFilter": { "name": "entry_modes[]", "in": "query", "description": "Filters the returned results by the specified list of entry modes.", "required": false, "schema": { "type": "array", "example": [ "CUSTOMER_ENTRY", "CHIP" ], "items": { "$ref": "#/components/schemas/EntryMode" } } }, "TypesFilter": { "name": "types[]", "in": "query", "description": "Filters the returned results by the specified list of transaction types.", "required": false, "schema": { "type": "array", "example": [ "PAYMENT", "REFUND" ], "items": { "type": "string", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ] } } }, "ChangesSinceFilter": { "name": "changes_since", "in": "query", "description": "Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2019-08-28T09:00:00Z" } }, "NewestTimeFilter": { "name": "newest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2019-08-29T09:00:00Z" } }, "NewestRefFilter": { "name": "newest_ref", "in": "query", "description": "Pagination reference that returns results before the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over `newest_time` when both are provided.", "required": false, "schema": { "type": "string", "example": "090df9bf-93b7-40f1-8181-fbdb236568a1" } }, "TransactionID": { "name": "id", "in": "query", "description": "Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource).", "required": false, "schema": { "type": "string", "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } } }, "securitySchemes": { "apiKey": { "description": "Authenticate requests with an API key created in the [Dashboard](https://me.sumup.com/settings/api-keys). Send the key in the HTTP `Authorization` header as `Bearer YOUR_API_KEY`. See the [API key guide](https://developer.sumup.com/tools/authorization/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.\n\nRegister an application in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications) to obtain a client ID and client secret. Use the authorization code flow to request a merchant's consent, then send the issued access token in the HTTP `Authorization` header as `Bearer ACCESS_TOKEN`. Request the scopes needed for the endpoints your integration calls.\n\nTo 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.", "checkouts.read": "View checkouts.", "checkouts.write": "Create, process, and deactivate checkouts.", "transactions.history": "View transactions and transaction history.", "transactions.read": "View transactions and transaction history.", "refunds.write": "Refund transactions.", "receipts.read": "View receipts.", "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.", "customers.read": "View customers and their payment instruments.", "customers.write": "Create and manage customers and their payment instruments.", "user.payout-settings": "View and manage your payout settings.", "payouts.read": "View payouts.", "user.subaccounts": "View and manage the user profile details of your employees." } } } } }, "examples": { "CreatedReader": { "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-09T14:50:20.214Z", "updated_at": "2023-05-09T14:52:58.714Z" } } }, "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." } } }, "webhooks": { "checkouts.created": { "post": { "operationId": "CheckoutCreatedWebhook", "tags": [ "Checkouts" ], "summary": "Checkout created", "description": "Sent once when a checkout is first observed in the checkout snapshot stream, even if it is already paid, failed, or expired. The event timestamp is the original checkout creation time.", "x-object": { "$ref": "#/components/schemas/Checkout" }, "x-object-type": "checkout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "created": { "value": { "id": "event_01ARZ3NDEKTSV4RRFFQ69G5FAV", "type": "checkouts.created", "created_at": "2026-10-15T12:00:00Z", "object": { "id": "e552de3b-1777-4c91-bdb8-756967678572", "type": "checkout", "url": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "checkouts.failed": { "post": { "operationId": "CheckoutFailedWebhook", "tags": [ "Checkouts" ], "summary": "Checkout failed", "description": "Sent once when a checkout is first observed with status FAILED. A failed checkout can subsequently be retried and paid. Later FAILED snapshots do not emit another failed event.", "x-object": { "$ref": "#/components/schemas/Checkout" }, "x-object-type": "checkout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "failed": { "value": { "id": "event_01ARZ3NDEKTSV4RRFFQ69G5FAV", "type": "checkouts.failed", "created_at": "2026-10-15T12:00:00Z", "object": { "id": "e552de3b-1777-4c91-bdb8-756967678572", "type": "checkout", "url": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "checkouts.expired": { "post": { "operationId": "CheckoutExpiredWebhook", "tags": [ "Checkouts" ], "summary": "Checkout expired", "description": "Sent once when a checkout is first observed with status EXPIRED. Expiry or deactivation without an upstream snapshot cannot produce this event. Later EXPIRED snapshots do not emit another expired event.", "x-object": { "$ref": "#/components/schemas/Checkout" }, "x-object-type": "checkout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "expired": { "value": { "id": "event_01ARZ3NDEKTSV4RRFFQ69G5FAV", "type": "checkouts.expired", "created_at": "2026-10-15T12:00:00Z", "object": { "id": "e552de3b-1777-4c91-bdb8-756967678572", "type": "checkout", "url": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "checkouts.updated": { "post": { "operationId": "CheckoutUpdatedWebhook", "tags": [ "Checkouts" ], "summary": "Checkout updated", "description": "Sent when a checkout snapshot is published, including creation and payment status updates. Fetch the checkout to inspect its current status. This is not a guarantee that every checkout mutation produces a notification.", "x-object": { "$ref": "#/components/schemas/Checkout" }, "x-object-type": "checkout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "updated": { "value": { "id": "event_01ARZ3NDEKTSV4RRFFQ69G5FAV", "type": "checkouts.updated", "created_at": "2026-10-15T12:00:00Z", "object": { "id": "e552de3b-1777-4c91-bdb8-756967678572", "type": "checkout", "url": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "checkouts.paid": { "post": { "operationId": "CheckoutPaidWebhook", "tags": [ "Checkouts" ], "summary": "Checkout paid", "description": "Sent once when a checkout is first observed with status PAID. Later PAID snapshots do not emit another paid event. The timestamp is the snapshot update time, not necessarily the payment completion time.", "x-object": { "$ref": "#/components/schemas/Checkout" }, "x-object-type": "checkout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "paid": { "value": { "id": "event_01ARZ3NDEKTSV4RRFFQ69G5FAV", "type": "checkouts.paid", "created_at": "2026-10-15T12:00:00Z", "object": { "id": "e552de3b-1777-4c91-bdb8-756967678572", "type": "checkout", "url": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "readers.created": { "post": { "operationId": "ReaderCreatedWebhook", "tags": [ "Readers" ], "summary": "Reader created", "description": "Sent when a reader is paired to a merchant account and becomes available through the Readers API.", "x-object": { "$ref": "#/components/schemas/Reader" }, "x-object-type": "reader", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "created": { "summary": "A reader created webhook event.", "value": { "id": "evt_reader_123", "type": "readers.created", "created_at": "2023-05-09T14:52:58.714Z", "object": { "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "type": "reader", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/readers/rdr_3MSAFM23CK82VSTT4BN6RWSQ65" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "readers.deleted": { "post": { "operationId": "ReaderDeletedWebhook", "tags": [ "Readers" ], "summary": "Reader deleted", "description": "Sent when a reader is unpaired from a merchant account and is no longer available through the Readers API.", "x-object": { "$ref": "#/components/schemas/Reader" }, "x-object-type": "reader", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "deleted": { "summary": "A reader deleted webhook event.", "value": { "id": "evt_reader_456", "type": "readers.deleted", "created_at": "2023-05-10T09:21:33.004Z", "object": { "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "type": "reader", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/readers/rdr_3MSAFM23CK82VSTT4BN6RWSQ65" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "members.created": { "post": { "operationId": "MemberCreatedWebhook", "tags": [ "Members" ], "summary": "Member created", "description": "Sent when a member is created, invited, or accepts an invitation for a merchant account.", "x-object": { "$ref": "#/components/schemas/Member" }, "x-object-type": "member", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "created": { "summary": "A member created webhook event.", "value": { "id": "evt_membership_123", "type": "members.created", "created_at": "2026-05-14T08:30:00Z", "object": { "id": "mem_123", "type": "member", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/members/mem_123" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "members.updated": { "post": { "operationId": "MemberUpdatedWebhook", "tags": [ "Members" ], "summary": "Member updated", "description": "Sent when a member is updated, disabled, rejected, or expires for a merchant account.", "x-object": { "$ref": "#/components/schemas/Member" }, "x-object-type": "member", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "updated": { "summary": "A member updated webhook event.", "value": { "id": "evt_membership_456", "type": "members.updated", "created_at": "2026-05-14T09:15:00Z", "object": { "id": "mem_123", "type": "member", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/members/mem_123" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "members.deleted": { "post": { "operationId": "MemberDeletedWebhook", "tags": [ "Members" ], "summary": "Member deleted", "description": "Sent when a member is deleted from a merchant account.", "x-object": { "$ref": "#/components/schemas/Member" }, "x-object-type": "member", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "deleted": { "summary": "A member deleted webhook event.", "value": { "id": "evt_membership_789", "type": "members.deleted", "created_at": "2026-05-14T10:45:00Z", "object": { "id": "mem_123", "type": "member", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/members/mem_123" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "roles.created": { "post": { "operationId": "RoleCreatedWebhook", "tags": [ "Roles" ], "summary": "Role created", "description": "Sent when a role is created for a merchant account.", "x-object": { "$ref": "#/components/schemas/Role" }, "x-object-type": "role", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "created": { "summary": "A role created webhook event.", "value": { "id": "evt_role_123", "type": "roles.created", "created_at": "2026-05-14T08:30:00Z", "object": { "id": "rol_123", "type": "role", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/roles/rol_123" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "roles.updated": { "post": { "operationId": "RoleUpdatedWebhook", "tags": [ "Roles" ], "summary": "Role updated", "description": "Sent when a role is updated for a merchant account.", "x-object": { "$ref": "#/components/schemas/Role" }, "x-object-type": "role", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "updated": { "summary": "A role updated webhook event.", "value": { "id": "evt_role_123", "type": "roles.updated", "created_at": "2026-05-14T08:30:00Z", "object": { "id": "rol_123", "type": "role", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/roles/rol_123" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } }, "roles.deleted": { "post": { "operationId": "RoleDeletedWebhook", "tags": [ "Roles" ], "summary": "Role deleted", "description": "Sent when a role is deleted for a merchant account.", "x-object": { "$ref": "#/components/schemas/Role" }, "x-object-type": "role", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "deleted": { "summary": "A role deleted webhook event.", "value": { "id": "evt_role_123", "type": "roles.deleted", "created_at": "2026-05-14T08:30:00Z", "object": { "id": "rol_123", "type": "role", "url": "https://api.sumup.com/v0.1/merchants/MC0DE/roles/rol_123" } } } } } } }, "responses": { "2XX": { "description": "Return any 2xx response to acknowledge successful delivery." } } } } } }