Debitura Payments API

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.
  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'
      operationId: getPayments
      x-operation-id-source: derived
  /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'
      operationId: getPaymentsById
      x-operation-id-source: derived
components:
  schemas:
    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.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.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
    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.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.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.
  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