openapi: 3.0.3
info:
  title: Tratta Bulk Operations Charges 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: Charges
  description: Charge processing and management
paths:
  /charges:
    get:
      operationId: listCharges
      summary: List Charges
      description: Returns a paginated list of charges.
      tags:
      - Charges
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successful response with charge list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeListResponse'
    post:
      operationId: createCharge
      summary: Create Charge
      description: Creates a new charge against a payment method or debt account.
      tags:
      - Charges
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeRequest'
      responses:
        '201':
          description: Charge created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /charges/{id}:
    get:
      operationId: getCharge
      summary: Get Charge
      description: Returns a single charge by ID.
      tags:
      - Charges
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Charge:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
          format: float
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
          - refunded
        payment_method_id:
          type: string
        debt_account_id:
          type: string
        created_at:
          type: string
          format: date-time
    ChargeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Charge'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        errorCode:
          type: string
          description: Optional error code
    ChargeListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    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
    ChargeRequest:
      type: object
      required:
      - amount
      properties:
        amount:
          type: number
          format: float
        payment_method_id:
          type: string
        debt_account_id:
          type: string
        description:
          type: string
  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'
    UnprocessableEntity:
      description: Unprocessable entity - missing parameters or invalid data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token provided by Tratta after organization setup