SumUp Transactions API

openapi: 3.2.0
info:
  title: SumUp REST Checkouts Transactions 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: 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'
paths:
  /v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds:
    parameters:
    - name: merchant_code
      in: path
      description: Merchant code of the account that owns the payment to refund.
      required: true
      schema:
        type: string
        example: MH4H92C7
    - name: transaction_id
      in: path
      description: Unique ID of the transaction.
      required: true
      schema:
        type: string
    post:
      operationId: RefundTransaction
      summary: Refund a transaction
      description: Refunds an identified transaction either in full or partially.
      requestBody:
        description: Optional amount for partial refunds.
        content:
          application/json:
            example:
              amount: 5
            schema:
              description: Optional amount for partial refunds of transactions.
              type: object
              properties:
                amount:
                  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.
                  type: number
                  format: float
                  example: 5
      responses:
        '204':
          description: Returns an empty response body when the operation succeeds.
        '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 transaction cannot be refunded due to business constraints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Transaction_Not_Refundable:
                  description: The state of the identified transaction resource does not permit the requested operation.
                  value:
                    error_code: CONFLICT
                    message: The transaction is not refundable in its current state
                Not_Enough_Balance:
                  description: The merchant balance does not allow performing the refund.
                  value:
                    error_code: NOT_ENOUGH_BALANCE
                    message: Not enough available balance to perform the operation at the moment
      security:
      - apiKey: []
      - oauth2:
        - payments
      tags:
      - Transactions
      x-codegen:
        method_name: refund
      x-scopes:
      - payments
  /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`'
      parameters:
      - name: merchant_code
        in: path
        description: Merchant code of the account whose transaction should be retrieved.
        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
      - name: transaction_code
        in: query
        description: Retrieves the transaction resource with the specified transaction code.
        required: false
        schema:
          type: string
      - name: foreign_transaction_id
        in: query
        description: External/foreign transaction id (passed by clients).
        schema:
          type: string
      - name: client_transaction_id
        in: query
        description: Client transaction id.
        schema:
          type: string
      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-29 10:56:56.876000+00:00
                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
      security:
      - apiKey: []
      - oauth2:
        - transactions.history
      tags:
      - Transactions
      x-codegen:
        method_name: get
      x-scopes:
      - transactions.history
  /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.
      parameters:
      - name: merchant_code
        in: path
        description: Merchant code of the account whose transaction history should be listed.
        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
      - name: order
        in: query
        description: Specifies the order in which the returned results are displayed.
        schema:
          type: string
          default: ascending
          enum:
          - ascending
          - descending
      - 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
      - name: users
        in: query
        description: Filters the returned results by user email.
        required: false
        schema:
          type: array
          items:
            type: string
            format: email
          example:
          - merchant@example.com
        example:
        - merchant@example.com
      - name: statuses[]
        in: query
        description: Filters the returned results by the specified list of final statuses of the transactions.
        required: false
        schema:
          type: array
          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
          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
          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
          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
      - 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
      - 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
      - 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
      - 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
      responses:
        '200':
          description: Returns a page of transaction history items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionHistory'
                    example:
                    - transaction_code: TEENSK4W2K
                      amount: 10.1
                      currency: EUR
                      timestamp: 2020-02-29 10:56:56.876000+00:00
                      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:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionsHistoryLink'
                    example: []
              example:
                items:
                - transaction_code: TEENSK4W2K
                  amount: 10.1
                  currency: EUR
                  timestamp: 2020-02-29 10:56:56.876000+00:00
                  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
      security:
      - apiKey: []
      - oauth2:
        - transactions.history
      tags:
      - Transactions
      x-codegen:
        method_name: list
      x-scopes:
      - transactions.history
components:
  schemas:
    Currency:
      description: Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.
      type: string
      example: EUR
      enum:
      - BGN
      - BRL
      - CHF
      - CLP
      - COP
      - CZK
      - DKK
      - EUR
      - GBP
      - HRK
      - HUF
      - NOK
      - PLN
      - RON
      - SEK
      - USD
      title: Currency
    EntryMode:
      description: Entry mode of the payment details.
      type: string
      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
      title: Entry Mode
    TransactionID:
      description: Unique ID of the transaction.
      type: string
      title: Transaction ID
    HorizontalAccuracy:
      description: Indication of the precision of the geographical position received from the payment terminal.
      type: number
      format: float
      title: Horizontal Accuracy
    EventStatus:
      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.'
      type: string
      enum:
      - FAILED
      - PAID_OUT
      - PENDING
      - RECONCILED
      - REFUNDED
      - SCHEDULED
      - SUCCESSFUL
      title: Event Status
    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
      additionalProperties: true
      required:
      - type
      title: Problem
    CardType:
      description: Issuing card network of the payment card used for the transaction.
      type: string
      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
      title: Card Type
    TransactionFull:
      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:
            description: External/foreign transaction id (passed by clients).
            type: string
            example: J13253253x1
          client_transaction_id:
            description: Client transaction id.
            type: string
            example: urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2
          username:
            description: Email address of the registered user (merchant) to whom the payment is made.
            type: string
            format: email
          fee_amount:
            description: Transaction SumUp total fee amount.
            type: number
            format: decimal
            example: 8
          lat:
            $ref: '#/components/schemas/Lat'
          lon:
            $ref: '#/components/schemas/Lon'
          horizontal_accuracy:
            $ref: '#/components/schemas/HorizontalAccuracy'
          merchant_id:
            description: SumUp merchant internal Id.
            type: integer
            format: int64
            example: 136902
          device_info:
            $ref: '#/components/schemas/Device'
          simple_payment_type:
            description: Simple name of the payment type.
            type: string
            enum:
            - CASH
            - CC_SIGNATURE
            - ELV
            - ELV_WITHOUT_SIGNATURE
            - CC_CUSTOMER_ENTERED
            - MANUAL_ENTRY
            - EMV
            - RECURRING
            - BALANCE
            - MOTO
            - BOLETO
            - APM
            - BITCOIN
            - CARD
          verification_method:
            description: Verification method used for the transaction.
            type: string
            enum:
            - none
            - signature
            - offline PIN
            - online PIN
            - offline PIN + signature
            - na
          card:
            $ref: '#/components/schemas/CardResponse'
          elv_account:
            $ref: '#/components/schemas/ElvCardAccount'
          local_time:
            description: Local date and time of the creation of the transaction.
            type: string
            format: date-time
          payout_date:
            description: The date of the payout.
            type: string
            format: date
            example: 2019-08-28
          payout_type:
            description: Payout type for the transaction.
            type: string
            enum:
            - BANK_ACCOUNT
            - PREPAID_CARD
          process_as:
            description: Debit/Credit.
            type: string
            example: CREDIT
            enum:
            - CREDIT
            - DEBIT
          products:
            description: List of products from the merchant's catalogue for which the transaction serves as a payment.
            type: array
            items:
              $ref: '#/components/schemas/Product'
          vat_rates:
            description: List of VAT rates applicable to the transaction.
            type: array
            items:
              type: object
              properties:
                rate:
                  description: VAT rate.
                  type: number
                  format: decimal
                  example: 0.045
                net:
                  description: NET amount of products having this VAT rate applied.
                  type: number
                  format: decimal
                  example: 1.36
                vat:
                  description: VAT amount of this rate applied.
                  type: number
                  format: decimal
                  example: 0.06
                gross:
                  description: Gross amount of products having this VAT rate applied.
                  type: number
                  format: decimal
                  example: 1.42
          transaction_events:
            description: Detailed list of events related to the transaction.
            type: array
            items:
              $ref: '#/components/schemas/TransactionEvent'
          simple_status:
            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.'
            type: string
            enum:
            - SUCCESSFUL
            - PAID_OUT
            - CANCEL_FAILED
            - CANCELLED
            - CHARGEBACK
            - FAILED
            - REFUND_FAILED
            - REFUNDED
            - NON_COLLECTION
            - PENDING
          links:
            description: List of hyperlinks for accessing related resources.
            type: array
            items:
              $ref: '#/components/schemas/Link'
          events:
            description: Compact list of events related to the transaction.
            type: array
            items:
              $ref: '#/components/schemas/Event'
          location:
            description: Details of the payment location as received from the payment terminal.
            type: object
            properties:
              lat:
                $ref: '#/components/schemas/Lat'
              lon:
                $ref: '#/components/schemas/Lon'
              horizontal_accuracy:
                $ref: '#/components/schemas/HorizontalAccuracy'
          tax_enabled:
            description: Indicates whether tax deduction is enabled for the transaction.
            type: boolean
      title: Transaction Full
    PaymentType:
      description: Payment type used for the transaction.
      type: string
      enum:
      - CASH
      - POS
      - ECOM
      - RECURRING
      - BITCOIN
      - BALANCE
      - MOTO
      - BOLETO
      - DIRECT_DEBIT
      - APM
      - UNKNOWN
      title: Payment Type
    Product:
      description: Purchase product.
      type: object
      properties:
        name:
          description: Product name.
          type: string
          example: Purchase reader for merchant with code ME3FCAVF
        price_label:
          description: Product description.
          type: string
        price:
          description: Product price.
          type: number
          format: decimal
          example: 100
        vat_rate:
          description: VAT percentage.
          type: number
          format: decimal
        single_vat_amount:
          description: VAT amount for a single product.
          type: number
          format: decimal
        price_with_vat:
          description: Product price incl. VAT.
          type: number
          format: decimal
        vat_amount:
          description: VAT amount.
          type: number
          format: decimal
        quantity:
          description: Product quantity.
          type: integer
          example: 1
        total_price:
          description: Quantity x product price.
          type: number
          format: decimal
          example: 100
        total_with_vat:
          description: Total price incl. VAT.
          type: number
          format: decimal
      title: Product
    TransactionCheckoutInfo:
      description: Checkout-specific fields associated with a transaction.
      type: object
      properties:
        merchant_code:
          description: Unique code of the registered merchant to whom the payment is made.
          type: string
          example: MH4H92C7
        vat_amount:
          description: Amount of the applicable VAT (out of the total transaction amount).
          type: number
          format: float
          example: 6
        tip_amount:
          description: Amount of the tip (out of the total transaction amount).
          type: number
          format: float
          example: 3
        entry_mode:
          $ref: '#/components/schemas/EntryMode'
        auth_code:
          description: Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
          type: string
          example: '053201'
      title: Transaction Checkout Info
    EventID:
      description: Unique ID of the transaction event.
      type: integer
      format: int64
      title: Event ID
    TransactionMixinHistory:
      description: Additional transaction fields used by history and detailed views.
      type: object
      properties:
        product_summary:
          description: Short description of the payment. The value is taken from the `description` property of the related checkout resource.
          type: string
        payouts_total:
          description: Total number of payouts to the registered user specified in the `user` property.
          type: integer
        payouts_received:
          description: Number of payouts that are made to the registered user specified in the `user` property.
          type: integer
        payout_plan:
          description: Payout plan of the registered user at the time when the transaction was made.
          type: string
          enum:
          - SINGLE_PAYMENT
          - TRUE_INSTALLMENT
          - ACCELERATED_INSTALLMENT
      title: Transaction Mixin History
    Link:
      description: Details of a link to a related resource.
      type: object
      properties:
        rel:
          description: Specifies the relation to the current resource.
          type: string
        href:
          description: URL for accessing the related resource.
          type: string
          format: uri
        type:
          description: Specifies the media type of the related resource.
          type: string
        min_amount:
          description: Minimum allowed amount for the refund.
          type: number
          format: float
        max_amount:
          description: Maximum allowed amount for the refund.
          type: number
          format: float
      title: Link
    Event:
      description: High-level transaction event details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/EventID'
        transaction_id:
          $ref: '#/components/schemas/TransactionID'
        type:
          $ref: '#/components/schemas/EventType'
        status:
          $ref: '#/components/sc

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sumup/refs/heads/main/openapi/sumup-transactions-api-openapi.yml