openapi: 3.0.3 info: title: SumUp REST API version: 1.0.0 description: |- SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status). You can experiment and work on your integration in a sandbox that doesn't affect your regular data and doesn't process real transactions. To create a sandbox merchant account visit the [dashboard](https://me.sumup.com/settings/developer). To use the sandbox when interacting with SumUp APIs [create an API](https://me.sumup.com/settings/api-keys) key and use it for [authentication](https://developer.sumup.com/api/authentication). license: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" servers: - url: https://api.sumup.com description: Production server tags: - name: 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. Use this tag to: - create a checkout before collecting or confirming payment details - process the checkout with a card, saved card, wallet, or supported alternative payment method - retrieve or list checkouts to inspect their current state and associated payment attempts - deactivate a checkout that should no longer be used Typical workflow: - create a checkout with the order amount, currency, and merchant information - process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts) - retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record Checkouts 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: |- Allow your regular customers to save their information with the Customers model. This will prevent re-entering payment instrument information for recurring payments on your platform. Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers. 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. In 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: - `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant - `REFUND`: money returned to the payer - `CHARGE_BACK`: money reversed after the original payment - `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback From an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to: - list transactions for reporting, reconciliation, and customer support workflows - retrieve a single transaction when you need the latest payment details - inspect `simple_status` for the current merchant-facing outcome of the payment - inspect `events` or `transaction_events` when you need refund, payout, or chargeback history Typical workflow: - create and process payments through the Checkouts endpoints - use the Transactions endpoints to read the resulting payment records - 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. You 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: The Receipts model obtains receipt-like details for specific transactions. 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" paths: /v0.1/merchants/{merchant_code}/payment-methods: get: operationId: GetPaymentMethods summary: Get available payment methods description: |- Get payment methods available for the given merchant to use with a checkout. 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: |- The amount for which the payment methods should be eligible, in major units. schema: type: number example: 9.99 - in: query name: currency required: false description: The currency for which the payment methods should be eligible. 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 new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout. For 3DS checkouts, add the `redirect_url` parameter to your request body schema. To use the [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the `hosted_checkout.enabled` to `true`. Follow by processing a checkout to charge the provided payment instrument. 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: '2020-02-29T10:56:56+00:00' 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: '2020-02-29T10:56:56+00:00' 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: '2020-02-29T10:56:56+00:00' 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 the list of checkout resources by the unique reference of the checkout. 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: Unique identifier of the checkout resource. schema: type: string example: 4e425463-3e1b-431d-83fa-1e51c2925e99 get: operationId: GetCheckout summary: Retrieve a checkout description: |- Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively. 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 an identified checkout resource. 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: '2020-02-29T10:56:56+00:00' 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: '2020-02-29T10:56:56+00:00' 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] When 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. ::: Processing 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. Follow this request with `Retrieve a checkout` to confirm its status. 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: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' 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: PENDING 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: Successfully processed checkout with Boleto 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: Successfully processed checkout with iDeal 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&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 mechanism: - browser CheckoutSuccessBancontact: description: Successfully processed checkout with Bancontact 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&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=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-6152f8ee267j amount: 2 currency: EUR merchant_code: MH4H92C7 description: Deletion example purpose: CHECKOUT status: EXPIRED date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' 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. Use this endpoint after the customer selects Apple Pay and before calling `ApplePaySession.completeMerchantValidation(...)` in the browser. SumUp validates the merchant session request and returns the Apple Pay session object that your frontend should pass to Apple's JavaScript API. tags: - Checkouts parameters: - name: checkout_id in: path required: true description: Unique identifier of the checkout resource. schema: type: string example: 4e425463-3e1b-431d-83fa-1e51c2925e99 x-codegen: method_name: create_apple_pay_session x-scopes: [] requestBody: description: The data needed to create an apple pay session for a checkout. content: application/json: schema: type: object required: - context - target properties: context: type: string description: the context to create this apple pay session. format: hostname example: example.com target: type: string description: The target url to create this apple pay session. format: uri example: https://apple-pay-gateway-cert.apple.com/paymentservices/startSession responses: '200': description: | Successful request. Returns the Apple Pay merchant session object that should be forwarded to the Apple Pay JS SDK to complete merchant validation and continue the payment flow. 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: '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 new saved customer resource which you can later manipulate and save payment instruments to. 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' - 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 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: Unique identifier of the saved customer resource. schema: type: string example: 831ff8d4cd5958ab5670 get: operationId: GetCustomer summary: Retrieve a customer description: |- Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation. 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. The 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: Unique identifier of the saved customer resource. 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: Unique identifier of the saved customer resource. 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 an identified transaction either in full or partially. 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 be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction. example: 5 responses: '201': description: The transaction was refunded in full or partially based on the request. content: application/json: schema: type: object 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: - `id` - `transaction_code` - `foreign_transaction_id` - `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 detailed history of all transactions associated with the merchant profile. 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: Specifies the order in which the returned results are displayed. schema: type: string enum: - ascending - descending default: ascending - name: limit in: query description: |- Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results. schema: type: integer example: 10 - name: users[] in: query description: Filters the returned results by user email. required: false example: - merchant@example.com schema: type: array example: - merchant@example.com items: type: string format: email - name: statuses[] in: query description: |- Filters the returned results by the specified list of final statuses of the transactions. 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: |- Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request). 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: |- Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *greater* than the specified value. This parameters supersedes the `oldest_time` parameter (if both are provided in the request). 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. The response can include: - regular payouts (`type = PAYOUT`) - deduction records for refunds, chargebacks, direct debit returns, or balance adjustments Results 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 123456789,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 receipt specific data for a transaction. 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. Use `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.parent.id in: query description: >- Filter memberships by the parent of the resource the membership is in. When filtering by parent both `resource.parent.id` and `resource.parent.type` must be present. Pass explicit null to filter for resources without a parent. schema: type: string nullable: true - name: resource.parent.type in: query description: >- Filter memberships by the parent of the resource the membership is in. When filtering by parent both `resource.parent.id` and `resource.parent.type` must be present. Pass explicit null to filter for resources without a parent. schema: nullable: true allOf: - $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: user.type in: query description: Filter the returned members by user type. Repeat this parameter to include multiple user types. schema: type: array items: $ref: '#/components/schemas/UserType' style: form explode: true - 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: Create a merchant member. 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. 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] # Not supported in 3.0, can be enabled once we move to 3.1 # examples: # "Invite a user": # email: karl.berg@example.com # roles: [role_employee] # "Create a managed user": # email: employee123@mycompany.com # roles: [role_employee] # nickname: "Employee 123" # is_managed: true # metadata: # external_id: ced70a99-89d1-42c4-81e7-63f81cad805d 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: Update the merchant member. 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 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. 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: Update a custom role. 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. 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. Timestamps are accepted in the following formats: - 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). - 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:01+00:00 - 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: Update a Reader. 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. If the server returns any other code, the callback will be retried up to 5 times with exponential backoff. description: | Creates a Checkout for a Reader. This process is asynchronous and the actual transaction may take some time to be started on the device. There are some caveats when using this endpoint: * The target device must be online, otherwise checkout won't be accepted * After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected. **Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher. 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: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' application/problem+json: example: detail: Bad Request status: 400 title: Bad Request type: https://developer.sumup.com/problem/bad-request schema: $ref: '#/components/schemas/Problem' 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: example: detail: Validation failed status: 422 title: Unprocessable Entity 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. This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state). Supported States * `IDLE` – Reader ready for next transaction * `SELECTING_TIP` – Waiting for tip input * `WAITING_FOR_CARD` – Awaiting card insert/tap * `WAITING_FOR_PIN` – Waiting for PIN entry * `WAITING_FOR_SIGNATURE` – Waiting for customer signature * `UPDATING_FIRMWARE` – Firmware update in progress Device Status * `ONLINE` – Device connected and operational * `OFFLINE` – Device disconnected (last state persisted) **Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher. 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}/terminate: post: callbacks: {} description: | Terminate a Reader Checkout stops the current transaction on the target device. This process is asynchronous and the actual termination may take some time to be performed on the device. There are some caveats when using this endpoint: * The target device must be online, otherwise terminate won't be accepted * The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc. * There is no confirmation of the termination. If a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL. **Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher. 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. 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 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' 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: 90 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 used by SumUp to notify your platform about processing updates for the checkout. 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 example: '2020-02-29T10:56:56+00:00' 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. nullable: true 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. It should be unique enough for you to identify the payment attempt in your own 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 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 used by SumUp to notify your platform about processing updates for the checkout. 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 example: '2020-02-29T10:56:56+00:00' 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. nullable: true 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: 90 description: |- Updated merchant-defined reference for the checkout. example: f00a8f74-b05d-4605-bd73-2a901bae5802 valid_until: type: string example: '2020-02-29T10:56:56+00:00' format: date-time description: |- Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. nullable: true 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: |- Saved-card token to use instead of raw card details when processing with a previously stored payment instrument. 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&VAA=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 customer details. required: - customer_id properties: customer_id: type: string description: Unique identifier of the customer. example: 831ff8d4cd5958ab5670 personal_details: $ref: '#/components/schemas/PersonalDetails' 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. Additional properties specific to the problem type may be present. type: object properties: type: description: A URI reference that identifies the problem type. type: string format: uri example: 'https://developer.sumup.com/problem/not-found' title: description: 'A short, human-readable summary of the problem type.' type: string example: Requested resource couldn't be found. status: description: The HTTP status code generated by the origin server for this occurrence of the problem. type: integer example: 404 detail: description: A human-readable explanation specific to this occurrence of the problem. type: string example: The requested resource doesn't exist or does not belong to you. instance: description: A URI reference that identifies the specific occurrence of the problem. type: string format: uri 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. A record can represent either: - an actual payout sent to the merchant (`type = PAYOUT`) - 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: Relation. example: next href: type: string description: Location. example: limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=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: Unique token identifying the saved payment card for a customer. 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. 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.0 vat_rate: type: number format: decimal description: VAT rate applied to the product price. example: 0.19 single_vat_amount: type: number format: decimal description: VAT amount for a single product. example: 19.0 price_with_vat: type: number format: decimal description: Product price including VAT. example: 119.0 vat_amount: type: number format: decimal description: Total VAT amount for the product quantity. example: 19.0 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.0 total_with_vat: type: number format: decimal description: Total product price including VAT. example: 119.0 Receipt: type: object title: Receipt description: Receipt details for a transaction. 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. 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 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: |- Transaction code returned by the acquirer/processing entity after processing the transaction. example: TEENSK4W2K amount: type: number format: float description: Total amount of the transaction. 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: Amount of the applicable VAT (out of the total transaction amount). example: 6 tip_amount: type: number format: float description: Amount of the tip (out of the total transaction amount). 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 refunded amount. example: 0 PaymentType: title: Payment Type type: string description: Payment type used for the transaction. enum: - CASH - POS - ECOM - RECURRING - BITCOIN - BALANCE - MOTO - BOLETO - DIRECT_DEBIT - APM - UNKNOWN example: ECOM EntryMode: title: Entry Mode type: string description: Entry mode of the payment details. 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 - CONECS - CUP - DINERS - DISCOVER - EFTPOS - ELO - ELV - GIROCARD - HIPERCARD - INTERAC - JCB - MAESTRO - MASTERCARD - PLUXEE - 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: Transaction SumUp total fee amount. example: 8.0 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. - `PENDING`: The payment has been initiated and is still being processed. A final outcome is not available yet. - `SUCCESSFUL`: The payment was completed successfully. - `PAID_OUT`: The payment was completed successfully and the funds have already been included in a payout to the merchant. - `FAILED`: The payment did not complete successfully. - `CANCELLED`: The payment was cancelled or reversed and is no longer payable or payable to the merchant. - `CANCEL_FAILED`: An attempt to cancel or reverse the payment was not completed successfully. - `REFUNDED`: The payment was refunded in full or in part. - `REFUND_FAILED`: An attempt to refund the payment was not completed successfully. - `CHARGEBACK`: The payment was subject to a chargeback. - `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: - BGN - 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. - `PENDING`: The transaction has been created but its final outcome is not known yet. - `SUCCESSFUL`: The transaction completed successfully. - `CANCELLED`: The transaction was cancelled or otherwise reversed before completion. - `FAILED`: The transaction attempt did not complete successfully. - `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: Type of the transaction event. enum: - PAYOUT - CHARGE_BACK - REFUND - PAYOUT_DEDUCTION example: REFUND TransactionEventStatus: title: Transaction Event Status type: string description: |- Status of the transaction event. Not every value is used for every event type. - `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. - `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. - `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. - `PAID_OUT`: The payout event has been completed and the funds were included in a merchant payout. - `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. - `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`. - `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: Unique identifier of the transaction event. 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.0 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: 0 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: 0 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: $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: Optional tip amount in minor units, added on top of total_amount. example: 100 type: integer total_amount: $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. Possible values are: * `merchant` - merchant account(s) * `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 UserType: type: string description: Type of the user account. enum: - user - managed_user - service_account - system_account example: user 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. type: object example: {} additionalProperties: true 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`. Whether 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. maxLength: 10 example: "10999" country: $ref: '#/components/schemas/CountryCode' city: type: string description: > The city of the address. maxLength: 60 example: Berlin province: type: string description: > The province where the address is located. This may not be relevant in some countries. maxLength: 60 example: Berlin region: type: string description: > The region where the address is located. This may not be relevant in some countries. 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. 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. 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. 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. maxLength: 60 example: California neighborhood: type: string description: > Locality level of the address. Used in countries such as Brazil or Chile. 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. 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. 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. 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. maxLength: 60 example: Lisbon District zip_code: type: string description: > A US system of postal codes used by the United States Postal Service (USPS). maxLength: 10 example: "94103" eircode: type: string description: > A postal address in Ireland. 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) country code. This definition users `oneOf` with a two-character string type 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. * `sole_trader`: The business is run by an self-employed individual. * `company`: The business is run as a company with one or more shareholders * `partnership`: The business is run as a company with two or more shareholders that can be also other legal entities * `non_profit`: The business is run as a nonprofit organization that operates for public or social benefit * `government_entity`: The business is state owned and operated 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`. 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`. 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. 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. In 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. **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. 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. The more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks). 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. 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. minLength: 1 maxLength: 500 examples: - Thanks for shopping with us. icon: type: string format: uri description: > An icon for the merchant. Must be square. 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. hero: type: string format: uri description: > Data-URL encoded hero image for the merchant business. primary_color: type: string description: > A hex color value representing the primary branding color of this merchant (your brand color). 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. 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). 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. examples: - "#FF4B3A" - "#0072C6" - "#F68B20" background_color: type: string description: > A hex color value representing the preferred background color of this merchant. 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. 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. 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. examples: - "de.gmbh" value: type: string minLength: 1 maxLength: 100 description: > The company identifier value. 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. 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. 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`. The status is only returned after write operations or on read endpoints when the `version` query parameter is provided. 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`. required: - id properties: id: type: string readOnly: true description: > The unique identifier for the Person. This is a [typeid](https://github.com/sumup/typeid). examples: - "pers_2EGQ057R6C8J791RVCG5NWAEAB" user_id: type: string description: > A corresponding identity user ID for the Person, if they have a user account. 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. 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. example: Maria Sophie minLength: 1 maxLength: 60 phone_number: $ref: '#/components/schemas/PhoneNumber' 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`. 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. * `owner`: The Person is a business owner. If this value is set, the `ownership_percent` should be set as well. * `officer`: The Person is an officer at the company. examples: - representative - owner - officer ownership: $ref: '#/components/schemas/Ownership' address: $ref: '#/components/schemas/Address' identifiers: $ref: '#/components/schemas/PersonalIdentifiers' citizenship: $ref: '#/components/schemas/CountryCode' nationality: type: string 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. nullable: true country_of_residence: type: string 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. pattern: "^[A-Z]{2}$" nullable: true 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. properties: name: type: string description: The company's legal name. minLength: 1 maxLength: 150 example: Gin & 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. type: string example: "1532" pattern: ^[0-9]{4}$ legal_type: $ref: '#/components/schemas/LegalType' address: $ref: '#/components/schemas/Address' trading_address: $ref: '#/components/schemas/Address' identifiers: $ref: '#/components/schemas/CompanyIdentifiers' phone_number: $ref: '#/components/schemas/PhoneNumber' website: description: > HTTP(S) URL of the company's website. 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). 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). 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. Present only for readers that are already paired. This 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. Possible values: - `unknown` - The reader status is unknown. - `processing` - The reader is created and waits for the physical device to confirm the pairing. - `paired` - The reader is paired with a merchant account and can be used with SumUp APIs. - `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated. 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 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: - must be between 0.01 and 0.99 total_amount: - must be greater than 0 InstallmentsTooLow: description: Error returned when installments is not within the allowed range. value: errors: installments: - is invalid ReaderBusy: description: Error returned when a checkout was requested in the last 60 seconds. value: errors: detail: There is a pending checkout for the device. type: READER_BUSY ReaderOffline: description: Error returned when the target device is not online. value: errors: detail: The device is offline. type: READER_OFFLINE 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_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. Required for some countries enum: - credit - debit nullable: true type: string 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. nullable: true type: integer payment_failure_reason: description: Payment failure reason nullable: true type: string payment_status: description: Payment status from payments v2 event nullable: true type: string 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. The amount is represented as an integer value altogether with the currency and the minor unit. For example, EUR 1.00 is represented as value 100 with minor unit of 2. 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. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0. 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 nullable: true type: string required: - checkout_id - client_transaction_id - reader_serial_number - payment_type - card_type - reader_firmware_version - installments - payment_status - valid_until - created_at - updated_at - status - total_amount type: object required: - data title: GetReaderCheckoutResponse type: object StatusResponse: description: Status of a device example: data: battery_level: 10.0 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_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. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: string client_transaction_id: description: | The client transaction ID is a unique identifier for the transaction that is generated for the client. It can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get). example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: string required: - client_transaction_id type: object required: - data title: CreateReaderCheckoutResponse 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: Reader Checkout example: aade: provider_id: '123' signature: QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5 signature_data: B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039 affiliate: app_id: com.example.app foreign_transaction_id: '123456' key: ef7b684a-d6f4-4e93-9b1b-6acdd6564a8e tags: {} card_type: debit description: This is a description... installments: 1 return_url: https://webhook.site/e21ddbb0-42c4-4358-a981-f5a95cd86fb5 tip_rates: - 0.05 - 0.1 - 0.15 tip_timeout: 60 total_amount: currency: EUR minor_unit: 2 value: 5033 properties: aade: description: | Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol. When such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider. 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: | Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction. nullable: true properties: app_id: description: | Application ID of the affiliate. It is a unique identifier for the application and should be set by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page. example: com.example.app type: string foreign_transaction_id: description: | Foreign transaction ID of the affiliate. It is a unique identifier for the transaction. It can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get). example: 19e12390-72cf-4f9f-80b5-b0c8a67fa43f type: string key: description: | Key of the affiliate. It is a unique identifier for the key and should be generated by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page. example: 123e4567-e89b-12d3-a456-426614174000 type: string tags: additionalProperties: true description: | Additional metadata for the transaction. It is key-value object that can be associated with the transaction. example: custom_key_1: custom_value_1 custom_key_2: custom_value_2 type: object required: - app_id - key - foreign_transaction_id title: Affiliate type: object card_type: description: | The card type of the card used for the transaction. Is is required only for some countries (e.g: Brazil). 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. It may vary according to the merchant country. For example, in Brazil, the maximum number of installments is 12. Omit if the merchant country does support installments. Otherwise, the checkout will be rejected. example: 1 minimum: 1 nullable: true type: integer return_url: description: | Webhook URL to which the payment result will be sent. It must be a HTTPS url. example: https://www.example.com format: uri type: string tip_rates: description: | List of tipping rates to be displayed to the cardholder. The rates are in percentage and should be between 0.01 and 0.99. The list should be sorted in ascending order. items: format: float multipleOf: 0.01 type: number type: array tip_timeout: default: 30 description: | Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds. It can only be set if `tip_rates` is provided. **Note**: If the target device is a Solo, it must be in version 3.3.38.0 or higher. example: 30 maximum: 120 minimum: 30 type: integer total_amount: description: | Amount structure. The amount is represented as an integer value altogether with the currency and the minor unit. For example, EUR 1.00 is represented as value 100 with minor unit of 2. 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. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0. 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 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: '2020-02-29T10:56:56+00:00' 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: '2020-02-29T10:56:56+00:00' 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 be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction. 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: '2020-02-29T10:56:56+00:00' 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: '2020-02-29T10:56:56+00:00' 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: '2020-02-29T10:56:56+00:00' 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 the list of checkout resources by the unique reference of the checkout. required: false schema: type: string example: f00a8f74-b05d-4605-bd73-2a901bae5802 CheckoutID: name: checkout_id in: path required: true description: Unique identifier of the checkout resource. schema: type: string example: 4e425463-3e1b-431d-83fa-1e51c2925e99 CustomerID: name: customer_id in: path required: true description: Unique identifier of the saved customer resource. 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: Specifies the order in which the returned results are displayed. schema: type: string enum: - ascending - descending default: ascending LimitFilter: name: limit in: query description: |- Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results. schema: type: integer example: 10 UsersFilter: name: users[] in: query description: Filters the returned results by user email. 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 the returned results by the specified list of final statuses of the transactions. 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: |- Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request). 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: |- API keys allow you easily interact with SumUp APIs. API keys are static tokens. You can create API keys from the [Dashboard](https://me.sumup.com/settings/api-keys) type: http scheme: Bearer oauth2: type: oauth2 description: |- SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users. To integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications). To maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication. flows: authorizationCode: authorizationUrl: https://api.sumup.com/authorize tokenUrl: https://api.sumup.com/token refreshUrl: https://api.sumup.com/token scopes: payments: Make payments by creating and processing checkouts. 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. clientCredentials: tokenUrl: 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 employee. 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: 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.