openapi: 3.0.3
info:
  title: Tratta Bulk Operations Transactions API
  description: The Tratta REST API enables programmatic integration with Tratta's debt collection and payment experience platform. Manage debt accounts, payment plans, transactions, customers, charges, and webhooks for collections workflows. Supports both sandbox and production environments.
  version: v1.0.0
  contact:
    name: Tratta Support
    url: https://docs.tratta.io/
  x-logo:
    url: https://www.tratta.io/logo.png
servers:
- url: https://{org-uuid}.production.tratta.io/api/v1
  description: Tratta Production Server
  variables:
    org-uuid:
      description: Your organization UUID provided by Tratta
      default: your-org-uuid
- url: https://{org-uuid}.sandbox.tratta.io/api/v1
  description: Tratta Sandbox Server
  variables:
    org-uuid:
      description: Your organization UUID provided by Tratta
      default: your-org-uuid
security:
- BearerAuth: []
tags:
- name: Transactions
  description: Transaction history and reporting
paths:
  /transactions:
    get:
      operationId: listTransactions
      summary: List Transactions
      description: Returns a paginated list of payment transactions.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/IncludeParam'
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter transactions from this date
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter transactions to this date
      responses:
        '200':
          description: Successful response with transaction list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
  /transactions/{id}:
    get:
      operationId: getTransaction
      summary: Get Transaction
      description: Returns a single transaction by ID.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    TransactionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        errorCode:
          type: string
          description: Optional error code
    PaginationLinks:
      type: object
      properties:
        first:
          type: string
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
        last:
          type: string
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        current_page:
          type: integer
        per_page:
          type: integer
        total_pages:
          type: integer
    Transaction:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
          format: float
        type:
          type: string
          enum:
          - payment
          - refund
          - reversal
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
        payment_source:
          type: string
        charge_id:
          type: string
        payment_plan_id:
          type: string
        created_at:
          type: string
          format: date-time
    TransactionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Transaction'
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
      description: Page number for pagination
    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
      description: Number of records per page (1-500)
    IncludeParam:
      name: include
      in: query
      required: false
      schema:
        type: string
      description: Comma-delimited list of related resources to include in response (e.g., customers,payment_methods)
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource unique identifier
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token provided by Tratta after organization setup