openapi31.yaml

openapi: 3.1.0
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 payment checkout for the specified merchant, amount, and currency. Supply a `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout does not charge a payment instrument.

        Set `hosted_checkout.enabled` to `true` to receive a [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL where the customer can complete the payment.
        Use `redirect_url` for redirect-based payment and 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback URL.

        Complete the payment through [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget).
      tags:
        - Checkouts
      security:
        - apiKey: []
        - oauth2:
            - payments
            - checkouts.write
      x-codegen:
        method_name: create
      x-scopes:
        - payments
        - checkouts.write
      requestBody:
        required: true
        description: Details for creating a checkout resource.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutCreateRequest'
            examples:
              Checkout:
                description: Standard request body for creating a checkout
                value:
                  checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802
                  amount: 10.1
                  currency: EUR
                  merchant_code: MH4H92C7
                  description: Purchase
                  valid_until: '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 the amount, currency, description, reference, expiration, or customer associated with an existing checkout. Only the supplied fields are updated.

        This request changes the checkout details; it does not charge a payment instrument. Process the checkout separately to attempt a payment.
      tags:
        - Checkouts
      security:
        - apiKey: []
        - oauth2:
            - payments
            - checkouts.write
      x-codegen:
        method_name: update
      x-scopes:
        - payments
        - checkouts.write
      requestBody:
        required: true
        description: Details for updating a checkout resource.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutUpdateRequest'
            example:
              amount: 12.5
              currency: EUR
              description: Updated purchase
              checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802
              valid_until: '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: <apple-pay-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.id
          in: query
          description: Filter memberships by the ID of the resource the membership is in.
          schema:
            type: string
        - name: resource.parent.id
          in: query
          allowEmptyValue: true
          description: >-
            Filter memberships by the parent of the resource the membership is in.

            Omit both `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.
          schema:
            type: string
        - name: resource.parent.type
          in: query
          allowEmptyValue: true
          description: >-
            Filter memberships by the parent of the resource the membership is in.

            Omit both `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.
          schema:
            $ref: '#/components/schemas/ResourceType'
        - name: roles
          in: query
          description: Filter the returned memberships by role.
          schema:
            type: array
            items:
              type: string
            example: [role_employee, role_accountant]
          style: form
          explode: true
      responses:
        "200":
          description: Returns a list of Membership objects.
          content:
            application/json:
              schema:
                type: object
                required:
                  - total_count
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Membership'
                  total_count:
                    type: integer
                    example: 3
        "400":
          description: Invalid query parameter combination.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        "401":
          description: Authentication failed or missing required scope.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/unauthorized
                title: Unauthorized
                status: 401
                detail: Authentication credentials are missing or invalid.
  /v0.1/merchants/{merchant_code}/members:
    get:
      parameters:
        - name: offset
          in: query
          description: Offset of the first member to return.
          schema:
            type: integer
            default: 0
            minimum: 0
            example: 0
        - name: limit
          in: query
          description: Maximum number of members to return.
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 25
            example: 10
        - name: scroll
          in: query
          description: Indicates to skip count query.
          x-document: false
          schema:
            type: boolean
            default: false
            example: true
        - name: email
          in: query
          description: Filter the returned members by email address prefix.
          schema:
            type: string
            example: user
        - name: user.id
          in: query
          description: Search for a member by user id.
          schema:
            type: string
            format: uuid
            example: 245b2ead-85bf-45ff-856f-311a88a5d454
        - name: status
          in: query
          description: Filter the returned members by the membership status.
          schema:
            $ref: '#/components/schemas/MembershipStatus'
        - name: roles
          in: query
          description: Filter the returned members by role.
          schema:
            type: array
            items:
              type: string
            example: [role_employee, role_accountant]
          style: form
          explode: true
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
      summary: List members
      description: Lists merchant members.
      tags:
        - Members
      operationId: ListMerchantMembers
      x-codegen:
        method_name: list
      x-permissions:
        - relation: merchant_read
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, members.read]
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - members.read
      responses:
        "200":
          description: Returns a list of Member objects.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
                  total_count:
                    type: integer
                    example: 3
        "404":
          description: Merchant not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
    post:
      operationId: CreateMerchantMember
      summary: Create a member
      description: |-
        Adds a member to the merchant account with the specified roles.

        By default, sends an invitation email to the provided address. The recipient must accept the invitation to join the account.
        When `is_managed_user` is `true`, creates a managed user with the provided password and optional nickname and assigns the roles directly, without sending an invitation.
      tags:
        - Members
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - members.write
      x-codegen:
        method_name: create
      x-permissions:
        - relation: members_create
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, members.write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - roles
              properties:
                is_managed_user:
                  type: boolean
                  description: >-
                    True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname.
                email:
                  type: string
                  format: email
                  description: Email address of the member to add.
                  maxLength: 256
                password:
                  type: string
                  minLength: 8
                  format: password
                  description: Password of the member to add. Only used if `is_managed_user` is true. In the case of service accounts, the password is not used and can not be defined by the caller.
                nickname:
                  type: string
                  example: "Test User"
                  description: >-
                    Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only.
                  maxLength: 64
                roles:
                  type: array
                  description: List of roles to assign to the new member.
                  minItems: 1
                  maxItems: 124
                  items:
                    type: string
                    maxLength: 64
                metadata:
                  $ref: '#/components/schemas/Metadata'
                attributes:
                  $ref: '#/components/schemas/Attributes'
              example:
                email: karl.berg@example.com
                roles: [role_employee]
                # 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: |-
        Updates a merchant member and returns the updated member.

        Providing `roles` replaces the member's assigned roles and can grant or revoke access. Providing `metadata` replaces the entire metadata object.
        For managed users, `user.nickname` changes the display name and `user.password` replaces the password. Updating the password also enables the managed user account.
      tags:
        - Members
      operationId: UpdateMerchantMember
      x-codegen:
        method_name: update
      x-permissions:
        - relation: members_update
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, members.write]
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - members.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  minItems: 1
                  maxItems: 124
                  items:
                    type: string
                    maxLength: 64
                metadata:
                  $ref: '#/components/schemas/Metadata'
                attributes:
                  $ref: '#/components/schemas/Attributes'
                user:
                  type: object
                  description: Allows you to update user data of managed users.
                  properties:
                    nickname:
                      type: string
                      example: "Test User"
                      description: >-
                        User's nickname. Used for display purposes only.
                      maxLength: 64
                    password:
                      type: string
                      format: password
                      minLength: 8
                      description: Password of the member to add. Only used if `is_managed_user` is true.
              example:
                "Update member's role":
                  roles: [role_manager]
                "Update managed user":
                  user:
                    nickname: New Employee Name
      responses:
        "200":
          description: Returns the updated Member object if the update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        "400":
          description: Cannot set password or nickname for an invited user.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        "403":
          description: Cannot change password for managed user. Password was already used before.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to perform this action.
        "404":
          description: Merchant or member not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
        "409":
          description: Cannot update member as some data conflict with existing members.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - in: path
          name: member_id
          description: The ID of the member to retrieve.
          required: true
          schema:
            type: string
            example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
    delete:
      summary: Delete a member
      description: Deletes a merchant member.
      tags:
        - Members
      operationId: DeleteMerchantMember
      x-codegen:
        method_name: delete
      x-permissions:
        - relation: members_delete
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, members.write]
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - members.write
      responses:
        "200":
          description: Returns an empty response if the deletion succeeded.
        "403":
          description: Member deletion was forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to perform this action.
        "404":
          description: Merchant or member not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - in: path
          name: member_id
          description: The ID of the member to retrieve.
          required: true
          schema:
            type: string
            example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
  /v0.1/merchants/{merchant_code}/roles:
    get:
      summary: List roles
      description: List merchant's custom roles.
      tags:
        - Roles
      operationId: ListMerchantRoles
      x-codegen:
        method_name: list
      x-permissions:
        - relation: roles_list
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, roles.read]
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - roles.read
      responses:
        "200":
          description: Returns a list of Role objects.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
        "404":
          description: Merchant not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
    post:
      operationId: CreateMerchantRole
      summary: Create a role
      description: >-
        Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.
      tags:
        - Roles
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - roles.write
      x-codegen:
        method_name: create
      x-permissions:
        - relation: roles_create
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, roles.write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - permissions
              properties:
                name:
                  type: string
                  example: Senior Shop Manager II
                  description: >-
                    User-defined name of the role.
                permissions:
                  type: array
                  description: User's permissions.
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                  example:
                    - catalog_access
                    - taxes_access
                    - members_access
                metadata:
                  $ref: '#/components/schemas/Metadata'
                description:
                  type: string
                  example: "Manges the shop and the employees."
                  description: >-
                    User-defined description of the role.
      responses:
        "201":
          description: Returns the Role object after successful custom role creation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        "400":
          description: Invalid request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        "404":
          description: Merchant not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
  /v0.1/merchants/{merchant_code}/roles/{role_id}:
    get:
      summary: Retrieve a role
      description: Retrieve a custom role by ID.
      tags:
        - Roles
      operationId: GetMerchantRole
      x-codegen:
        method_name: get
      x-permissions:
        - relation: roles_view
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, roles.read]
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - roles.read
      responses:
        "200":
          description: Returns the Role object for a valid identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        "404":
          description: Merchant or role not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - in: path
          name: role_id
          description: The ID of the role to retrieve.
          required: true
          schema:
            type: string
            example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
    delete:
      operationId: DeleteMerchantRole
      summary: Delete a role
      description: Delete a custom role.
      tags:
        - Roles
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - roles.write
      x-codegen:
        method_name: delete
      x-permissions:
        - relation: roles_delete
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, roles.write]
      responses:
        "200":
          description: Returns an empty response if the role deletion succeeded.
        "400":
          description: Invalid request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        "404":
          description: Merchant not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - in: path
          name: role_id
          description: The ID of the role to retrieve.
          required: true
          schema:
            type: string
            example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
    patch:
      operationId: UpdateMerchantRole
      summary: Update a role
      description: |-
        Updates a custom role's name, description, or permissions and returns the updated role.

        Providing `permissions` replaces the role's permission list and changes the access granted to members assigned to that role. Omitted fields remain unchanged.
      tags:
        - Roles
      security:
        - apiKey: []
        - oauth2:
            - user.subaccounts
            - roles.write
      x-codegen:
        method_name: update
      x-permissions:
        - relation: roles_update
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [user.subaccounts, roles.write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Senior Shop Manager II
                  description: >-
                    User-defined name of the role.
                permissions:
                  type: array
                  description: User's permissions.
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                  example:
                    - catalog_access
                    - taxes_access
                    - members_access
                description:
                  type: string
                  example: "Manges the shop and the employees."
                  description: >-
                    User-defined description of the role.
              example:
                name: 'Senior Shop Manager III'
                permissions:
                  - catalog_edit
                  - taxes_access
                  - members_edit
      responses:
        "200":
          description: Returns the updated Role object if the update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        "400":
          description: Invalid request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        "404":
          description: Merchant not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - in: path
          name: role_id
          description: The ID of the role to retrieve.
          required: true
          schema:
            type: string
            example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
  /v1/merchants/{merchant_code}:
    get:
      operationId: GetMerchant
      summary: Get Merchant
      description: >-
        Returns a Merchant for a valid Merchant code.
      tags:
        - Merchants
      externalDocs:
        description: Merchant documentation
        url: https://developer.sumup.com/tools/models/merchant
      x-codegen:
        method_name: get
      x-scopes: ["user.profile", "user.profile_readonly"]
      x-permissions: [merchant_read]
      security:
        - apiKey: []
        - oauth2:
            - user.profile
            - user.profile_readonly
      responses:
        "200":
          description: Returns a Merchant for a valid identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant'
        "404":
          description: The requested Merchant does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
  /v1/merchants/{merchant_code}/persons:
    get:
      operationId: ListPersons
      summary: List Persons
      description: >-
        Returns the Persons related to a Merchant.
      tags:
        - Merchants
      externalDocs:
        description: Persons documentation
        url: https://developer.sumup.com/tools/models/merchant#persons
      x-scopes: ["user.profile", "user.profile_readonly"]
      x-permissions: [persons_read]
      x-codegen:
        method_name: list_persons
      security:
        - apiKey: []
        - oauth2:
            - user.profile
            - user.profile_readonly
      responses:
        "200":
          description: Returns a list of Persons for a valid Merchant identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPersonsResponseBody'
        "404":
          description: The requested Merchant does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
  /v1/merchants/{merchant_code}/persons/{person_id}:
    get:
      operationId: GetPerson
      summary: Get Person
      description: >-
        Returns a single Person related to a Merchant.
      tags:
        - Merchants
      externalDocs:
        description: Persons documentation
        url: https://developer.sumup.com/tools/models/merchant#persons
      x-scopes: ["user.profile", "user.profile_readonly"]
      x-permissions: [persons_read]
      x-codegen:
        method_name: get_person
      security:
        - apiKey: []
        - oauth2:
            - user.profile
            - user.profile_readonly
      responses:
        "200":
          description: Returns a Person for a valid identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        "404":
          description: The requested Person does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - name: person_id
          description: Person ID
          in: path
          required: true
          schema:
            type: string
            example: pers_5AKFHN2KSK8D3TS79DJE3P3A2Z
  /v0.1/merchants/{merchant_code}/readers:
    get:
      summary: List Readers
      description: List all readers of the merchant.
      operationId: ListReaders
      tags:
        - Readers
      x-codegen:
        method_name: list
      x-permissions:
        - relation: readers.list
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [readers.read, terminals.read]
      security:
        - apiKey: []
        - oauth2:
            - readers.read
            - terminals.read
      responses:
        "200":
          description: Returns a list Reader objects.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reader'
        "401":
          description: Authentication failed or missing required scope.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/unauthorized
                title: Unauthorized
                status: 401
                detail: Authentication credentials are missing or invalid.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
    post:
      summary: Create a Reader
      operationId: CreateReader
      description: Create a new Reader for the merchant account.
      tags:
        - Readers
      x-codegen:
        method_name: create
      x-permissions:
        - relation: readers.create
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [readers.write, terminals.write]
      security:
        - apiKey: []
        - oauth2:
            - readers.write
            - terminals.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pairing_code
                - name
              properties:
                pairing_code:
                  $ref: '#/components/schemas/ReaderPairingCode'
                name:
                  $ref: '#/components/schemas/ReaderName'
                metadata:
                  $ref: '#/components/schemas/Metadata'
      responses:
        "201":
          description: Returns the Reader object if the creation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reader'
              examples:
                created:
                  summary: A reader that waits for the physical device to acknowledge the pairing.
                  value:
                    id: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
                    name: Frontdesk
                    status: processing
                    device:
                      identifier: U1DT3NA00-CN
                      model: solo
                    created_at: "2023-05-09T14:50:20.214Z"
                    updated_at: "2023-05-09T14:52:58.714Z"
          links:
            UpdateReaderByID:
              operationId: UpdateReader
              parameters:
                reader_id: "$response.body#/id"
              description: >-
                Update the reader object. This can be used to set a name after using this endpoint to verify the pairing code.
            DeleteReaderByID:
              operationId: DeleteReader
              parameters:
                reader_id: "$response.body#/id"
              description: >-
                Delete the reader.
        "400":
          description: The request is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/bad-request
                title: Bad Request
                status: 400
                detail: Request validation failed.
        "404":
          description: There's no pending reader for the submitted pairing code.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
        "409":
          description: The Reader is not in a pending state.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
  /v0.1/merchants/{merchant_code}/readers/{reader_id}:
    get:
      summary: Retrieve a Reader
      description: Retrieve a Reader.
      operationId: GetReader
      tags:
        - Readers
      x-codegen:
        method_name: get
      x-permissions:
        - relation: readers.view
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [readers.read, terminals.read]
      security:
        - apiKey: []
        - oauth2:
            - readers.read
            - terminals.read
      parameters:
        - in: header
          name: If-Modified-Since
          description: |-
            Return the reader only if it has been modified after the specified timestamp given in the headers.

            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: |-
        Updates a reader's name or metadata and returns the updated reader.

        Providing `metadata` replaces the entire metadata object; include all entries that should be retained. Omitted fields remain unchanged.
      operationId: UpdateReader
      tags:
        - Readers
      x-codegen:
        method_name: update
      x-permissions:
        - relation: readers.update
          object_type: merchant
          object_id_param: merchant_code
      x-scopes: [readers.write, terminals.write]
      security:
        - apiKey: []
        - oauth2:
            - readers.write
            - terminals.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/ReaderName'
                metadata:
                  $ref: '#/components/schemas/Metadata'
      responses:
        "200":
          description: Returns the updated Reader object if the update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reader'
        "403":
          description: The request isn't sufficiently authorized to modify the reader.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to perform this action.
        "404":
          description: The requested Reader resource does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/not-found
                title: Requested resource couldn't be found.
                status: 404
                detail: The requested resource doesn't exist or does not belong to you.
      parameters:
        - name: merchant_code
          description: Short unique identifier for the merchant.
          in: path
          required: true
          schema:
            type: string
            example: MK10CL2A
        - name: reader_id
          in: path
          description: The unique identifier of the reader.
          required: true
          schema:
            $ref: '#/components/schemas/ReaderID'
  /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout:
    post:
      callbacks:
        ReaderCheckoutStatusChange:
          '{$request.body#/return_url}':
            post:
              callbacks: {}
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ReaderCheckoutStatusChange'
                required: true
              responses:
                '200':
                  description: |
                    Your server returns this code if it accepts the callback.
                    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
            - "null"
          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.
        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
            - "null"
          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.
        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
            - "null"
          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.
        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
    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
    UserType:
      type: string
      description: Type of the user account.
      enum:
        - user
        - managed_user
        - service_account
        - system_account
      example: user
    Address:
      externalDocs:
        description: Address documentation
        url: https://developer.sumup.com/tools/glossary/address
      description: >-
        An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, `city` is `post_town`. In the United States, the top-level administrative unit used in addresses is `state`, whereas in Chile it's `region`.

        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
            - "null"
          pattern: "^[A-Z]{2}$"
          description: >
            The Person's nationality. May be an [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, but legacy data may not conform to this standard.

        country_of_residence:
          type:
            - string
            - "null"
          description: >
            An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code representing the country where the Person resides.

          pattern: "^[A-Z]{2}$"
        version:
          $ref: '#/components/schemas/Version'
        change_status:
          $ref: '#/components/schemas/ChangeStatus'
    Company:
      externalDocs:
        description: Company documentation
        url: https://developer.sumup.com/tools/glossary/merchant#company
      type: object
      description: >
        Information about the company or business. This is legal information that is used for verification.

      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
              type:
                - string
                - "null"
            checkout_id:
              description: Unique identifier for the checkout
              format: uuid
              type: string
            client_transaction_id:
              description: Client transaction identifier associated with the checkout
              type: string
            created_at:
              description: Checkout creation timestamp
              format: date-time
              type: string
            installments:
              description: Number of installments for the transaction. Required for some countries.
              type:
                - integer
                - "null"
            payment_failure_reason:
              description: Payment failure reason
              type:
                - string
                - "null"
            payment_status:
              description: Payment status from payments v2 event
              type:
                - string
                - "null"
            payment_type:
              description: Type of the payment. Required for some countries
              enum:
                - card
                - pix
              type: string
            reader_firmware_version:
              description: Reader firmware version
              type: string
            reader_serial_number:
              description: Device serial number
              type: string
            status:
              description: Current status of the checkout
              enum:
                - pending
                - successful
                - failed
                - cancelled
              type: string
            total_amount:
              description: |
                Amount structure.

                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
              type:
                - string
                - "null"
          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.
          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
            - "null"
        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
          type:
            - integer
            - "null"
        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.