> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Get transactions

> Returns a paginated list of transactions for the authenticated company with optional filters.
Requires the transaction.list permission.




## OpenAPI

````yaml /api-spec.yaml get /v1/transactions
openapi: 3.1.0
info:
  title: Rinne API
  version: 1.0.0
  description: >
    **Rinne API** is a robust payment platform that offers integration with
    multiple payment providers.


    ## Authentication


    The API uses API Key authentication via the `x-api-key` header. Each company
    has a unique key to access resources.


    ## Response Format


    All responses follow a consistent format:

    - **Success**: Returns the requested data directly

    - **Error**: Returns an `error` object with detailed information


    ## Pagination


    Endpoints that return lists support pagination through parameters:

    - `page`: Page number (default: 1)

    - `limit`: Items per page (default: 20, maximum: 100)


    ## Supported Providers


    The API supports multiple payment providers:

    - **Rinne**: Internal provider

    - **Celcoin**: PIX integration and other financial services


    ## Raw Card Data (PCI Endpoints)


    Card credential fields (`card_data.number`, `card_data.cvv`,
    `card_data.network_token`,

    `card_data.cryptogram`, and the 3DS `card.number`) must always be sent
    encrypted —

    values start with the `ev:` prefix. Plaintext values are rejected with

    `400 VALIDATION_ERROR` on every host.


    There are two ways to send encrypted values:

    - **rinne-js**: card forms and wallet buttons (Apple Pay / Google Pay)
    encrypt
      credentials client-side before they leave the browser.
    - **PCI API host**: server-to-server integrations that handle raw card data
    must call
      `https://pci.api.rinne.com.br/core` (sandbox: `https://pci.api-sandbox.rinne.com.br/core`)
      instead of the regular host. This endpoint encrypts `number` and `cvv` in transit
      before the request reaches the API; all other fields pass through unchanged.

    The PCI host serves only transaction creation and 3DS session creation (both
    the

    self and merchant variants); use the regular host for everything else.
  contact:
    name: Rinne API Support
    email: suporte@rinne.com.br
servers:
  - url: https://api-sandbox.rinne.com.br/core
    description: Sandbox
  - url: https://api.rinne.com.br/core
    description: Production
security: []
tags:
  - name: System
    description: System and API health endpoints
  - name: Authentication
    description: User authentication and authorization endpoints
  - name: Management
    description: >-
      Merchant management endpoints - create, list, get specific, overview,
      update
  - name: Transactions
    description: Transaction operations for merchants - create, list, overview, refunds
  - name: Affiliations
    description: Affiliation management for merchants
  - name: Banking
    description: Banking operations for merchants - balance, cashout, statements
  - name: Bank Accounts
    description: Bank account management for merchants
  - name: Pix Keys
    description: PIX key management for merchants
  - name: Company Transactions
    description: Direct transaction management and query endpoints for companies
  - name: Companies
    description: Company management
  - name: Company Affiliations
    description: Payment provider affiliation management
  - name: Company Banking
    description: Company banking endpoints (balance, etc.)
  - name: Company Pix
    description: Company PIX key management
  - name: Company Ledger
    description: Company ledger entry query endpoints
  - name: Ledger
    description: Ledger entry query endpoints (company and merchants)
  - name: Webhooks
    description: Endpoints for receiving webhooks from external providers
  - name: Pricing
    description: Fee and cost policy management for transaction pricing
  - name: Users
    description: User management endpoints
  - name: Roles
    description: Role management endpoints
  - name: Permissions
    description: Permission management endpoints
  - name: Admin
    description: Admin management endpoints
    x-scalar-ignore: true
paths:
  /v1/transactions:
    get:
      tags:
        - Company Transactions
      summary: Get transactions
      description: >
        Returns a paginated list of transactions for the authenticated company
        with optional filters.

        Requires the transaction.list permission.
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of transactions per page
          example: 20
        - in: query
          name: status
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - PROCESSING
                - AUTHORIZED
                - APPROVED
                - REFUNDED
                - PARTIALLY_REFUNDED
                - PENDING_REFUND
                - CHARGEDBACK
                - WAITING_PAYMENT
                - AWAITING_3DS
                - REFUSED
                - FAILED
                - EXPIRED
                - PENDING_CANCELLATION
                - CANCELLED
          description: >-
            Comma-separated list of statuses to filter by (e.g.,
            PROCESSING,APPROVED)
          example: PROCESSING,APPROVED
        - in: query
          name: provider
          schema:
            type: string
            enum:
              - CELCOIN
              - RINNE
              - CAPPTA
          description: >-
            Filter by provider (accepts lowercase and uppercase, returns
            uppercase)
          example: CELCOIN
        - in: query
          name: id
          schema:
            type: string
          description: Filter by transaction ID
          example: tx_123456789
        - in: query
          name: installments
          schema:
            type: integer
            minimum: 1
          description: Filter by number of installments
          example: 12
        - in: query
          name: payment_method
          schema:
            type: string
            enum:
              - CREDIT_CARD
              - DEBIT_CARD
              - PIX
              - BOLEPIX
          description: Filter by payment method
          example: CREDIT_CARD
        - in: query
          name: capture_method
          schema:
            type: string
            enum:
              - EMV
              - MAGSTRIPE
              - ECOMMERCE
              - CONTACTLESS_ICC
          description: Filter by capture method
          example: EMV
        - in: query
          name: affiliation_id
          schema:
            type: string
          description: Filter by affiliation ID
          example: 123e4567-e89b-12d3-a456-426614174002
        - in: query
          name: organization_id
          schema:
            type: string
          description: Filter by organization transaction ID
          example: 123e4567-e89b-12d3-a456-426614174003
        - in: query
          name: provider_transaction_id
          schema:
            type: string
          description: Filter by provider transaction ID
          example: prov_tx_123456
        - in: query
          name: request_id
          schema:
            type: string
          description: Filter by request ID
          example: b941fcaf-d77e-448c-9bdd-e7effd269fb7
        - in: query
          name: amount
          schema:
            type: integer
          description: Filter by transaction amount (in cents)
          example: 10050
        - in: query
          name: amount_from
          schema:
            type: integer
          description: Minimum amount (inclusive) in cents
          example: 5000
        - in: query
          name: amount_to
          schema:
            type: integer
          description: Maximum amount (inclusive) in cents
          example: 20000
        - in: query
          name: created_at_from
          schema:
            type: string
            format: date-time
          description: Start creation datetime (ISO 8601) inclusive
          example: '2025-01-01T00:00:00.000Z'
        - in: query
          name: created_at_to
          schema:
            type: string
            format: date-time
          description: End creation datetime (ISO 8601) inclusive
          example: '2025-01-31T23:59:59.999Z'
        - in: query
          name: sort
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - created_at
                - amount
                - installments
                - '-created_at'
                - '-amount'
                - '-installments'
          description: >-
            Multi-field sort string (e.g., -created_at,amount). Allowed fields:
            created_at, amount, installments
          example: '-created_at,amount'
      responses:
        '200':
          description: Paginated list of transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionResponse'
                  pagination:
                    $ref: '#/components/schemas/PaginationResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
        '403':
          description: Insufficient permissions to access this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TransactionResponse:
      type: object
      description: Transaction data returned by the API
      properties:
        id:
          type: string
          description: Transaction unique identifier
          example: tx_123456789
        provider:
          type: string
          enum:
            - CELCOIN
            - RINNE
            - CAPPTA
          description: Payment provider
          example: CELCOIN
        affiliation_id:
          type: string
          description: Affiliation ID for this transaction
          example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793
        request_id:
          type: string
          description: Unique request ID for this transaction used for idempotency
          example: request-123
        mcc:
          type: string
          description: Merchant Category Code
          example: '5411'
        amount:
          type: integer
          description: Transaction amount in cents
          example: 10050
        currency:
          type: string
          enum:
            - BRL
          description: Transaction currency
          example: BRL
        pricing:
          $ref: '#/components/schemas/TransactionPricing'
          description: Transaction pricing information
        fee_policy_id:
          type:
            - string
            - 'null'
          description: Fee policy ID applied to this transaction
          example: fee_policy_123
        cost_policy_id:
          type:
            - string
            - 'null'
          description: Cost policy ID applied to this transaction
          example: cost_policy_123
        approved_amount:
          type:
            - integer
            - 'null'
          description: Approved amount in cents
          example: 10050
        refunded_amount:
          type:
            - integer
            - 'null'
          description: Total amount refunded in cents (sum of completed refunds)
          example: 0
        three_d_secure_session_id:
          type:
            - string
            - 'null'
          format: uuid
          description: |
            ID of the 3DS session linked to this transaction, if any.
            Set when the transaction was created with a 3DS session
            (session-first flow) or authenticated via the
            /authenticate endpoint (transaction-first flow).
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          enum:
            - PROCESSING
            - AUTHORIZED
            - APPROVED
            - REFUNDED
            - PARTIALLY_REFUNDED
            - PENDING_REFUND
            - CHARGEDBACK
            - WAITING_PAYMENT
            - AWAITING_3DS
            - REFUSED
            - FAILED
            - EXPIRED
            - PENDING_CANCELLATION
            - CANCELLED
          description: Transaction status
          example: APPROVED
        acquirer_response_code:
          type:
            - string
            - 'null'
          description: Acquirer response code
          example: '00'
        capture_method:
          type: string
          enum:
            - EMV
            - MAGSTRIPE
            - ECOMMERCE
            - CONTACTLESS_ICC
          description: Transaction capture method
          example: EMV
        installments:
          type:
            - integer
            - 'null'
          description: Number of installments
          example: 1
        payment_method:
          type: string
          enum:
            - CREDIT_CARD
            - DEBIT_CARD
            - PIX
            - BOLEPIX
          description: Payment method
          example: PIX
        pix_data:
          anyOf:
            - $ref: '#/components/schemas/PixDataResponse'
            - type: 'null'
          description: PIX-specific data (present if payment_method is PIX)
        bolepix_data:
          anyOf:
            - $ref: '#/components/schemas/BolepixDataResponse'
            - type: 'null'
          description: Bolepix-specific data (present if payment_method is BOLEPIX)
        card_data:
          anyOf:
            - $ref: '#/components/schemas/CardDataResponse'
            - type: 'null'
          description: >-
            Card-specific data (present if payment_method is CREDIT_CARD or
            DEBIT_CARD)
        soft_descriptor:
          type:
            - string
            - 'null'
          description: Soft descriptor shown on cardholder statement
          example: MYSTORE
        serial_number:
          type:
            - string
            - 'null'
          description: Terminal serial number
          example: '12345678'
        nsu:
          type:
            - string
            - 'null'
          description: Network Sequential Number
          example: '000123'
        metadata:
          type:
            - object
            - 'null'
          nullable: true
          description: Additional metadata
          additionalProperties: true
        latest_refund_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Latest refund timestamp (for the most recent completed refund)
          example: '2023-12-01T10:00:00.000Z'
        status_reason:
          type:
            - string
            - 'null'
          enum:
            - PROVIDER
            - ACQUIRER
            - ANTIFRAUD
            - INTERNAL_ERROR
            - NO_ACQUIRER
            - ACQUIRER_TIMEOUT
            - CHALLENGE_NOT_ALLOWED
            - REVERSED
          description: >-
            Status reason details. REVERSED indicates a failed card transaction
            whose charge was later found at the acquirer and reversed by
            reconciliation.
          example: PROVIDER
        approved_at:
          type:
            - string
            - 'null'
          description: Transaction approval timestamp
          example: '2023-12-01T10:00:00.000Z'
        automatic_anticipation:
          type: boolean
          description: >
            Whether this transaction was automatically anticipated at creation
            time. Set to true when the affiliation's anticipation_type is
            AUTOMATIC; false otherwise.
          example: false
        company_id:
          type: string
          description: Company ID that owns this transaction
          example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793
        company_full_name:
          type: string
          description: Company full name
          example: Test Company
        company_name:
          type:
            - string
            - 'null'
          description: Company name
          example: Test Company
        organization_id:
          type:
            - string
            - 'null'
          description: Organization transaction ID (for refunds/chargebacks)
          example: tx_organization_123456
        consumer:
          anyOf:
            - $ref: '#/components/schemas/ConsumerResponse'
            - type: 'null'
          description: Consumer information
        created_at:
          type: string
          format: date-time
          description: Transaction creation timestamp
          example: '2023-12-01T10:00:00.000Z'
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Transaction last update timestamp
          example: '2023-12-01T10:00:00.000Z'
      required:
        - id
        - provider
        - affiliation_id
        - request_id
        - mcc
        - amount
        - currency
        - pricing
        - status
        - capture_method
        - installments
        - payment_method
        - automatic_anticipation
        - company_id
        - created_at
    PaginationResponse:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
        - hasNext
        - hasPrev
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 50
        totalPages:
          type: integer
          example: 3
        hasNext:
          type: boolean
          example: true
        hasPrev:
          type: boolean
          example: false
    AuthenticationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: AUTHENTICATION_ERROR
            message:
              type: string
              example: Authentication required to access this resource
            status:
              type: integer
              example: 401
            details:
              type: object
              properties:
                reason:
                  type: string
                  example: Invalid API key
            path:
              type: string
              example: /companies/me
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    AuthorizationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: AUTHORIZATION_ERROR
            message:
              type: string
              example: You need 'admin' permissions to access this resource
            status:
              type: integer
              example: 403
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    InternalServerErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: INTERNAL_SERVER_ERROR
            message:
              type: string
              example: An unexpected error occurred
            status:
              type: integer
              example: 500
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    TransactionPricing:
      type: object
      description: Transaction pricing information with fee and cost structures
      properties:
        fee:
          $ref: '#/components/schemas/PricingValue'
          description: Fee pricing structure
        cost:
          $ref: '#/components/schemas/PricingValue'
          description: Cost pricing structure
      required:
        - fee
        - cost
    PixDataResponse:
      type: object
      description: PIX-specific data for transactions
      properties:
        pix_key_id:
          type:
            - string
            - 'null'
          description: PIX key ID
          example: pix_key_123
        description:
          type:
            - string
            - 'null'
          description: PIX description
          example: 'Payment for order #123'
        qr_code:
          type:
            - string
            - 'null'
          description: PIX QR code
          example: >-
            00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Test
            Company6008São Paulo62070503***6304E2CA
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: PIX expiration timestamp
          example: '2023-12-02T10:00:00.000Z'
        identification:
          type:
            - string
            - 'null'
          description: PIX identification
          example: order_123
        expiration_in_seconds:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 86400
          description: Expiration time in seconds (1-86400)
          example: 86400
        end_to_end_id:
          type:
            - string
            - 'null'
          description: PIX end-to-end ID
          example: E12345678202312101234567890123456
        due_date:
          type:
            - string
            - 'null'
          format: date
          description: >
            Due date for the PIX payment in YYYY-MM-DD format. Mandatory when
            using interest, fine, discount, and/or abatement.


            **Important:** For validation purposes, dates are always interpreted
            in Brazil timezone by default (America/Sao_Paulo, UTC-3).
          example: '2025-12-31'
        expiration_in_days_after_due_date:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 365
          description: >-
            Number of days after the due date before the PIX payment expires.
            Required when `due_date` is provided. Must not be provided
            otherwise.
          example: 30
          default: 30
        interest:
          anyOf:
            - allOf:
                - $ref: '#/components/schemas/InterestConfig'
            - type: 'null'
          description: Interest configuration (if applicable)
        fine:
          anyOf:
            - allOf:
                - $ref: '#/components/schemas/FineConfig'
            - type: 'null'
          description: Fine configuration (if applicable)
        discount:
          anyOf:
            - allOf:
                - $ref: '#/components/schemas/DiscountDatesConfigItemResponse'
            - type: 'null'
          description: Discount configuration (if applicable)
        abatement:
          anyOf:
            - allOf:
                - $ref: '#/components/schemas/AbatementConfig'
            - type: 'null'
          description: Abatement configuration (if applicable)
    BolepixDataResponse:
      type: object
      description: Bolepix-specific data for transactions
      required:
        - pix_key_id
        - external_request_id
        - due_date
      properties:
        pix_key_id:
          type: string
          description: PIX key ID used for this transaction
          example: pix_key_123
        external_request_id:
          type: string
          description: External request ID used with the provider
          example: ext-req-123
        due_date:
          type: string
          format: date
          description: Due date in YYYY-MM-DD format
          example: '2025-12-31'
        expiration_in_days_after_due_date:
          type:
            - integer
            - 'null'
          description: Days after due date before expiration
          example: 30
        boleto_transaction_id:
          type:
            - string
            - 'null'
          description: Provider's boleto transaction ID
          example: boleto-123
        bank_issuer:
          type:
            - string
            - 'null'
          description: Issuing bank name
          example: Banco do Brasil
        bank_code:
          type:
            - string
            - 'null'
          description: Issuing bank code
          example: '001'
        bank_branch:
          type:
            - string
            - 'null'
          description: Bank branch number
          example: '1234'
        bank_account_number:
          type:
            - string
            - 'null'
          description: Bank account number
          example: 12345-6
        bar_code:
          type:
            - string
            - 'null'
          description: Boleto bar code
          example: '00190000090299993600000000000000185830000010000'
        bank_line:
          type:
            - string
            - 'null'
          description: Boleto bank line (typed representation of bar code)
          example: 00190.00009 02999.936001 00000.000001 8 58300000010000
        bank_assignor:
          type:
            - string
            - 'null'
          description: Assignor name
          example: Company Name
        pix_transaction_id:
          type:
            - string
            - 'null'
          description: Provider's PIX transaction ID
          example: pix-123
        pix_identification:
          type:
            - string
            - 'null'
          description: PIX identification (txid)
          example: txid123456789
        pix_emv:
          type:
            - string
            - 'null'
          description: PIX EMV QR code payload
          example: 00020126580014br.gov.bcb.pix...
        paid_via:
          type:
            - string
            - 'null'
          enum:
            - PIX
            - BOLETO
          description: How the payment was made (PIX or BOLETO)
          example: PIX
        paid_amount:
          type:
            - integer
            - 'null'
          description: Amount actually paid in cents
          example: 50000
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Payment timestamp
          example: '2025-12-20T10:00:00.000Z'
        discount:
          type:
            - object
            - 'null'
          description: Discount configuration
          properties:
            amount:
              type:
                - integer
                - 'null'
              description: Discount amount in cents
              example: 5000
            percentage:
              type:
                - number
                - 'null'
              description: Discount percentage
              example: 10
            modality:
              type: string
              enum:
                - FIXED
                - PERCENTAGE
              description: Discount modality
              example: FIXED
            until_date:
              type:
                - string
                - 'null'
              format: date
              description: Date until which discount applies
              example: '2025-12-25'
        fine_percentage:
          type:
            - number
            - 'null'
          description: Fine percentage applied after due date
          example: 2
        monthly_interest_percentage:
          type:
            - number
            - 'null'
          description: >-
            Monthly interest percentage (divided by 30 and applied per day after
            due date)
          example: 1
    CardDataResponse:
      type: object
      description: >-
        Card data included in transaction responses. Only non-sensitive fields
        are returned.
      required:
        - expiry_month
        - expiry_year
        - last_digits
      properties:
        expiry_month:
          type: string
          pattern: ^(0[1-9]|1[0-2])$
          description: Card expiration month in MM format (01-12).
          example: '12'
        expiry_year:
          type: string
          pattern: ^\d{4}$
          description: Card expiration year in YYYY format.
          example: '2028'
        brand:
          type:
            - string
            - 'null'
          description: Card brand (e.g., VISA, MASTERCARD, ELO, AMEX).
          example: VISA
        device_id:
          type:
            - string
            - 'null'
          description: Device identifier associated with the card token, if available.
          example: device-123
        last_digits:
          type: string
          pattern: ^\d{4}$
          description: Last 4 digits of the card number.
          example: '1111'
        cardholder_name:
          type:
            - string
            - 'null'
          description: Name of the cardholder as it appears on the card.
          example: John Doe
        country:
          type:
            - string
            - 'null'
          description: Issuing country of the card (ISO 3166-1 alpha-2).
          example: BR
        wallet_type:
          type:
            - string
            - 'null'
          enum:
            - APPLE_PAY
            - GOOGLE_PAY
          description: Digital wallet type used for the payment, if applicable.
          example: APPLE_PAY
        display_name:
          type:
            - string
            - 'null'
          description: Human-readable display name for the card.
          example: Visa •••• 1111
        authentication_type:
          type:
            - string
            - 'null'
          enum:
            - 3DS
          description: Authentication type used for the card transaction, if any.
          example: 3DS
    ConsumerResponse:
      type: object
      description: Consumer information
      properties:
        full_name:
          type:
            - string
            - 'null'
          example: João Silva
        email:
          type:
            - string
            - 'null'
          format: email
          example: joao@email.com
        pix_key:
          type:
            - string
            - 'null'
          example: joao@email.com
        document_type:
          type: string
          enum:
            - CPF
            - CNPJ
          description: Consumer document type
          example: CPF
        document_number:
          type:
            - string
            - 'null'
          example: '81146431023'
        phone:
          type:
            - string
            - 'null'
          example: '+5511999999999'
        birth_date:
          type:
            - string
            - 'null'
          example: 15-08-1990
        address:
          anyOf:
            - $ref: '#/components/schemas/AddressResponse'
            - type: 'null'
          description: Consumer address
      required:
        - document_type
    PricingValue:
      type: object
      description: >-
        Pricing structure with percentage, flat fee, and minimum price. At least
        one pricing component must be provided.
      anyOf:
        - required:
            - percentage
        - required:
            - flat
        - required:
            - minimum_price
      properties:
        percentage:
          type:
            - number
            - 'null'
          format: float
          minimum: 0
          description: Percentage fee (e.g., 2.5 for 2.5%)
          example: 2.5
        flat:
          type:
            - number
            - 'null'
          format: float
          minimum: 0
          description: Flat fee in cents
          example: 50
        minimum_price:
          type:
            - number
            - 'null'
          format: float
          minimum: 0
          description: Minimum fee in cents
          example: 100
    InterestConfig:
      type: object
      description: |
        Interest configuration for PIX payments with due date.
        Interest is applied when payment is made after the due date.
        Exactly one of amount or percentage must be provided.
      required:
        - modality
      properties:
        amount:
          type: integer
          minimum: 1
          description: >
            Interest amount in cents (positive integer).

            Required for amount-based modalities (AMOUNT_PER_DAY,
            AMOUNT_PER_WORKING_DAY).

            Must not be provided for percentage-based modalities.
          example: 1000
        percentage:
          type: number
          minimum: 0
          maximum: 100
          multipleOf: 0.01
          description: >
            Interest percentage (0-100, up to 2 decimal places).

            Required for percentage-based modalities (PERCENTAGE_PER_DAY,
            PERCENTAGE_PER_MONTH, etc.).

            Must not be provided for amount-based modalities.
          example: 10.5
        modality:
          type: string
          enum:
            - AMOUNT_PER_DAY
            - PERCENTAGE_PER_DAY
            - PERCENTAGE_PER_MONTH
            - PERCENTAGE_PER_YEAR
            - AMOUNT_PER_WORKING_DAY
            - PERCENTAGE_PER_WORKING_DAY
            - PERCENTAGE_PER_WORKING_MONTH
            - PERCENTAGE_PER_WORKING_YEAR
          description: |
            Interest calculation modality:
            - AMOUNT_PER_DAY: Fixed amount per day
            - PERCENTAGE_PER_DAY: Percentage per day
            - PERCENTAGE_PER_MONTH: Percentage per month
            - PERCENTAGE_PER_YEAR: Percentage per year
            - AMOUNT_PER_WORKING_DAY: Fixed amount per working day
            - PERCENTAGE_PER_WORKING_DAY: Percentage per working day
            - PERCENTAGE_PER_WORKING_MONTH: Percentage per working month
            - PERCENTAGE_PER_WORKING_YEAR: Percentage per working year
          example: PERCENTAGE_PER_MONTH
    FineConfig:
      type: object
      description: |
        Fine configuration for PIX payments with due date.
        Fine is applied when payment is made after the due date.
        Exactly one of amount or percentage must be provided.
      required:
        - modality
      properties:
        amount:
          type: integer
          minimum: 1
          description: |
            Fine amount in cents (positive integer).
            Required for FIXED modality.
            Must not be provided for PERCENTAGE modality.
          example: 2000
        percentage:
          type: number
          minimum: 0
          maximum: 100
          multipleOf: 0.01
          description: |
            Fine percentage (0-100, up to 2 decimal places).
            Required for PERCENTAGE modality.
            Must not be provided for FIXED modality.
          example: 2.5
        modality:
          type: string
          enum:
            - FIXED
            - PERCENTAGE
          description: |
            Fine calculation modality:
            - FIXED: Fixed amount fine
            - PERCENTAGE: Percentage-based fine
          example: PERCENTAGE
    DiscountDatesConfigItemResponse:
      type: object
      description: |
        Discount configuration response for PIX payments with due date.
        This is the response format for discount configuration.
      required:
        - modality
      properties:
        modality:
          type: string
          enum:
            - FIXED_AMOUNT_UNTIL_DATE
            - PERCENTAGE_UNTIL_DATE
            - AMOUNT_PER_DAY
            - AMOUNT_PER_WORKING_DAY
            - PERCENTAGE_PER_DAY
            - PERCENTAGE_PER_WORKING_DAY
          description: |
            Discount calculation modality:
            - FIXED_AMOUNT_UNTIL_DATE: Fixed discount amount until specific date
            - PERCENTAGE_UNTIL_DATE: Percentage discount until specific date
            - AMOUNT_PER_DAY: Amount discount per day
            - AMOUNT_PER_WORKING_DAY: Amount discount per working day
            - PERCENTAGE_PER_DAY: Percentage discount per day
            - PERCENTAGE_PER_WORKING_DAY: Percentage discount per working day
          example: PERCENTAGE_UNTIL_DATE
        amount:
          type:
            - integer
            - 'null'
          minimum: 1
          description: |
            Discount amount in cents (positive integer).
            Required for AMOUNT_PER_DAY and AMOUNT_PER_WORKING_DAY modalities.
            Null for other modalities or when discount_dates_config is used.
        percentage:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 100
          multipleOf: 0.01
          description: >
            Discount percentage (0-100, up to 2 decimal places).

            Required for PERCENTAGE_PER_DAY and PERCENTAGE_PER_WORKING_DAY
            modalities.

            Null for other modalities or when discount_dates_config is used.
          example: 50
        discount_dates_config:
          type:
            - array
            - 'null'
          description: >
            Array of discount date configurations.

            Required for FIXED_AMOUNT_UNTIL_DATE and PERCENTAGE_UNTIL_DATE
            modalities.
          items:
            type: object
            required:
              - until_date
            properties:
              until_date:
                type: string
                format: date
                description: >
                  Date until which this discount applies (YYYY-MM-DD).


                  **Important:** For validation purposes, dates are always
                  interpreted in Brazil timezone by default (America/Sao_Paulo,
                  UTC-3).
                example: '2025-12-15'
              amount:
                type:
                  - integer
                  - 'null'
                minimum: 1
                description: |
                  Discount amount in cents (positive integer).
                  Required for FIXED_AMOUNT_UNTIL_DATE modality.
                  Null for PERCENTAGE_UNTIL_DATE modality.
                example: 10000
              percentage:
                type:
                  - number
                  - 'null'
                minimum: 0
                maximum: 100
                multipleOf: 0.01
                description: |
                  Discount percentage (0-100, up to 2 decimal places).
                  Required for PERCENTAGE_UNTIL_DATE modality.
                  Null for FIXED_AMOUNT_UNTIL_DATE modality.
                example: 10
          example:
            - until_date: '2025-12-15'
              percentage: 10
            - until_date: '2025-12-20'
              percentage: 5
    AbatementConfig:
      type: object
      description: |
        Abatement configuration for PIX payments with due date.
        Abatement reduces the total amount to be paid.
        Exactly one of amount or percentage must be provided.
      required:
        - modality
      properties:
        amount:
          type: integer
          minimum: 1
          description: |
            Abatement amount in cents (positive integer).
            Required for FIXED modality.
            Must not be provided for PERCENTAGE modality.
          example: 5000
        percentage:
          type: number
          minimum: 0
          maximum: 100
          multipleOf: 0.01
          description: |
            Abatement percentage (0-100, up to 2 decimal places).
            Required for PERCENTAGE modality.
            Must not be provided for FIXED modality.
          example: 5
        modality:
          type: string
          enum:
            - FIXED
            - PERCENTAGE
          description: |
            Abatement calculation modality:
            - FIXED: Fixed amount abatement
            - PERCENTAGE: Percentage-based abatement
          example: FIXED
    AddressResponse:
      type: object
      description: Address information
      properties:
        street:
          type: string
          description: Street name
          example: Rua das Flores
        street_number:
          type:
            - string
            - 'null'
          description: Street number
          example: '123'
        complement:
          type:
            - string
            - 'null'
          description: Address complement
          example: Apt 101
        neighborhood:
          type: string
          description: Neighborhood
          example: Centro
        zipcode:
          type: string
          description: ZIP code
          example: '12345678'
        country:
          type: string
          description: Country code
          example: '076'
        state:
          type: string
          description: State
          example: SP
        city:
          type: string
          description: City
          example: São Paulo
      required:
        - street
        - neighborhood
        - zipcode
        - country
        - state
        - city
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Company API key for authentication

````