openapi: 3.0.1
info:
  title: Paysera Checkout Integration API
  description: API reference for Paysera Checkout integration endpoints. Use these
    endpoints to create payment orders, generate payment links, and query available
    payment methods.
  version: 1.0.0
  contact:
    name: Paysera Technical Support
    email: tech_support@paysera.com
servers:
- url: https://api.paysera.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Integration Project Management
  description: Integration Project Management
  x-displayName: Integration Project Management
- name: Integration payment links
  description: Integration API endpoints for managing payment links
  x-displayName: Integration payment links
- name: Integration Order Management
  description: API endpoints for managing orders
  x-displayName: Integration Order Management
paths:
  /checkout-project/integration/v1/methods:
    get:
      tags:
      - Integration Project Management
      summary: Get Available Payment Methods
      description: Retrieve all available payment methods for a project. The response
        includes details about each payment method, such as its key, title, description,
        type, flow, and the countries where it is available. Optional filtering by
        transaction amount and currency - when both parameters are provided, only
        payment methods whose limits encompass the specified amount will be returned.
      operationId: getPaymentMethods
      parameters:
      - name: amount
        in: query
        description: Transaction amount for filtering payment methods by limits. Filtering
          is only applied when both amount and currency are provided. If omitted,
          all payment methods are returned without limit filtering.
        required: false
        schema:
          type: integer
          example: 1000
        example: 5000
      - name: currency
        in: query
        description: Transaction currency code (ISO 4217) for filtering payment methods
          by limits. Filtering is only applied when both amount and currency are provided.
          If omitted, all payment methods are returned without limit filtering.
        required: false
        schema:
          type: string
          maxLength: 3
          minLength: 3
          example: EUR
        example: EUR
      responses:
        '200':
          description: Available payment methods successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_GetAvailablePaymentMethodsResponse'
              example:
                items:
                - key: swedbank
                  title: Swedbank
                  description: Pay via Swedbank online banking
                  type: pis
                  flow: redirect
                  available_countries: [LT, LV, EE]
                  available_currencies:
                    EUR:
                      main: true
                - key: revolut
                  title: Revolut
                  description: Pay via Revolut
                  type: wallet
                  flow: redirect
                  available_countries: [LT, LV, EE, UA]
                  available_currencies:
                    EUR:
                      main: true
                    USD:
                      main: false
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: unauthorized
                  error_description:
                    type: string
                    example: Authentication required
                type: object
              example:
                error: unauthorized
                error_description: Authentication required
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: not_found
                  error_description:
                    type: string
                    example: Project not found or no payment methods available
                type: object
              example:
                error: not_found
                error_description: Project not found or no payment methods available
  /checkout-project/integration/v1/split-beneficiaries:
    post:
      tags:
      - Integration Project Management
      summary: Register a split beneficiary
      description: |
        Register a recipient that order splits can reference by id. The recipient is
        identified by IBAN; whether it is a Paysera account or an external bank account
        is resolved server-side and returned as `destination_type`. An external IBAN is
        only accepted when external beneficiaries are enabled for the project, and the
        IBAN must not resolve to the project owner's own account. The returned `id` is
        the `beneficiary_id` used in order `splits[]`.
      operationId: createSplitBeneficiary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Checkout_Merchant_Project_API_CreateSplitBeneficiaryRequest'
      responses:
        '201':
          description: Beneficiary registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryResponse'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                destination_type: paysera_account
                account_number: EVP5210018145214
                name: Marketplace Seller 42
                created_at: 1716200000
        '400':
          description: |
            Invalid input — `invalid_properties` (field validation; details in
            `error_properties`) or `invalid_request` (malformed JSON).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: invalid_properties
                error_description: Validation failed
                error_properties:
                  iban:
                  - This value is not a valid IBAN.
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication required
        '409':
          description: A beneficiary with this account already exists for the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: conflict
                error_description: A beneficiary with this account already exists
        '422':
          description: |
            The request is well-formed but cannot be fulfilled — returned as
            `unprocessable_entity` with the reason in `error_description` (for example:
            split beneficiaries not enabled for the project, the IBAN belongs to the
            project owner, the IBAN is an external account but external beneficiaries
            are not enabled for the project, external beneficiaries are not allowed
            because payer tips are enabled, or the Paysera account behind the IBAN is
            inactive or closed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unprocessable_entity
                error_description: Split beneficiaries are not enabled for this project
    get:
      tags:
      - Integration Project Management
      summary: List split beneficiaries
      description: |
        List the project's registered split beneficiaries (cursor-paginated). The
        merchant's own self-row is included with a `null` id and cannot be referenced
        in order splits.
      operationId: getSplitBeneficiaries
      parameters:
      - name: after
        in: query
        required: false
        description: Cursor for the next page. Mutually exclusive with `before`.
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Cursor for the previous page. Mutually exclusive with `after`.
        schema:
          type: string
      - name: order_direction
        in: query
        required: false
        description: Sort direction by creation time.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: include_total
        in: query
        required: false
        description: Include the total count in `_metadata.total`.
        schema:
          type: boolean
          default: false
      - name: size
        in: query
        required: false
        description: Page size.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      responses:
        '200':
          description: Beneficiaries retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryListResponse'
              example:
                items:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  destination_type: paysera_account
                  account_number: EVP5210018145214
                  bic: null
                  name: Marketplace Seller 42
                  created_at: 1716200000
                  consent_status: null
                _metadata:
                  has_next: false
                  has_previous: false
                  cursors:
                    after: null
                    before: null
                  total: 1
        '400':
          description: Invalid query parameters (`invalid_properties`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: invalid_properties
                error_description: Validation failed
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication required
  /checkout-project/integration/v1/split-beneficiaries/by-phone:
    post:
      tags:
      - Integration Project Management
      summary: Register a split beneficiary by phone
      description: |
        Register a tip recipient by the phone number of their Paysera account. The
        person must already have a Paysera individual account registered to that
        phone number. Available only on projects with payer tips enabled.

        For Lithuanian merchants the returned `account_number` is `null`: the
        recipient's payout account is assigned later, when they give tax-agent
        consent. For other merchants the recipient's Paysera account is assigned
        immediately.
      operationId: createSplitBeneficiaryByPhone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Checkout_Merchant_Project_API_CreateSplitBeneficiaryByPhoneRequest'
      responses:
        '201':
          description: Beneficiary registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryByPhoneResponse'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: John D.
                account_number: null
                created_at: 1716200000
        '400':
          description: |
            Invalid input — `invalid_properties` (missing, malformed, too short or
            too long phone number) or `invalid_request` (malformed JSON).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: invalid_properties
                error_description: Validation failed
                error_properties:
                  phone:
                  - This value is not a valid phone number.
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication required
        '409':
          description: |
            A beneficiary for this person already exists for the project (duplicates
            are detected by the Paysera user the phone number resolves to).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: conflict
                error_description: A split beneficiary already exists for this project (Tip recipients)
        '422':
          description: |
            `unprocessable_entity` — payer tips are not enabled for the project, or
            no Paysera individual account was found for this phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unprocessable_entity
                error_description: No Paysera individual was found for this phone number
  /checkout-project/integration/v1/split-beneficiaries/{beneficiaryId}:
    delete:
      tags:
      - Integration Project Management
      summary: Delete a split beneficiary
      description: |
        Remove a registered beneficiary. Fails if the beneficiary is still referenced
        by the project's split policy.
      operationId: deleteSplitBeneficiary
      parameters:
      - name: beneficiaryId
        in: path
        required: true
        description: Id of the beneficiary to delete.
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Beneficiary deleted (no content)
        '400':
          description: The `beneficiaryId` path parameter is not a valid UUID (`invalid_properties`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: invalid_properties
                error_description: Validation failed
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication required
        '404':
          description: Beneficiary not found for this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: not_found
                error_description: Split beneficiary not found
        '409':
          description: |
            The beneficiary is still referenced by the split policy.
            `error_properties.referenced_by_slot_positions` lists the policy slot
            positions that reference it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: conflict
                error_description: Beneficiary is referenced by the split policy
                error_properties:
                  referenced_by_slot_positions:
                  - '1'
        '422':
          description: |
            `unprocessable_entity` — split beneficiaries not enabled, or attempting to
            delete the merchant's own self-row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unprocessable_entity
                error_description: The merchant's own beneficiary cannot be deleted
  /checkout-project/integration/v1/project/split-policy:
    get:
      tags:
      - Integration Project Management
      summary: Get the project split policy
      description: |
        Read the project's split-policy template — each slot's `slot_id`, role, and
        configured rule. Use the `slot_id`s to bind variadic order entries and to build
        per-order overrides.
      operationId: getSplitPolicy
      responses:
        '200':
          description: Split policy retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ProjectSplitPolicyResponse'
              example:
                project_id: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                configured: true
                slots:
                - slot_id: 11111111-1111-1111-1111-111111111111
                  position: 0
                  role: merchant
                  rule_type: percentage
                  value: 1000
                  beneficiary_id: null
                  beneficiary_account_number: null
                  beneficiary_name: null
                  beneficiary_missing: false
                - slot_id: 22222222-2222-2222-2222-222222222222
                  position: 1
                  role: variadic
                  rule_type: remainder
                  value: null
                  beneficiary_id: null
                  beneficiary_account_number: null
                  beneficiary_name: null
                  beneficiary_missing: false
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication required
        '404':
          description: The project has no split-policy template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse'
              example:
                error: not_found
                error_description: Split policy not found
  /checkout-payment-link/integration/v1/payment-links:
    post:
      tags:
      - Integration payment links
      summary: Create a new payment link via integration
      description: "\n            Creates a new payment link with the provided details\
        \ through the integration API.\n            A unique payment link will be\
        \ generated and returned in the response.\n        "
      operationId: createPaymentLink
      parameters:
      - name: Accept-Language
        in: header
        description: Preferred language for the response
        required: false
        schema:
          type: string
          enum:
          - en
          - lt
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Checkout_Payment_Link_API_CreatePaymentLinkIntegrationRequest'
        required: true
      responses:
        '201':
          description: Payment link created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Payment_Link_API_CreatePaymentLinkIntegrationResponse'
              example:
                link_id: c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f
                order_id: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a
                payment_URL: https://api.paysera.com/checkout-payment-link/payment-collection/v1/payment-links/abc123def456GhiJkl_mNOpQrStUvWxYz0123456
                experience:
                  language: en
                  payment_flow: paysera_checkout
                payment_details:
                  key: credit_card
                  purpose: Order #12345 - Leather Wallet
                  country_code: LT
                purchase:
                  amount: 2500
                payer_information:
                  name: John Doe
                  email: john@example.com
                expired_at: 1736436870
                created_at: 1736433270
        '400':
          description: |
            Invalid input. When the underlying order has splits, the link must not
            expire — passing a non-zero `lifetime` is rejected with
            `validation_split_expiration_not_allowed`. For a split order the link amount
            must also equal the order's full amount; a mismatch is rejected with
            `validation_split_amount_mismatch`.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Checkout_Payment_Link_API_ValidationErrorResponse'
                - $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse'
              example:
                error: invalid_properties
                error_description: One or more fields failed validation
                error_properties:
                  purchase.amount:
                  - This value should be greater than 0
        '401':
          description: Unauthorized - Invalid or missing API credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication is required to access this resource
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse'
              example:
                error: not_found
                error_description: Payment link not found
        '409':
          description: |
            A payment link with this name already exists for the order
            (`validation_duplicate_name`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse'
              example:
                error: validation_duplicate_name
                error_description: A payment link with this name already exists
  /merchant-order/integration/v1/orders:
    post:
      tags:
      - Integration Order Management
      summary: Create a new order
      description: "\n            Creates a new order with the provided details.\n\
        \            The order will be initialized in 'collecting-funds' status.\n\
        \            A unique order ID will be generated and returned in the response.\n\
        \        "
      operationId: createOrder
      parameters:
      - name: Accept-Language
        in: header
        description: 'Preferred language for the response. Supported values: ''en''
          (English) and ''lt'' (Lithuanian)'
        required: false
        schema:
          type: string
          enum:
          - en
          - lt
          default: en
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Merchant_Order_API_IntegrationCreateOrderRequest'
        required: true
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant_Order_API_IntegrationCreateOrderResponse'
              example:
                project_id: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                order_id: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a
                created_at: 1736433270
                merchant_data:
                  key1: value1
                  key2: value2
                source: https://example.com
                purchase:
                  reference: ORDER-12345
                  amount: 2500
                  currency: EUR
        '400':
          description: |
            Invalid input. For orders with `splits`, request-validation problems
            return `400` — e.g. `intermediary_account_required` (the project is not
            configured for splits) or `invalid_properties` (an entry's `type` is not
            `variadic` or `tip`). Policy and beneficiary conflicts return `422`.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Merchant_Order_API_ValidationErrorResponse'
                - $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse'
              example:
                error: invalid_properties
                error_description: One or more fields failed validation
                error_properties:
                  purchase.amount:
                  - This value should be a positive whole number
        '401':
          description: Unauthorized - Invalid or missing API credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse'
              example:
                error: unauthorized
                error_description: Authentication is required to access this resource
        '422':
          description: |
            Split validation error. The `error` field identifies the specific problem.

            Common split-related codes:
            * `policy_not_configured` — the policy template has unfilled slots
            * `policy_invalid` — the project's split policy is invalid
            * `variadic_entry_required` — the policy expects a variadic entry
            * `variadic_entry_not_allowed` — the policy has no variadic slot but one was sent
            * `variadic_entry_requires_policy` — a variadic entry was sent but the project has no split policy
            * `split_variadic_count_mismatch` — the number of variadic entries doesn't match the policy
            * `tip_entries_without_tips_enabled` — tip entries sent but payer tips are disabled
            * `split_variadic_slot_id_required` / `_unknown` / `_duplicate` — variadic `slot_id` binding problems
            * `variadic_beneficiary_required` / `tip_beneficiary_required` — an entry names no recipient
            * `split_entry_identifier_invalid` — an entry sets both `beneficiary_id` and `beneficiary`
            * `tip_beneficiary_consent_not_given` — the tip recipient has not given tax-agent consent (LT)
            * `inline_beneficiary_not_allowed_for_tip` — an inline `beneficiary` on a `tip` entry, on a project under the tax-agent consent regime
            * `inline_beneficiary_rejected` — the inline beneficiary was refused registration; `error_properties.rule` carries the stable reason key
            * `split_beneficiary_not_found` — a `beneficiary_id` is not registered for the project
            * `split_beneficiary_account_not_found` — a resolved EVP account does not exist
            * `split_amount_too_low` — order amount is below the minimum the policy needs to settle
            * `splits_invalid` — the resulting split configuration is invalid

            Per-order override (`split_overrides`) codes:
            * `overrides_not_enabled` — per-order overrides are not enabled on the project
            * `split_overrides_require_policy` — overrides sent but the project has no policy
            * `split_overrides_incomplete` / `split_override_unknown_slot` / `split_override_duplicate_slot` — slot restatement problems
            * `split_override_recipient_required` / `_not_allowed` / `_invalid` / `_ambiguous` — per-slot recipient problems (`_ambiguous`: more than one of `beneficiary_id` / `account` / `beneficiary` set)
            * `split_override_account_not_resolvable` — `account` is not a Paysera account; use an inline `beneficiary` or a registered `beneficiary_id` instead
            * `split_override_value_invalid` — value invalid for the slot's rule type
            * `split_override_variadic_entry_not_allowed` — a `variadic` entry was sent in `splits` alongside overrides
            * `split_remainder_required` / `split_too_many_remainders` / `split_percentage_sum_exceeded` — aggregate rule violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse'
              example:
                error: variadic_entry_required
                error_description: The configured split policy requires exactly one variadic entry.
components:
  schemas:
    Checkout_Merchant_Project_API_GetAvailablePaymentMethodsResponse:
      required:
      - items
      properties:
        items:
          description: List of available payment methods
          type: array
          items:
            $ref: '#/components/schemas/Checkout_Merchant_Project_API_GetAvailablePaymentMethodResponse'
      type: object
    Checkout_Merchant_Project_API_GetAvailablePaymentMethodResponse:
      required:
      - title
      - type
      - flow
      - available_countries
      - available_currencies
      properties:
        key:
          description: Unique identifier for the payment method
          type: string
          example: swedbank
          nullable: true
        title:
          description: Display name of the payment method
          type: string
          example: Credit/Debit Card
        description:
          description: Detailed description of the payment method
          type: string
          example: Pay via credit or debit card.
          nullable: true
        type:
          description: Type of payment method
          type: enum
          enum:
          - card
          - banklink
          - wallet
          - pis
          example: card
        flow:
          description: Flow type
          type: enum
          enum:
          - redirect
          - decoupled
          example: redirect
        available_countries:
          description: List of country codes where this payment method is available
          type: array
          items:
            type: string
          example:
          - LT
          - EE
          - UA
        available_currencies:
          description: Available currencies configuration for this payment method
          type: object
          example:
            EUR:
              main: true
            USD:
              main: false
          additionalProperties:
            type: array
            items: {}
      type: object
    Checkout_Payment_Link_API_ValidationErrorResponse:
      required:
      - error
      - error_description
      - error_properties
      type: object
      properties:
        error_properties:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        error_description:
          type: string
        error:
          type: string
    Checkout_Payment_Link_API_SimpleErrorResponse:
      required:
      - error
      - error_description
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    Checkout_Payment_Link_API_CreatePaymentLinkIntegrationRequest:
      required:
      - experience
      - name
      - order_id
      - purchase
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 0
          type: string
          description: Descriptive name for the payment link
          example: April Invoice Payment
        lifetime:
          maximum: 86313600
          minimum: 0
          type: integer
          description: |
            The lifetime of the link in seconds. If omitted, the default value
            259200 (3 days) is used. If value is 0, the link never expires.

            **Must be `0` if the underlying order has splits** — otherwise the request
            is rejected with `validation_split_expiration_not_allowed`.
          format: int64
          example: 3600
        experience:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_ExperienceDto'
        payment_details:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_PaymentDetailsDto'
        purchase:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_PurchaseDto'
        payer_information:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_PayerInformationDto'
        order_id:
          type: string
          description: An reference ID for the associated order.
          format: uuid
          example: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a
        metadata:
          type: object
          additionalProperties:
            type: string
            description: Additional metadata key-value pairs
            example: '{"referrer":"https://paysera.net"}'
          description: Additional metadata key-value pairs
          example:
            referrer: https://paysera.net
      description: Request for integration payment link creation
    Checkout_Payment_Link_API_ExperienceDto:
      required:
      - language
      type: object
      properties:
        language:
          minLength: 1
          pattern: ^[a-z]{2}$
          type: string
          description: The language of the payment link, selected from the project's
            description languages
          example: en
        payment_flow:
          type: string
          description: Payment flow type - can be null for default flow
          nullable: true
          enum:
            - paysera_checkout
            - direct_payment
          example: paysera_checkout
          default: paysera_checkout
      description: Payment experience configuration
    Checkout_Payment_Link_API_PayerInformationDto:
      type: object
      properties:
        name:
          maxLength: 150
          minLength: 0
          type: string
          description: Payer name
          example: John Doe
        email:
          type: string
          description: Payer email. Required if the payment link is personalized
          example: customer@example.com
      description: Payer information
    Checkout_Payment_Link_API_PaymentDetailsDto:
      type: object
      properties:
        key:
          type: string
          description: Preferred payment method key
          example: credit_card
        purpose:
          maxLength: 255
          minLength: 0
          type: string
          description: Payment purpose description
          example: 'Order #12345 - Leather Wallet'
        country_code:
          pattern: ^[A-Z]{2}$
          type: string
          description: Country code in ISO 3166-1 alpha-2 format
          example: LT
      description: Payment details
    Checkout_Payment_Link_API_PurchaseDto:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 1
          type: number
          description: The amount to be paid in minor currency units (e.g. cents)
          example: 1000
      description: Purchase information
    Checkout_Payment_Link_API_CreatePaymentLinkIntegrationResponse:
      required:
      - created_at
      - experience
      - link_id
      - order_id
      - payer_information
      - payment_URL
      - payment_details
      - purchase
      type: object
      properties:
        link_id:
          type: string
          description: Unique payment link ID
          format: uuid
        order_id:
          type: string
          description: Unique order ID
          format: uuid
          example: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a
        payment_URL:
          type: string
          description: Payment URL
          example: www.example.com/sasdadw
        experience:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_ExperienceResponseDto'
        payment_details:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_PaymentDetailsResponseDto'
        purchase:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_PurchaseResponseDto'
        payer_information:
          $ref: '#/components/schemas/Checkout_Payment_Link_API_PayerInformationResponseDto'
        expired_at:
          type: integer
          description: Payment link expiration timestamp in UTC timezone
          format: int64
          example: 1745925943
        created_at:
          type: integer
          description: Payment link creation timestamp in UTC timezone
          format: int64
          example: 1745925543
      description: Response after integration payment link creation
    Checkout_Payment_Link_API_ExperienceResponseDto:
      required:
      - language
      - payment_flow
      type: object
      properties:
        language:
          type: string
          description: The language of the payment link, selected from the project's
            description languages
          example: en
        payment_flow:
          type: string
          description: Payment flow type
          enum:
            - paysera_checkout
            - direct_payment
          example: paysera_checkout
      description: Payment experience configuration response
    Checkout_Payment_Link_API_PayerInformationResponseDto:
      type: object
      properties:
        name:
          type: string
          description: Payer name
          example: John Doe
        email:
          type: string
          description: Payer email
          example: customer@example.com
      description: Payer information response
    Checkout_Payment_Link_API_PaymentDetailsResponseDto:
      type: object
      properties:
        key:
          type: string
          description: Payment method key
          example: card
        purpose:
          type: string
          description: Payment purpose
          example: 'Order #12345 - Leather Wallet'
        country_code:
          type: string
          description: Country code in ISO 3166-1 alpha-2 format
          example: LT
      description: Payment details response
    Checkout_Payment_Link_API_PurchaseResponseDto:
      required:
      - amount
      type: object
      properties:
        amount:
          type: integer
          description: The amount to be paid in minor currency units (e.g. cents)
          format: int64
          example: 4999
      description: Purchase information response
    Merchant_Order_API_ValidationErrorResponse:
      required:
      - error
      - error_description
      - error_properties
      type: object
      properties:
        error_properties:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        error_description:
          type: string
        error:
          type: string
    Merchant_Order_API_SimpleErrorResponse:
      required:
      - error
      - error_description
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    Merchant_Order_API_IntegrationCreateOrderRequest:
      required:
      - purchase
      type: object
      properties:
        project_id:
          type: string
          description: Project identifier. If not provided, will be extracted from
            JWT token.
          format: uuid
          example: c35593b8-6b65-4cae-9d8e-39af32578ba7
        redirect_urls:
          $ref: '#/components/schemas/Merchant_Order_API_RedirectUrls'
        metadata:
          type: object
          additionalProperties:
            type: string
            description: "\n            Additional data attached to the order in key-value\
              \ format.\n            Each key and value must be at most 255 characters\
              \ long.\n            \"Keys and values exceeding 255 characters will\
              \ be automatically trimmed.\n        "
            example: '{"platform":"shopify","platform_version":"2.11.0","plugin_name":"paysera-checkout","plugin_version":"1.4.3","referrer":"https://merchantsite.com/somepage"}'
          description: "\n            Additional data attached to the order in key-value\
            \ format.\n            Each key and value must be at most 255 characters\
            \ long.\n            \"Keys and values exceeding 255 characters will be\
            \ automatically trimmed.\n        "
          example:
            platform: shopify
            platform_version: 2.11.0
            plugin_name: paysera-checkout
            plugin_version: 1.4.3
            referrer: https://merchantsite.com/somepage
        merchant_data:
          type: object
          additionalProperties:
            type: string
            description: "\n            Merchant data attached to the order in key-value\
              \ format.\n            Each key and value must be at most 255 characters\
              \ long.\n        "
            example: '{"key1":"value1","key2":"value2","key3":"value3"}'
          description: "\n            Merchant data attached to the order in key-value\
            \ format.\n            Each key and value must be at most 255 characters\
            \ long.\n        "
          example:
            key1: value1
            key2: value2
            key3: value3
        source:
          maxLength: 255
          minLength: 0
          type: string
          description: "\n            Source indicating where this order originated\
            \ from.\n            \"Can be a website URL or other identifier.\n   \
            \         \"If not specified or empty, defaults to 'Integration'\n   \
            \         "
          example: https://myshop.paysera.net
          default: Integration
        purchase:
          $ref: '#/components/schemas/Merchant_Order_API_Purchase'
        splits:
          type: array
          nullable: true
          description: |
            Per-order entries for the project's split policy. Send one `variadic`
            entry per variadic slot in the policy template, and one `tip` entry per
            tip recipient when payer tips are enabled. Each entry names its recipient
            either by `beneficiary_id` (a beneficiary registered for the project) or
            with an inline `beneficiary` declaration that registers the recipient on
            the fly — the merchant share, percentages, and fixed shares come from the
            policy template, so do not send them.

            Orders with splits require a non-expiring payment link (`lifetime: 0`).
          items:
            $ref: '#/components/schemas/Merchant_Order_API_SplitRequest'
        split_overrides:
          allOf:
          - $ref: '#/components/schemas/Merchant_Order_API_SplitOverridesRequest'
          description: |
            Per-order override of the project's split-policy rules. Restates
            every policy slot for this order only — changing each slot's rule and/or
            recipient without altering the saved policy. Requires the project to have
            per-order overrides enabled. This is the only path that accepts a recipient
            account directly (without registering a beneficiary). Tips still travel in
            `splits` as `tip` entries.
      description: Request for order creation
    Merchant_Order_API_SplitRequest:
      required:
      - type
      type: object
      description: |
        Single split entry. `type` selects the role; the recipient is named by exactly
        one of `beneficiary_id` (a beneficiary registered for the project) or an
        inline `beneficiary` declaration. The rule (fixed amount or percentage) is
        configured on the project's split-policy template — your integration does not
        send it.
      properties:
        type:
          type: string
          description: |
            Role of this entry:
            * `variadic` — the per-order recipient that fills the policy template's
              variadic slot (e.g., the marketplace seller for this specific order).
            * `tip` — a recipient of an extra tip the payer chooses to add on top of
              the order total.
          enum:
          - variadic
          - tip
          example: variadic
        beneficiary_id:
          type: string
          format: uuid
          nullable: true
          description: |
            Id of the registered split beneficiary to pay. Register beneficiaries via
            the integration split-beneficiaries API; the merchant's self-beneficiary
            cannot be referenced here. Provide either this or `beneficiary`, not both.
          example: 550e8400-e29b-41d4-a716-446655440000
        beneficiary:
          allOf:
          - $ref: '#/components/schemas/Merchant_Order_API_InlineSplitBeneficiaryRequest'
          description: |
            Inline beneficiary declaration — registers the recipient for the project
            as part of order creation. Provide either this or `beneficiary_id`, not
            both. Not accepted for `tip` entries on projects under the tax-agent
            consent regime.
        slot_id:
          type: string
          format: uuid
          nullable: true
          description: |
            Policy slot this variadic entry binds to. Required only when the policy has
            more than one variadic slot; with a single variadic slot it binds
            automatically. Ignored for `tip` entries.
          example: c1a2b3d4-e5f6-7890-abcd-ef1234567890
    Merchant_Order_API_SplitOverridesRequest:
      required:
      - slots
      type: object
      description: |
        Per-order restatement of the project's split policy. Must restate every
        policy slot exactly once. Exactly one slot must be `remainder`, and the
        `percentage` slots must sum to less than 100%.
      properties:
        slots:
          type: array
          minItems: 1
          description: One entry per policy slot. Every slot of the policy must be listed exactly once.
          items:
            $ref: '#/components/schemas/Merchant_Order_API_SplitOverrideSlotRequest'
    Merchant_Order_API_SplitOverrideSlotRequest:
      required:
      - slot_id
      - type
      type: object
      description: Restated rule for a single policy slot.
      properties:
        slot_id:
          type: string
          format: uuid
          description: |
            Identifies which policy slot is being restated (from the split-policy
            response). The recipient is taken from that policy slot unless `recipient`
            is supplied.
          example: c1a2b3d4-e5f6-7890-abcd-ef1234567890
        type:
          type: string
          description: |
            Rule type for this slot:
            * `fixed` — `value` in minor units / cents.
            * `percentage` — `value` in basis points (1 bp = 0.01%; 10000 = 100%).
            * `remainder` — omit `value`; the slot absorbs the residual.
          enum:
          - fixed
          - percentage
          - remainder
          example: percentage
        value:
          type: integer
          format: int64
          nullable: true
          description: |
            Rule value. Required for `fixed` (cents, > 0) and `percentage`
            (basis points, 1–10000); omit for `remainder`.
          example: 1500
        recipient:
          allOf:
          - $ref: '#/components/schemas/Merchant_Order_API_SplitOverrideRecipientRequest'
          description: |
            Recipient for this slot. Required for a `variadic` slot, optional for a
            fixed `beneficiary` slot (replaces the policy recipient), and must be
            omitted for the `merchant` slot.
    Merchant_Order_API_SplitOverrideRecipientRequest:
      type: object
      description: |
        Recipient of an override slot. Provide exactly one of `beneficiary_id`,
        `account`, or `beneficiary`.
      properties:
        beneficiary_id:
          type: string
          format: uuid
          nullable: true
          description: Id of a split beneficiary already registered for the project.
          example: 550e8400-e29b-41d4-a716-446655440000
        account:
          type: string
          nullable: true
          description: |
            A Paysera account paid directly, without prior registration — given as
            an EVP account number or as the IBAN of a Paysera account (resolved
            server-side). A non-Paysera IBAN is not accepted here, as `account`
            carries no beneficiary name — declare it via `beneficiary` or register
            it as a beneficiary first.
          example: LT403500010018497892
        beneficiary:
          allOf:
          - $ref: '#/components/schemas/Merchant_Order_API_InlineSplitBeneficiaryRequest'
          description: |
            Inline beneficiary declaration — registers the recipient for the project
            as part of order creation.
    Merchant_Order_API_InlineSplitBeneficiaryRequest:
      required:
      - iban
      - name
      type: object
      description: |
        Beneficiary declared inline on an order. Registered for the project as the
        order is created (the returned beneficiary can be reused on later orders). If
        the IBAN is already registered for the project, the existing beneficiary is
        reused and keeps its stored name. Whether the IBAN is a Paysera account or an
        external bank account is resolved server-side, under the same project rules as
        the split-beneficiaries API (external IBANs require external beneficiaries to
        be enabled for the project; only EEA SEPA IBANs are accepted). Registration
        happens after the request's shape checks pass, so an order rejected by a later
        configuration check may still leave the beneficiary registered.
      properties:
        iban:
          type: string
          description: Recipient's IBAN (Paysera or external).
          example: LT403500010018497892
        name:
          type: string
          description: Display name for the beneficiary.
          minLength: 1
          maxLength: 255
          example: Marketplace Seller 42
    Merchant_Order_API_Purchase:
      required:
      - amount
      - currency
      - reference
      type: object
      properties:
        reference:
          type: string
          description: Unique identifier for the order in the merchant system
          example: ORDER-879-XYZ
        amount:
          type: integer
          format: int64
          description: Order amount in minor currency units (cents). Must be a positive whole number. For example, €149.99 is 14999.
          example: 14999
        currency:
          type: string
          description: Currency code in ISO 4217 format
          example: EUR
      description: Payment purchase information (request)
    Merchant_Order_API_PurchaseResponse:
      required:
      - amount
      - currency
      - reference
      type: object
      properties:
        reference:
          type: string
          description: Unique identifier for the order in the merchant system
          example: ORDER-879-XYZ
        amount:
          type: integer
          format: int64
          description: Order amount in minor currency units (cents). Returned as an integer (Long). For example, €149.99 is returned as 14999.
          example: 14999
        currency:
          type: string
          description: Currency code in ISO 4217 format
          example: EUR
      description: Payment purchase information (response — amount is an integer)
    Merchant_Order_API_RedirectUrls:
      type: object
      properties:
        success_url:
          maxLength: 2048
          minLength: 0
          type: string
          description: URL for redirection after successful payment completion
          example: https://best-merchant.paysera.net/success
        failure_url:
          maxLength: 2048
          minLength: 0
          type: string
          description: URL for redirection when payment fails
          example: https://best-merchant.paysera.net/fail
        callback_url:
          maxLength: 2048
          minLength: 0
          type: string
          description: Backend URL to receive payment updates
          example: https://best-merchant.paysera.net/webhook
        cancel_url:
          maxLength: 2048
          minLength: 0
          type: string
          description: URL for redirection when the payer cancels the payment
          example: https://best-merchant.paysera.net/cancel
      description: Redirect URLs for the order
    Merchant_Order_API_IntegrationCreateOrderResponse:
      required:
      - created_at
      - order_id
      - project_id
      - purchase
      - source
      type: object
      properties:
        project_id:
          type: string
          description: Project identifier associated with the order
          format: uuid
          example: c35593b8-6b65-4cae-9d8e-39af32578ba7
        order_id:
          type: string
          description: Unique order identifier
          format: uuid
        created_at:
          type: integer
          description: Creation date-time in UTC timezone
          format: int64
          example: 1736433270
        merchant_data:
          type: object
          additionalProperties:
            type: string
            description: "\n            Additional data attached to the order in key-value\
              \ format.\n        "
            example: '{"key1":"value1","key2":"value2","key3":"value3"}'
          description: "\n            Additional data attached to the order in key-value\
            \ format.\n        "
          example:
            key1: value1
            key2: value2
            key3: value3
        source:
          type: string
          description: Source indicating where this order originated from
          example: https://myshop.paysera.net
        purchase:
          $ref: '#/components/schemas/Merchant_Order_API_PurchaseResponse'
      description: Response after order creation
    Checkout_Merchant_Project_API_ErrorResponse:
      type: object
      description: |
        Error envelope. `error` is a stable machine code; `error_description` is a
        human-readable message; `error_properties` (when present) maps a field to its
        validation messages.
      properties:
        error:
          type: string
          example: unprocessable_entity
        error_description:
          type: string
          example: Split beneficiaries are not enabled for this project
        error_properties:
          type: object
          nullable: true
          additionalProperties:
            type: array
            items:
              type: string
    Checkout_Merchant_Project_API_CreateSplitBeneficiaryRequest:
      type: object
      required:
      - iban
      - name
      properties:
        iban:
          type: string
          description: |
            Recipient's IBAN. Whether it is a Paysera account or an external bank
            account is resolved server-side and returned as `destination_type`. An
            external IBAN is only accepted when external beneficiaries are enabled
            for the project, and the IBAN must not resolve to the project owner's
            own account.
          example: LT403500010018497892
        name:
          type: string
          description: Display name for the beneficiary.
          minLength: 1
          maxLength: 255
          example: Marketplace Seller 42
    Checkout_Merchant_Project_API_SplitBeneficiaryResponse:
      type: object
      description: A registered split beneficiary. The `id` is the `beneficiary_id` used in order `splits[]`.
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        destination_type:
          type: string
          enum:
          - paysera_account
          - external_iban
          description: Resolved from the submitted IBAN.
          example: paysera_account
        account_number:
          type: string
          description: The resolved Paysera (EVP) account number, or the masked IBAN for an external destination.
          example: EVP5210018145214
        name:
          type: string
          example: Marketplace Seller 42
        created_at:
          type: integer
          format: int64
          description: Creation time as a Unix timestamp (seconds).
          example: 1716200000
    Checkout_Merchant_Project_API_CreateSplitBeneficiaryByPhoneRequest:
      type: object
      required:
      - phone
      properties:
        phone:
          type: string
          description: Phone number of the recipient's Paysera individual account, in international format.
          minLength: 8
          maxLength: 32
          example: '+37060000000'
    Checkout_Merchant_Project_API_SplitBeneficiaryByPhoneResponse:
      type: object
      description: A tip recipient registered by phone. The `id` is the `beneficiary_id` used in order `splits[]`.
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          nullable: true
          description: The recipient's name as known to Paysera.
          example: John D.
        account_number:
          type: string
          nullable: true
          description: |
            The recipient's Paysera (EVP) account. `null` for Lithuanian merchants
            until the recipient gives tax-agent consent, after which their payout
            account is assigned.
          example: null
        created_at:
          type: integer
          format: int64
          description: Creation time as a Unix timestamp (seconds).
          example: 1716200000
    Checkout_Merchant_Project_API_SplitBeneficiaryListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryListItem'
        _metadata:
          $ref: '#/components/schemas/Checkout_Merchant_Project_API_ListMetadata'
    Checkout_Merchant_Project_API_SplitBeneficiaryListItem:
      type: object
      required:
      - id
      - destination_type
      - account_number
      - bic
      - name
      - created_at
      - consent_status
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          description: Beneficiary id. `null` for the merchant's own self-row (cannot be referenced in splits).
          example: 550e8400-e29b-41d4-a716-446655440000
        destination_type:
          type: string
          enum:
          - paysera_account
          - external_iban
          example: paysera_account
        account_number:
          type: string
          nullable: true
          description: |
            The beneficiary's Paysera (EVP) account, or the masked IBAN for an
            external destination; `null` for a self-row with no bank account and for
            tip recipients whose account is not assigned yet.
          example: EVP5210018145214
        bic:
          type: string
          nullable: true
          description: BIC / SWIFT of the beneficiary bank, when provided for an external destination. `null` for paysera-account beneficiaries and the merchant self-row.
          example: null
        name:
          type: string
          example: Marketplace Seller 42
        created_at:
          type: integer
          format: int64
          example: 1716200000
        consent_status:
          type: string
          enum:
          - given
          - not_given
          - null
          nullable: true
          description: |
            Tax-agent consent status. Populated only on Lithuanian payer-tips projects;
            `null` on non-LT or tips-disabled projects, and also `null` within an
            eligible project for the merchant self-row, plain account beneficiaries, and
            tip recipients with no consent record.
    Checkout_Merchant_Project_API_ListMetadata:
      type: object
      properties:
        has_next:
          type: boolean
        has_previous:
          type: boolean
        cursors:
          type: object
          properties:
            after:
              type: string
              nullable: true
            before:
              type: string
              nullable: true
        total:
          type: integer
          nullable: true
          description: Total item count. Always present; `null` unless `include_total=true` was requested.
    Checkout_Merchant_Project_API_ProjectSplitPolicyResponse:
      type: object
      properties:
        project_id:
          type: string
          format: uuid
          example: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
        configured:
          type: boolean
          description: Whether every slot's merchant-owned fields are set. An order with splits fails if `false`.
        slots:
          type: array
          items:
            $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitPolicySlot'
    Checkout_Merchant_Project_API_SplitPolicySlot:
      type: object
      description: One share of the policy. Bind variadic order entries and per-order overrides by `slot_id`.
      properties:
        slot_id:
          type: string
          format: uuid
          example: 22222222-2222-2222-2222-222222222222
        position:
          type: integer
          description: 0-based position of the slot in the policy.
          example: 1
        role:
          type: string
          enum:
          - merchant
          - beneficiary
          - variadic
          example: variadic
        rule_type:
          type: string
          enum:
          - fixed
          - percentage
          - remainder
          nullable: true
          description: Rule kind, or `null` if not yet configured.
        value:
          type: integer
          nullable: true
          description: Cents for `fixed`; basis points for `percentage` (10000 = 100%); `null` for `remainder` or unconfigured.
        beneficiary_id:
          type: string
          format: uuid
          nullable: true
          description: Fixed recipient configured on the slot, if any.
        beneficiary_account_number:
          type: string
          nullable: true
          description: The fixed recipient's EVP account, if any.
        beneficiary_name:
          type: string
          nullable: true
          description: The fixed recipient's display name, if any.
        beneficiary_missing:
          type: boolean
          description: '`true` if a beneficiary slot references a recipient that has been deleted.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for authentication