openapi: 3.1.0
info:
  title: Getpaid Accounts API
  version: v2
  contact:
    email: support@getpaid.io
  description: '# Getting started


    Our APIs provide programmatic access to the Getpaid solution. This page contains a comprehensive reference for all

    resources of the Getpaid public API. For walkthrough documentation please see [Getpaid guides](/) for step by step usage

    of the Getpaid platform including the API and [Getpaid API integration](/integration/api) for the technical aspects of

    this Getpaid API.


    To get started, book a demo and sign up at <https://getpaid.io>. This will give you access to the [Getpaid

    dashboard](https://dashboard.getpaid.io) where you can configure your account and retrieve your credentials needed to

    authenticate with Getpaid API.


    ## Postman


    Getpaid provides a Postman collection to test the API features in sandbox. You can [download the Postman collection and

    the environments](/integration/api/postman) to start testing the Getpaid API.


    ## Fields formats


    | Type | Format |

    | :- | :- |

    | `amount-minor` | Amount in the minor currency unit (e.g. 100 cents for 1 EUR). |

    | `country` | The country code fields follow the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) in uppercase. Examples: `DE`, `US`. |

    | `currency` | The currency code fields follow the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. Examples: `EUR`, `USD`. |

    | `date` | Dates are formatted using the complete date format according to the [ISO 8601 standard](https://www.w3.org/TR/NOTE-datetime): `YYYY-MM-DD`. Example: `2023-09-30`.                                        |

    | `date-time` | Date-time fields are formatted using the [ISO 8601 standard](https://www.w3.org/TR/NOTE-datetime) for the combined date and time in UTC with 3 seconds fractional digits: `YYYY-MM-DDThh:mm:ss.SSSZ`. Example: `2015-09-01T23:59:59.479Z`. |

    | `date-time-offset` | Date-time fields with time-zone are formatted [ISO 8601 standard](https://www.w3.org/TR/NOTE-datetime) for the combined date and time with the time-zone and no second fractional digits: `YYYY-MM-DDThh:mm:ssTZD`. Example: `2015-09-01T23:59:59+01:00`. |

    | `email` | Email fields should follow the [RFC 5322](https://tools.ietf.org/html/rfc5322) standard. Example: `jon.smith@acme.com` |

    | `hex-color` | Colors are represented as a string starting with `#` followed by six hexadecimal digits. Each pair of digits represents the intensity of red, green, and blue components respectively. Examples: `#FFFFFF`, `#000000`, `#FF5733`. |

    | `id` | Identifiers are formatted as a string of 3 alphabetic characters (which represents the type of the identified object), one underscore and 26 alphanumeric characters. Every identifier generated in our system is globally unique. Examples: `acc_44678r08jtm8zbt227tzhc4nw5`, `doc_473cr1y0ghbyc3m1yfbwvn3nxx`. |

    | `ip-address` | IP fields are formatted using the [Internet Protocol version 4 (IPv4)](https://en.wikipedia.org/wiki/Internet_Protocol_version_4) standard: `x.x.x.x` where `x` must be a decimal value between `0` and `255`. Example: `192.158.1.38`. |

    | `version` | A resource version. For resources that can evolved over time, a unique reference of the snapshot used in other resource. For example, the account information used for a payment, the information used for the statement descriptor or the processing configuration are tighted to the version of the account. |

    '
servers:
- url: https://api.getpaid.io
  description: Live
- url: https://api.sandbox.getpaid.io
  description: Sandbox
tags:
- name: Accounts
  description: Getpaid accounts created for sellers so they can start accepting payments and receiving payouts.
paths:
  /v2/accounts/query:
    post:
      tags:
      - Accounts
      summary: Query accounts
      description: 'Query accounts filtering, sorting and paginating results.


        See [Queries](/operate/queries) for more examples and details about pagination and common query patterns.

        '
      operationId: query_accounts
      security:
      - OAuth:
        - accounts:read
      parameters:
      - $ref: '#/components/parameters/GetpaidIdempotencyKey'
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryAccountsRequest'
            examples:
              QueryAccounts:
                $ref: '#/components/examples/QueryAccounts'
        required: true
      responses:
        '200':
          description: OK
          headers:
            Getpaid-Trace-Id:
              $ref: '#/components/headers/GetpaidTraceId'
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAccountsResponse'
              examples:
                FilteredAccounts:
                  $ref: '#/components/examples/FilteredAccounts'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '422':
          $ref: '#/components/responses/422InvalidParameters'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /v2/accounts/{account_id}/themes:
    get:
      tags:
      - Accounts
      summary: Get account themes
      description: 'Retrieve the themes configured for an account.


        Sellers can retrieve themes they own. Platforms can retrieve themes for sellers they own.

        '
      operationId: get_account_themes
      security:
      - OAuth:
        - accounts:read
      parameters:
      - name: account_id
        in: path
        description: The ID of the account whose themes should be retrieved.
        required: true
        schema:
          $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: OK
          headers:
            Getpaid-Trace-Id:
              $ref: '#/components/headers/GetpaidTraceId'
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetThemesResponse'
              examples:
                AccountThemes:
                  $ref: '#/components/examples/AccountThemes'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
components:
  examples:
    FilteredAccounts:
      summary: Filtered accounts
      value:
        type: accounts
        cursor: Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==
        data:
        - id: acc_44678r08jtm8zbt227tzhc4nw5
          legal_name: Garage Deutschland AG
          country: DE
          created_at: '2026-01-16T08:02:55.339Z'
        - id: acc_5y789s19kum9act338uaic5ox6
          legal_name: Titan Auto Parts GmbH
          country: DE
          created_at: '2026-01-04T11:28:17.144Z'
    AccountThemes:
      summary: Account themes
      value:
        themes:
        - id: thm_4jkgtzffbf9pzem7dgfhdeztwa
          name: Default Titan Auto Parts GmbH
          settings:
            logo:
              id: doc_4wt0wrfqwz0vkatave0fkjg046
              content_type: image/png
              url: https://example.com/logo.png
            business:
              legal_name: Titan Auto Parts GmbH
              trading_name: Titan Auto
            colors:
              primary: '#05495c'
              secondary: '#e07b7b'
          is_default: true
          created_at: '2026-02-03T10:00:00.000Z'
          updated_at: '2026-02-03T10:00:00.000Z'
    QueryAccounts:
      summary: Query accounts
      value:
        type: accounts
        filters:
          country: DE
          legal_name: Garage
        sorts:
        - field: created_at
          direction: descending
  responses:
    422InvalidParameters:
      description: Invalid Parameters
      headers:
        Getpaid-Trace-Id:
          $ref: '#/components/headers/GetpaidTraceId'
      content:
        application/problem+json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ProblemDetailsBase'
            - type: object
              required:
              - errors
              properties:
                errors:
                  type: object
                  description: The JSON path of any request body fields or header names that are invalid with a description of the error
                  additionalProperties:
                    type: array
                    items:
                      type: string
                  example:
                    currency:
                    - invalid_option
                type:
                  example: https://docs.getpaid.io/integration/api/responses#422---invalid-parameters
                title:
                  example: Invalid Parameters
                status:
                  example: 422
    404NotFound:
      description: Not Found
      headers:
        Getpaid-Trace-Id:
          $ref: '#/components/headers/GetpaidTraceId'
      content:
        application/problem+json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ProblemDetailsBase'
            - type: object
              properties:
                type:
                  example: https://docs.getpaid.io/integration/api/responses#404---not-found
                title:
                  example: Not Found
                status:
                  example: 404
    500InternalServerError:
      description: Internal Server Error
      headers:
        Getpaid-Trace-Id:
          $ref: '#/components/headers/GetpaidTraceId'
    429TooManyRequests:
      description: Too Many Requests
      headers:
        Getpaid-Trace-Id:
          $ref: '#/components/headers/GetpaidTraceId'
    401Unauthorized:
      description: Unauthorized
      headers:
        Getpaid-Trace-Id:
          $ref: '#/components/headers/GetpaidTraceId'
    400BadRequest:
      description: Bad Request
      headers:
        Getpaid-Trace-Id:
          $ref: '#/components/headers/GetpaidTraceId'
  schemas:
    QueryAccountsRequest:
      allOf:
      - $ref: '#/components/schemas/BaseQueryRequest'
      - required:
        - type
        properties:
          type:
            type: string
            enum:
            - accounts
          filters:
            $ref: '#/components/schemas/AccountsFiltersRequest'
          sorts:
            $ref: '#/components/schemas/AccountsSortsRequest'
    PaginationData:
      description: The list of queried elements.
      type: array
      items:
        type: object
    AccountId:
      allOf:
      - $ref: '#/components/schemas/Id'
      - description: The unique identifier of the account.
        example: acc_44678r08jtm8zbt227tzhc4nw5
    AccountsFiltersRequest:
      description: Filtering accounts.
      type: object
      properties:
        id:
          allOf:
          - description: The account identifier to filter by using an exact match operation.
          - $ref: '#/components/schemas/AccountId'
        legal_name:
          description: The account legal name to filter by using a contains operation.
          type: string
          maxLength: 255
        country:
          allOf:
          - description: The country to filter by using an exact match operation.
          - $ref: '#/components/schemas/Country'
    MediumString:
      type: string
      minLength: 1
      maxLength: 250
    PaginationFirst:
      description: Pagination. The number of elements that will be retrieved.
      type: integer
      default: 20
      minimum: 1
      maximum: 100
    ThemeId:
      allOf:
      - $ref: '#/components/schemas/Id'
      - description: The unique identifier of the theme.
        example: thm_4jkgtzffbf9pzem7dgfhdeztwa
    Country:
      type: string
      format: country
      minLength: 2
      maxLength: 2
      description: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      example: DE
    AccountLegalName:
      allOf:
      - description: The legal name of the account.
      - $ref: '#/components/schemas/MediumString'
    DateTime:
      description: 'UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)).

        Always includes the ''Z'' UTC indicator.

        '
      type: string
      format: date-time
      minLength: 24
      maxLength: 24
      example: '2025-09-01T22:05:48.479Z'
    AccountThemeSettings:
      type: object
      required:
      - logo
      - business
      - colors
      properties:
        logo:
          $ref: '#/components/schemas/ThemeAsset'
        icon:
          $ref: '#/components/schemas/ThemeAsset'
        business:
          $ref: '#/components/schemas/ThemeBusinessSettings'
        colors:
          $ref: '#/components/schemas/ThemeColorSettings'
        font:
          $ref: '#/components/schemas/ThemeFontSettings'
    PaginatedResponse:
      type: object
      required:
      - data
      properties:
        cursor:
          $ref: '#/components/schemas/PaginationCursor'
        data:
          $ref: '#/components/schemas/PaginationData'
    ThemeAsset:
      type: object
      required:
      - id
      - content_type
      - url
      properties:
        id:
          $ref: '#/components/schemas/DocumentId'
        content_type:
          type: string
          description: The media type of the theme asset.
          example: image/png
        url:
          allOf:
          - $ref: '#/components/schemas/Url'
          - description: The public URL of the theme asset.
            example: https://example.com/logo.png
    BaseQueryRequest:
      type: object
      properties:
        type:
          description: 'The type of the Getpaid solution resources to query.


            Some query endpoints infer the resource type from the request path. In those cases, if this field is set, it

            must match the resource targeted by the request URL.

            '
          type: string
        first:
          allOf:
          - $ref: '#/components/schemas/PaginationFirst'
        after:
          $ref: '#/components/schemas/PaginationAfter'
        filters:
          description: Filters to reduce the data set to query. If not set, all resources available of the given type will be queried.
        sorts:
          $ref: '#/components/schemas/BaseSortsRequest'
    ThemeBusinessSettings:
      type: object
      required:
      - legal_name
      properties:
        legal_name:
          allOf:
          - $ref: '#/components/schemas/MediumString'
          - description: The legal business name displayed by the theme.
        trading_name:
          allOf:
          - $ref: '#/components/schemas/MediumString'
          - description: The trading name displayed by the theme.
    CreatedAt:
      allOf:
      - description: When the resource was created.
      - $ref: '#/components/schemas/DateTime'
    UpdatedAt:
      allOf:
      - description: When the resource was last updated.
      - $ref: '#/components/schemas/DateTime'
    PaginationCursor:
      description: The cursor to the last item. If non-empty, can be used to fetch the next page. If not set, there is no more elements.
      type: string
      maxLength: 250
      example: Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==
    ThemeFontSettings:
      type: object
      properties:
        family:
          allOf:
          - $ref: '#/components/schemas/MediumString'
          - description: The font family used by the theme.
        size:
          type: string
          description: The base font size used by the theme.
          example: 0.875rem
        external_url:
          allOf:
          - $ref: '#/components/schemas/Url'
          - description: The URL of the external font stylesheet used by the theme.
            example: https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap
    PaginationAfter:
      description: Pagination. The `cursor` from next page will be retrieved.
      type: string
      maxLength: 250
    AccountTheme:
      type: object
      required:
      - id
      - name
      - settings
      - is_default
      - created_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/ThemeId'
        name:
          allOf:
          - $ref: '#/components/schemas/MediumString'
          - description: The name of the theme.
        settings:
          $ref: '#/components/schemas/AccountThemeSettings'
        is_default:
          type: boolean
          description: Whether this is the default theme for the account.
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
    ThemeColorSettings:
      type: object
      required:
      - primary
      - secondary
      properties:
        primary:
          type: string
          description: The primary theme color as a hex RGB value.
          example: '#05495c'
        secondary:
          type: string
          description: The secondary theme color as a hex RGB value.
          example: '#e07b7b'
        text:
          type: string
          description: The text theme color as a hex RGB value.
          example: '#000000'
        error_text:
          type: string
          description: The error text theme color as a hex RGB value.
          example: '#b71d18'
    AccountsSortsRequest:
      description: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
      type: array
      minItems: 1
      uniqueItems: true
      items:
        allOf:
        - $ref: '#/components/schemas/BaseSortItemRequest'
        - properties:
            field:
              enum:
              - id
              - created_at
              - legal_name
              - country
    Id:
      type: string
      format: id
      minLength: 30
      maxLength: 50
    BaseSortItemRequest:
      description: Each field to sort by.
      type: object
      required:
      - field
      - direction
      properties:
        field:
          description: The field to sort by. Each field available can only be used once in the list.
          type: string
        direction:
          description: The sort direction
          type: string
          enum:
          - ascending
          - descending
    GetThemesResponse:
      type: object
      required:
      - themes
      properties:
        themes:
          type: array
          description: The account themes.
          items:
            $ref: '#/components/schemas/AccountTheme'
    ProblemDetailsBase:
      type: object
      description: The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)].
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the problem type. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
          format: uri
          example: https://docs.getpaid.io/ref/error-types#problem
        title:
          type: string
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
          example: Invalid Request
        status:
          type: integer
          description: The HTTP status code.
          minimum: 400
          maximum: 599
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: The request body was invalid
    Url:
      type: string
      format: uri
      maxLength: 1024
    DocumentId:
      allOf:
      - $ref: '#/components/schemas/Id'
      - description: The unique identifier of the document.
        example: doc_4wt0wrfqwz0vkatave0fkjg046
    BaseSortsRequest:
      description: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
      type: array
      minItems: 1
      uniqueItems: true
      items:
        description: Each field to sort by.
        type: object
        required:
        - field
        - direction
        properties:
          field:
            description: The field to sort by. Each field available can only be used once in the list.
            type: string
          direction:
            description: The sort direction
            type: string
            enum:
            - ascending
            - descending
    QueryAccountsResponse:
      allOf:
      - required:
        - type
        properties:
          type:
            type: string
            enum:
            - accounts
          cursor:
            type: string
          data:
            items:
              required:
              - id
              - legal_name
              - country
              - created_at
              properties:
                id:
                  $ref: '#/components/schemas/AccountId'
                legal_name:
                  $ref: '#/components/schemas/AccountLegalName'
                country:
                  $ref: '#/components/schemas/Country'
                created_at:
                  $ref: '#/components/schemas/CreatedAt'
      - $ref: '#/components/schemas/PaginatedResponse'
  parameters:
    GetpaidIdempotencyKey:
      name: Getpaid-Idempotency-Key
      in: header
      description: 'A unique idempotency key to allow safe retrying.

        See [Getpaid API idempotency](/integration/api/idempotency) for more details.

        '
      schema:
        type: string
        minLength: 10
        maxLength: 100
        pattern: ^[a-zA-Z0-9_-]{10,100}$
        example: 5c255194-30ec-11ed-a261-0242ac120002
  headers:
    GetpaidTraceId:
      description: The trace identifier for the request. It is a good idea to log this and provide it with any support requests
      schema:
        type: string
        example: 96ce50247f87f540bb2d86771b3728b8
  securitySchemes:
    OAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.getpaid.io/oauth/token
          scopes:
            accounts:read: Allows to read accounts and onboarding applications.
            accounts:read_write: Allows to read, create and/or operate accounts and onboarding applications.
            payments:read: Allows to read payments and checkouts.
            payments:read_write: Allows to read, create and/or operate payments and checkouts.
x-tagGroups:
- name: General
  tags:
  - Authentication
  - Documents
- name: Accept payments
  tags:
  - Checkouts
  - Payments
  - Accept payments webhooks
- name: Onboard sellers
  tags:
  - Accounts
  - Applications
  - Onboard sellers webhooks
- name: Operate
  tags:
  - Queries
  - Exports
  - Analytics
  - Operate webhooks