SumUp Payouts API

openapi: 3.0.1
info:
  title: SumUp REST Checkouts Payouts 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: 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'
paths:
  /v1.0/merchants/{merchant_code}/payouts:
    get:
      operationId: ListPayoutsV1
      summary: List payouts
      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`.'
      parameters:
      - name: merchant_code
        in: path
        description: Merchant code of the account whose payouts should be listed.
        required: true
        schema:
          type: string
          example: MH4H92C7
      - name: start_date
        in: query
        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
      - name: end_date
        in: query
        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
      - name: format
        in: query
        description: Response format for the payout list.
        required: false
        schema:
          type: string
          example: json
          default: json
          enum:
          - json
          - csv
      - name: limit
        in: query
        description: Maximum number of payout records to return.
        required: false
        schema:
          type: integer
          example: 10
          maximum: 9999
          minimum: 1
      - name: order
        in: query
        description: Sort direction for the returned payouts.
        required: false
        schema:
          type: string
          example: desc
          default: asc
          enum:
          - asc
          - 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:
                description: CSV-formatted payout export returned when `format=csv`.
                type: string
              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
      security:
      - apiKey: []
      - oauth2:
        - user.profile
        - user.profile_readonly
      tags:
      - Payouts
      x-codegen:
        method_name: list
      x-scopes:
      - user.profile
      - user.profile_readonly
components:
  schemas:
    ErrorExtended:
      description: Error payload with the invalid parameter reference.
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          param:
            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.
            type: string
      title: Error Extended
    FinancialPayout:
      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
      properties:
        id:
          description: Unique identifier of the payout-related record.
          type: integer
          example: 123456789
        type:
          description: High-level payout record category.
          type: string
          example: PAYOUT
          enum:
          - PAYOUT
          - CHARGE_BACK_DEDUCTION
          - REFUND_DEDUCTION
          - DD_RETURN_DEDUCTION
          - BALANCE_DEDUCTION
        amount:
          description: Amount of the payout or deduction in major units.
          type: number
          format: float
          example: 132.45
        date:
          description: Payout date associated with the record, in `YYYY-MM-DD` format.
          type: string
          format: date
          example: 2024-02-29
        currency:
          description: Three-letter ISO 4217 currency code of the payout.
          type: string
          example: EUR
        fee:
          description: Fee amount associated with the payout record, in major units.
          type: number
          format: float
          example: 3.12
        status:
          description: Merchant-facing outcome of the payout record.
          type: string
          example: SUCCESSFUL
          enum:
          - SUCCESSFUL
          - FAILED
        reference:
          description: Processor or payout reference associated with the record.
          type: string
          example: payout-2024-02-29
        transaction_code:
          description: Transaction code of the original sale associated with the payout or deduction.
          type: string
          example: TEENSK4W2K
      required:
      - id
      - type
      - amount
      - date
      - currency
      - fee
      - status
      - reference
      - transaction_code
      title: Financial Payout
    FinancialPayouts:
      description: Ordered list of payout and payout-deduction records.
      type: array
      items:
        $ref: '#/components/schemas/FinancialPayout'
      title: Financial Payouts
    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
    Error:
      description: Error message structure.
      type: object
      properties:
        message:
          description: Short description of the error.
          type: string
          example: Resource not found
        error_code:
          description: Platform code for the error.
          type: string
          example: NOT_FOUND
      title: Error
  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.
            transactions.history: View transactions and transaction history.
            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.
            user.payout-settings: View and manage your payout settings.
            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.
            transactions.history: View transactions and transaction history.
            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.
            user.payout-settings: View and manage your payout settings.
            user.subaccounts: View and manage the user profile details of your employee.