> ## 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 a specific transaction for a merchant

> Requires the merchant.transaction.view permission.

Retrieves detailed information about a specific transaction for a merchant that belongs to the authenticated organization.

This endpoint returns the full transaction details including ledger entries, which provides comprehensive
information about the transaction's financial impact and settlement status.




## OpenAPI

````yaml /api-spec.yaml get /v1/merchants/{merchantId}/transactions/{transactionId}
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/merchants/{merchantId}/transactions/{transactionId}:
    get:
      tags:
        - Transactions
      summary: Get a specific transaction for a merchant
      description: >
        Requires the merchant.transaction.view permission.


        Retrieves detailed information about a specific transaction for a
        merchant that belongs to the authenticated organization.


        This endpoint returns the full transaction details including ledger
        entries, which provides comprehensive

        information about the transaction's financial impact and settlement
        status.
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
          description: The merchant ID
          example: 123e4567-e89b-12d3-a456-426614174000
        - in: path
          name: transactionId
          required: true
          schema:
            type: string
          description: The transaction ID
          example: tx_123456789
      responses:
        '200':
          description: Transaction retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionWithFullRelationsResponse'
        '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'
        '404':
          description: >-
            Merchant or transaction not found, or merchant does not belong to
            authenticated organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TransactionWithFullRelationsResponse:
      allOf:
        - $ref: '#/components/schemas/TransactionResponse'
        - type: object
          description: >-
            Transaction data with full relations including refunds, ledger
            entries, and settlement items
          properties:
            fee_policy:
              type:
                - object
                - 'null'
              description: Fee policy details
              properties:
                id:
                  type: string
                  description: Fee policy unique identifier
                  example: fp_123456789
                name:
                  type: string
                  description: Fee policy name
                  example: Standard Processing Fee
                description:
                  type:
                    - string
                    - 'null'
                  description: Fee policy description
                  example: Standard processing fee for all transactions
                created_at:
                  type: string
                  format: date-time
                  description: Fee policy creation timestamp
                  example: '2023-01-01T00:00:00.000Z'
                updated_at:
                  type: string
                  format: date-time
                  description: Fee policy last update timestamp
                  example: '2023-01-01T00:00:00.000Z'
            three_d_secure_session:
              anyOf:
                - allOf:
                    - $ref: '#/components/schemas/ThreeDSecureSessionResponse'
                - type: 'null'
              description: >
                The 3DS session linked to this transaction (newest, when more
                than

                one was ever linked), or null when the transaction did not use a

                3DS session. Only returned on single-transaction endpoints; list

                endpoints carry just `three_d_secure_session_id`.
            refunds:
              type: array
              description: Refunds associated with this transaction
              items:
                type: object
                description: Refund details
                properties:
                  id:
                    type: string
                    description: Refund unique identifier
                    example: ref_123456789
                  transaction_id:
                    type: string
                    description: Transaction ID this refund belongs to
                    example: tx_123456789
                  request_id:
                    type: string
                    description: External request ID for idempotency
                    example: req_refund_123
                  amount:
                    type: integer
                    description: Refund amount in cents
                    example: 5000
                  status:
                    type: string
                    enum:
                      - PENDING
                      - PROCESSING
                      - COMPLETED
                      - FAILED
                      - TIMEOUT
                      - CANCELLED
                    description: Refund status
                    example: COMPLETED
                  reason:
                    type: string
                    enum:
                      - BANKING_ERROR
                      - FRAUD
                      - CUSTOMER_REQUEST
                      - PIX_WITHDRAWAL_OR_CHANGE_ERROR
                    description: Reason for the refund
                    example: CUSTOMER_REQUEST
                  description:
                    type:
                      - string
                      - 'null'
                    description: Additional description for the refund
                    example: Customer requested partial refund
                  provider_refund_identification:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Provider-specific identification for the refund (e.g., E2E
                      ID for PIX, ARN for cards)
                    example: D13935893202307271346SPpDyb4f123
                  created_at:
                    type: string
                    format: date-time
                    description: Refund creation timestamp
                    example: '2023-12-01T10:00:00.000Z'
                  updated_at:
                    type: string
                    format: date-time
                    description: Refund last update timestamp
                    example: '2023-12-01T10:00:00.000Z'
            ledger_entries:
              type:
                - array
                - 'null'
              description: Ledger entries associated with this transaction
              items:
                $ref: '#/components/schemas/LedgerEntryResponse'
    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
    NotFoundErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: Company with ID '123' not found
            status:
              type: integer
              example: 404
            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
    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
    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
    ThreeDSecureSessionResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Internal 3DS session ID (use as three_d_secure_session_id when
            creating a transaction)
          example: 550e8400-e29b-41d4-a716-446655440000
        tds_session_id:
          type: string
          description: >-
            Provider session ID (use with the client-side SDK for challenge
            flows)
          example: tds_visa_e7c2yfa3867c
        auth_status:
          type: string
          enum:
            - ACTION_REQUIRED
            - AUTHENTICATED
            - FAILED
          description: >
            Current authentication status:

            - `ACTION_REQUIRED`: Cardholder must complete 3DS challenge

            - `AUTHENTICATED`: Authentication successful (frictionless or
            completed challenge)

            - `FAILED`: Authentication failed
          example: AUTHENTICATED
        consumption_status:
          type: string
          enum:
            - NOT_CONSUMED
            - PROCESSING
            - CONSUMED
          description: |
            Whether this session has been used for a transaction:
            - `NOT_CONSUMED`: Available for use
            - `PROCESSING`: Currently being used (atomic claim)
            - `CONSUMED`: Already used for a transaction
          example: NOT_CONSUMED
        amount:
          type: integer
          description: Amount in minor units (cents)
          example: 10000
        currency:
          type: string
          description: ISO 4217 currency code
          example: BRL
        failure_reason:
          type:
            - string
            - 'null'
          description: >-
            Reason for authentication failure (only present when auth_status is
            FAILED)
          example: null
        liability_shift:
          type:
            - boolean
            - 'null'
          description: Whether liability has shifted to the issuer
          example: true
        authentication_flow:
          type:
            - string
            - 'null'
          description: 3DS authentication flow type (frictionless, challenge, attempt)
          example: frictionless
        expires_at:
          type: string
          format: date-time
          description: Session expiration time
          example: '2026-02-06T20:35:00.000Z'
        created_at:
          type: string
          format: date-time
          example: '2026-02-06T19:35:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-02-06T19:35:00.000Z'
    LedgerEntryResponse:
      type: object
      description: Ledger entry data returned by the API
      properties:
        id:
          type: string
          description: Ledger entry unique identifier
          example: le_123456789
        posting_set_id:
          type: string
          description: Posting set ID this entry belongs to
          example: ps_123456789
        pair_token:
          type: string
          description: Pair token for double-entry bookkeeping
          example: pair_123456789
        event_id:
          type: string
          description: Event ID that triggered this entry
          example: evt_123456789
        owner_type:
          type: string
          enum:
            - COMPANY
            - PLATFORM
            - PROVIDER
          description: Type of owner for this ledger entry
          example: COMPANY
        owner_id:
          type: string
          description: ID of the owner
          example: comp_123456789
        company_id:
          type:
            - string
            - 'null'
          description: Company ID (if owner is a company)
          example: comp_123456789
        organization_id:
          type:
            - string
            - 'null'
          description: Organization ID (if applicable)
          example: org_123456789
        affiliation_id:
          type:
            - string
            - 'null'
          description: Affiliation ID (if applicable)
          example: aff_123456789
        amount:
          type: integer
          description: Entry amount in cents
          example: 10050
        operation:
          type: string
          enum:
            - CREDIT
            - DEBIT
          description: Operation type
          example: CREDIT
        type:
          type: string
          enum:
            - TRANSACTION
            - ORGANIZATION_FEE
            - PLATFORM_COST
            - PROVIDER_COST
            - ORGANIZATION_ANTICIPATION_FEE
            - PLATFORM_ANTICIPATION_COST
            - PLATFORM_REFUND_COST
            - PROVIDER_REFUND_COST
            - TRANSACTION_REFUND
            - TRANSACTION_REFUND_REVERSAL
            - ORGANIZATION_FEE_REFUND
            - PLATFORM_COST_REFUND
            - PROVIDER_COST_REFUND
            - TRANSACTION_DISPUTE
            - TRANSACTION_DISPUTE_REVERSAL
          description: Entry type
          example: TRANSACTION
        currency:
          type: string
          enum:
            - BRL
          description: Currency code
          example: BRL
        payment_date:
          type: string
          format: date
          description: Payment date
          example: '2023-12-01'
        transaction_id:
          type:
            - string
            - 'null'
          description: Associated transaction ID
          example: tx_123456789
        refund_id:
          type:
            - string
            - 'null'
          description: Associated refund ID
          example: ref_123456789
        dispute_id:
          type:
            - string
            - 'null'
          description: Associated dispute ID
          example: dis_123456789
        cashout_id:
          type:
            - string
            - 'null'
          description: Associated cashout ID
          example: co_123456789
        installment:
          type: integer
          description: Installment number
          example: 1
        total_installments:
          type: integer
          description: Total number of installments
          example: 1
        outstanding_amount:
          type: integer
          description: Outstanding amount in cents
          example: 0
        settled:
          type: boolean
          description: Whether the entry is settled
          example: true
        fully_settled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the entry was fully settled
          example: '2023-12-01T10:00:00.000Z'
        last_clearing_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Last clearing timestamp
          example: '2023-12-01T10:00:00.000Z'
        created_at:
          type: string
          format: date-time
          description: Entry creation timestamp
          example: '2023-12-01T10:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Entry last update timestamp
          example: '2023-12-01T10:00:00.000Z'
        settlement_items:
          type: array
          description: Settlement items for this ledger entry
          items:
            $ref: '#/components/schemas/SettlementItemResponse'
      required:
        - id
        - posting_set_id
        - pair_token
        - event_id
        - owner_type
        - owner_id
        - amount
        - operation
        - type
        - currency
        - payment_date
        - installment
        - total_installments
        - outstanding_amount
        - settled
        - created_at
        - updated_at
        - settlement_items
    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
    SettlementItemResponse:
      type: object
      description: Settlement item data returned by the API
      properties:
        id:
          type: string
          description: Settlement item unique identifier
          example: si_123456789
        ledger_entry_id:
          type: string
          description: Associated ledger entry ID
          example: le_123456789
        settled_amount:
          type: integer
          description: Settled amount in cents
          example: 10050
        settlement_date:
          type: string
          format: date
          description: Settlement date
          example: '2023-12-01'
        method:
          type: string
          enum:
            - PIX
            - INTERNAL_TRANSFER
            - BOLETO
            - INVOICE
            - CARD_SETTLEMENT
            - CAPPTA_ORGANIZATION_SPLIT
          description: Settlement method
          example: PIX
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - PROCESSING
            - FAILED
          description: Settlement status
          example: PAID
        affiliation_bank_account_id:
          type:
            - string
            - 'null'
          description: >-
            Affiliation bank account ID (set for PIX/INVOICE/INTERNAL_TRANSFER
            settlements that land on the affiliation's bank account; null
            otherwise, e.g. CARD_SETTLEMENT)
          example: ba_123456789
        settlement_bank_account_id:
          type:
            - string
            - 'null'
          description: >-
            Settlement bank account ID (set on the CREDIT side of
            CARD_SETTLEMENT and CAPPTA_ORGANIZATION_SPLIT items; null on the
            DEBIT side and on settlements that use affiliation_bank_account_id
            instead)
          example: sba_123456789
        operation_id:
          type: string
          description: Operation ID
          example: op_123456789
        created_at:
          type: string
          format: date-time
          description: Item creation timestamp
          example: '2023-12-01T10:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Item last update timestamp
          example: '2023-12-01T10:00:00.000Z'
      required:
        - id
        - ledger_entry_id
        - settled_amount
        - settlement_date
        - method
        - status
        - operation_id
        - created_at
        - updated_at
    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

````