> ## 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.

# Authenticate a transaction with 3D Secure

> Authenticates a transaction that is in AWAITING_3DS status using a 3D Secure session.
Links the authenticated session to the transaction, updates card data with 3DS
authentication details (cryptogram, ECI, authentication_type), and processes
the payment with the provider.
Requires the transaction.create permission.

This endpoint is used in the transaction-first 3DS flow:
1. Transaction is created and enters AWAITING_3DS status
2. Authenticated company creates a 3DS session and completes authentication
3. Authenticated company calls this endpoint to link the session and process the payment

The session must be authenticated, not consumed, not expired, and match the
transaction's company, amount, and currency.




## OpenAPI

````yaml /api-spec.yaml post /v1/transactions/{transactionId}/authenticate
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: Cards
    description: Stored card management (self and merchant)
  - 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
paths:
  /v1/transactions/{transactionId}/authenticate:
    post:
      tags:
        - 3D Secure
        - Transactions
      summary: Authenticate a transaction with 3D Secure
      description: >
        Authenticates a transaction that is in AWAITING_3DS status using a 3D
        Secure session.

        Links the authenticated session to the transaction, updates card data
        with 3DS

        authentication details (cryptogram, ECI, authentication_type), and
        processes

        the payment with the provider.

        Requires the transaction.create permission.


        This endpoint is used in the transaction-first 3DS flow:

        1. Transaction is created and enters AWAITING_3DS status

        2. Authenticated company creates a 3DS session and completes
        authentication

        3. Authenticated company calls this endpoint to link the session and
        process the payment


        The session must be authenticated, not consumed, not expired, and match
        the

        transaction's company, amount, and currency.
      operationId: authenticateSelfTransaction3DS
      parameters:
        - in: path
          name: transactionId
          required: true
          schema:
            type: string
            format: uuid
          description: Transaction ID (must be in AWAITING_3DS status)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - three_d_secure_session_id
              properties:
                three_d_secure_session_id:
                  type: string
                  format: uuid
                  description: >-
                    ID of an authenticated 3D Secure session to link to the
                    transaction
                  example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Transaction authenticated and processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: |
            Validation error. Possible reasons:
            - Transaction is not in AWAITING_3DS status
            - Session is not authenticated
            - Session is missing cryptogram
            - Session has expired
            - Session is already consumed
            - Session belongs to a different company
            - Session amount does not match transaction amount
            - Session currency does not match transaction currency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '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: Transaction not found
          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:
    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
    ValidationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Validation error
            status:
              type: integer
              example: 400
            details:
              type: object
              properties:
                issues:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        example: email
                      type:
                        type: string
                        example: REQUIRED
                      message:
                        type: string
                        example: Field 'email' is required
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: boolean
                        example: invalid_value
                      constraints:
                        type: object
                        example:
                          min: 18
                          max: 120
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    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
    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:
        - last_digits
      properties:
        expiry_month:
          type:
            - string
            - 'null'
          pattern: ^(0[1-9]|1[0-2])$
          description: >-
            Card expiration month in MM format (01-12). Null for transactions
            Rinne did not originate (e.g. POS-originated Cappta webhooks) that
            carry only masked card data with no expiry.
          example: '12'
        expiry_year:
          type:
            - string
            - 'null'
          pattern: ^\d{4}$
          description: >-
            Card expiration year in YYYY format. Null for transactions Rinne did
            not originate (e.g. POS-originated Cappta webhooks).
          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

````