openapi: 3.2.0
info:
  title: Debitura Customer Payments API
  description: 'Welcome to the Debitura Customer API, your gateway to seamlessly integrating your debt collection workflow with our platform. Debitura connects customers with trusted debt collection firms specializing in pre-legal debt recovery. With this API, you can easily upload cases, track their status, and manage your debt collection process efficiently. For any support or inquiries, please reach out to us at contact@debitura.com. To setup an API key, log into your Debitura account and go here: https://app.debitura.com/CreditorApiKey


    📖 Full documentation, guides, and integration walkthroughs: https://docs.debitura.com/clients


    NOTE: if you''re representing a platform and want to provide this feature for your customers, you need a different API. Please contact us.'
  contact:
    name: Debitura Support
    url: https://www.debitura.com/integration/debt-collection-api
    email: contact@debitura.com
  version: v1
servers:
- url: https://customer-api.debitura.com
  description: Production
security:
- ApiKey: []
- Bearer: []
tags:
- name: Payments
  description: Payments
paths:
  /Payments:
    get:
      tags:
      - Payments
      summary: List payments
      description: 'Returns a paginated list of all payments recorded on your account across all cases.


        **Pagination:**

        - Page (default: 1) - Page number, starting from 1

        - PageSize (default: 10, max: 100) - Number of results per page


        **Response:**

        - Returns PaymentListApiDTO with page metadata and payments array

        - Each payment includes case reference, amount, currency, date, payment type, and status

        - Page metadata includes: totalResults, currentPage, skipped, pageSize


        **Note:** This endpoint returns ALL payments across all your cases. To get payments for a specific case, use GET /cases/{id}/payments instead.'
      parameters:
      - name: Page
        in: query
        schema:
          type: integer
          format: int32
          default: 1
      - name: PageSize
        in: query
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Payments returned
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalCustomerAPI.Models.Payments.Dtos.PaymentListApiDTO'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalCustomerAPI.Models.Payments.Dtos.PaymentListApiDTO'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalCustomerAPI.Models.Payments.Dtos.PaymentListApiDTO'
        '400':
          description: Invalid pagination parameters
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
  /Payments/{id}:
    get:
      tags:
      - Payments
      summary: Fetch payment by ID
      description: Returns payment details for the supplied payment ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Payment found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto'
        '400':
          description: ID missing or empty
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '404':
          description: Payment not found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
components:
  schemas:
    Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto:
      required:
      - currency
      - invoice
      - method
      - recipient
      type: object
      properties:
        id:
          type: string
          format: uuid
        dateCreated:
          type: string
          format: date-time
        dateUpdated:
          type:
          - string
          - 'null'
          format: date-time
        date:
          type: string
          format: date-time
        grossAmount:
          type: number
          format: double
        recipient:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
        currency:
          type:
          - string
          - 'null'
        invoice:
          $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentRelatedInvoiceDto'
      additionalProperties: false
    Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
        message:
          type:
          - string
          - 'null'
          description: A human-readable description of the error.
        solutionUrl:
          type:
          - string
          - 'null'
          description: "A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).\n            \n\nPartners who want a <b>single URL</b> that walks the user through every pending\nsigning in one chain — instead of forwarding one URL per\n`BusinessErrorApiDTO` — should use\nDebitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO.SigningHandoff's `CombinedSigningUrl`.\nThe two are complementary: `SolutionUrl` is granular per-error;\n`CombinedSigningUrl` is the chain-walking alternative for signing-related errors."
      additionalProperties: false
      description: Represents a business error in the API response.
    Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto:
      type: object
      properties:
        error:
          type:
          - string
          - 'null'
          description: Short human-readable error label (legacy field — preserved for backward compatibility).
        message:
          type:
          - string
          - 'null'
          description: Human-readable error description (legacy field — preserved for backward compatibility).
        businessErrors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO'
          description: Canonical structured error array. Consumers should migrate to reading this field.
      additionalProperties: false
      description: "Generic structured error response for API endpoints.\n            \nDual-write design: existing fields (Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.Error / Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.Message etc.)\nare preserved for backward compatibility alongside the canonical\nDebitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.BusinessErrors array, allowing consumers to migrate at their own pace."
    Debitura.Domain.Model.Base.PageData:
      type: object
      properties:
        totalResults:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        currentPage:
          type: integer
          format: int32
        responseCount:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
          readOnly: true
      additionalProperties: false
    Debitura.Web.ExternalCustomerAPI.Models.Payments.Dtos.PaymentListApiDTO:
      required:
      - page
      type: object
      properties:
        page:
          $ref: '#/components/schemas/Debitura.Domain.Model.Base.PageData'
        payments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto'
      additionalProperties: false
    Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentRelatedInvoiceDto:
      required:
      - reference
      - status
      type: object
      properties:
        status:
          type:
          - string
          - 'null'
        reference:
          type:
          - string
          - 'null'
        invoiceId:
          type: string
          format: uuid
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      description: This is for clients who manage their own account. They can get the API key in the platform and set it as the 'XApiKey' in the header.
      name: XApiKey
      in: header
    Bearer:
      type: http
      description: This is for referral partners, who are sending in clients to the platform. They get the bearer token from the referral partner Api and can be inserted here.
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Debitura developer documentation
  url: https://docs.debitura.com