openapi: 3.1.0
info:
  contact:
    name: Lerian Studio
    url: https://lerian.studio
  description: Public API for Pix BR Codes and immediate and due-date collections.
  license:
    name: Lerian Studio General License
  title: Pix Lerian — Collections
  version: 1.1.0
servers:
  - url: https://api.example.com/cob-hub/v1
    description: Replace the example host with the URL provided during environment onboarding.
security:
  - BearerAuth: []
tags:
  - description: Create, retrieve, list, and decode static Pix BR Codes.
    name: BR Codes
  - description: Create, retrieve, list, and cancel due-date Pix collections.
    name: Due-Date Collections
  - description: Create, retrieve, list, and cancel immediate Pix collections.
    name: Immediate Collections
paths:
  /brcodes/decode:
    post:
      description: 'Parses a Pix EMV payload and returns the structured payment details. Third-party payloads are accepted, so decoding is more permissive than BR Code creation: a payload without a Point of Initiation method is decoded as `STATIC`. `keyType` is inferred from the key value and omitted when no key type defined by the BCB both matches the value and passes validation. See the response schema for the rules that apply to each field.'
      operationId: decodeQRCode
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/decode-qrcode
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecodeQRCodeBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecodeQRCodeOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0221
                title: Bad Request
                status: 400
                detail: QR code could not be parsed.
                code: PIX-0221
              schema:
                $ref: '#/components/schemas/Detail'
          description: Missing or malformed request data, or an EMV payload that cannot be decoded as a valid Pix QR Code (PIX-0002, PIX-0003, PIX-0010, PIX-0200, PIX-0221).
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected server error (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Decode a Pix EMV payload
      tags:
        - BR Codes
  /brcodes/static:
    get:
      description: Returns a page-based list of static BR Codes with optional key/status filters.
      operationId: listStaticBRCodes
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/list-static-brcodes
      parameters:
        - description: Page number (1-based, default 1)
          explode: false
          in: query
          name: page
          schema:
            description: Page number (1-based, default 1)
            examples:
              - '1'
            type: string
        - description: Rows per page (default 20, max 100)
          explode: false
          in: query
          name: limit
          schema:
            description: Rows per page (default 20, max 100)
            examples:
              - '20'
            type: string
        - description: Filter by Pix key value (exact match)
          explode: false
          in: query
          name: key_value
          schema:
            description: Filter by Pix key value (exact match)
            type: string
        - description: Filter by status (ACTIVE, CANCELLED)
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status (ACTIVE, CANCELLED)
            examples:
              - ACTIVE
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListStaticBRCodesOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0206
                title: Bad Request
                status: 400
                detail: Invalid filter parameter value.
                code: PIX-0206
              schema:
                $ref: '#/components/schemas/Detail'
          description: Invalid filter input, including an unrecognized lifecycle status (PIX-0206).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure listing BR Codes (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: List static BR Codes
      tags:
        - BR Codes
    post:
      description: Creates a reusable static Pix BR Code and returns its EMV payload. The requested Pix key must belong to the account identified by `X-Account-Id` and is validated before the code is generated.
      operationId: createStaticBRCode
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/create-static-brcode
      parameters:
        - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412.
          in: header
          name: X-Idempotency
          required: true
          schema:
            maxLength: 64
            minLength: 1
            type: string
        - description: Merchant account UUID (scopes DICT key ownership validation)
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Merchant account UUID (scopes DICT key ownership validation)
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStaticBRCodeBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateStaticBRCodeOutput'
          description: Created
        '400':
          content:
            application/json:
              example:
                code: PIX-0030
                title: Idempotency Key Required
                message: The X-Idempotency header is required for this operation and must be within the accepted length.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Missing or malformed headers/body fields, an invalid Pix key shape, or another invalid create input (PIX-0001-0003, PIX-0017, PIX-0200). X-Idempotency absent or longer than 64 bytes (PIX-0030) uses the legacy {code,title,message} envelope; other 400 errors use application/problem+json.
        '412':
          content:
            application/json:
              example:
                code: PIX-0031
                title: Idempotency Key Conflict
                message: The X-Idempotency header was already used with a different request.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: X-Idempotency replayed with a divergent request -- a different method, URL or body, or a different X-Account-Id (PIX-0031). Evidence that an earlier request under this key already succeeded. Legacy {code,title,message} envelope, NOT problem+json.
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '422':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0201
                title: Unprocessable Entity
                status: 422
                detail: Pix key does not exist or is not active.
                code: PIX-0201
              schema:
                $ref: '#/components/schemas/Detail'
          description: The Pix key is absent or inactive for the calling account (PIX-0201), or the key and description cannot fit in the BR Code merchant template (PIX-0207).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure generating or persisting the BR Code (PIX-0000, PIX-0204).
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The DICT Hub is unreachable or returned an invalid ownership response (PIX-0223).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Create a static BR Code
      tags:
        - BR Codes
  /brcodes/static/{id}:
    get:
      description: Returns a single static BR Code scoped to the calling tenant.
      operationId: getStaticBRCode
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/get-static-brcode
      parameters:
        - description: BR Code UUID
          in: path
          name: id
          required: true
          schema:
            description: BR Code UUID
            examples:
              - 019e22f9-aabe-7ec9-ba6b-41608b9accf9
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStaticBRCodeOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0015
                title: Bad Request
                status: 400
                detail: One or more path parameters are invalid.
                code: PIX-0015
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed BR Code UUID path parameter (PIX-0015).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0205
                title: Not Found
                status: 404
                detail: BR Code does not exist for this organization.
                code: PIX-0205
              schema:
                $ref: '#/components/schemas/Detail'
          description: No BR Code exists for the supplied UUID in the calling organization (PIX-0205).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure reading the BR Code (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Get a static BR Code by ID
      tags:
        - BR Codes
  /collections/duedate:
    get:
      description: Returns a page-based list envelope of due-date collections, optionally filtered by a dueDateFrom/dueDateTo range. When a `txId` query parameter is supplied the endpoint switches to a by-txId lookup and returns a single bare collection entity instead — the two 200 shapes are documented as a oneOf.
      operationId: listDueDateCollections
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/list-due-date-collections
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: BACEN transaction ID — routes to by-txId lookup
          explode: false
          in: query
          name: txId
          schema:
            description: BACEN transaction ID — routes to by-txId lookup
            examples:
              - T1234567890123456789012345A
            type: string
        - description: Page number (1-based, default 1)
          explode: false
          in: query
          name: page
          schema:
            description: Page number (1-based, default 1)
            examples:
              - '1'
            type: string
        - description: Rows per page (default 20, max 100)
          explode: false
          in: query
          name: limit
          schema:
            description: Rows per page (default 20, max 100)
            examples:
              - '20'
            type: string
        - description: Filter by status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status
            examples:
              - ACTIVE
            type: string
        - description: Filter by Pix key value (exact match)
          explode: false
          in: query
          name: keyValue
          schema:
            description: Filter by Pix key value (exact match)
            type: string
        - description: 'Filter: due date range start (YYYY-MM-DD)'
          explode: false
          in: query
          name: dueDateFrom
          schema:
            description: 'Filter: due date range start (YYYY-MM-DD)'
            examples:
              - '2026-08-01'
            type: string
        - description: 'Filter: due date range end (YYYY-MM-DD)'
          explode: false
          in: query
          name: dueDateTo
          schema:
            description: 'Filter: due date range end (YYYY-MM-DD)'
            examples:
              - '2026-08-31'
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                fictitiousExample:
                  summary: Fictitious example
                  value:
                    items:
                      - abatement:
                          modality: PERCENTAGE
                          value: '5.00'
                        accountId: 019606a1-3b4c-7d8e-9f01-234567890abc
                        additionalInfo:
                          - key: orderId
                            value: '12345'
                        amount: '100.50'
                        calendar:
                          dueDate: '2030-09-01'
                          validityAfterDue: 30
                        createdAt: '2030-08-20T10:30:00Z'
                        currency: BRL
                        debtor:
                          document: '39053344705'
                          name: João da Silva
                        description: Fatura de servicos
                        discount:
                          modality: VALUE_PER_CALENDAR_DAY_ADVANCE
                          value: '3.00'
                        emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F
                        expiresAt: '2030-10-01T23:59:59Z'
                        externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                        fine:
                          modality: FIXED_VALUE
                          value: '10.00'
                        id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab
                        interest:
                          modality: VALUE_CALENDAR_DAYS
                          value: '1.50'
                        isExpired: false
                        keyType: EVP
                        keyValue: 123e4567-e12b-12d1-a456-426655440000
                        locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                        merchantCity: Goiania
                        merchantDocument: '39053344705'
                        merchantName: Loja Teste
                        organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc
                        status: ACTIVE
                        txId: TX1234567890123456789012345
                        type: DUE_DATE
                        updatedAt: '2030-08-20T10:30:00Z'
                    limit: 20
                    page: 1
                    total: 1
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ListDueDateCollectionsOutput'
                  - $ref: '#/components/schemas/DueDateCollectionOutput'
          description: List envelope in list mode, or a single DueDateCollectionOutput when `txId` is supplied.
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0206
                title: Bad Request
                status: 400
                detail: Invalid filter parameter value.
                code: PIX-0206
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed X-Account-Id, or an invalid page/limit/dueDateFrom/dueDateTo/status filter value (PIX-0020, PIX-0206). Malformed X-Account-Id or invalid txId, page, limit, date range, status, or keyValue filter input (PIX-0001, PIX-0017, PIX-0020, PIX-0200, PIX-0206).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: 'By-`txId` mode only: no collection found for the given txId (PIX-0240). By-txId mode only: no due-date collection exists for the supplied txId in the account scope (PIX-0240).'
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure listing (or by-txId retrieving) collections. Unexpected internal failure listing or retrieving the collection (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: List due-date collections or retrieve one by txId
      tags:
        - Due-Date Collections
    post:
      description: 'Registers a dynamic due-date Pix collection using the due-date calendar defined by the BCB and optional value modifiers (fine, interest, abatement, and discount). The Pix key is validated before creation. The collection includes its EMV payload, location URL, and expiration time.


        **Replay:** retrying the same request with the same `txId` within the same organization, account, and merchant-document scope returns the original `201` response unchanged and does not create another collection. Using an existing `txId` with a different request body returns `PIX-0012` with status `409`.'
      operationId: createDueDateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/create-due-date-collection
      parameters:
        - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key returns the ORIGINAL response at 200, even when the body differs from the first request under this key -- the key alone decides replay for collection creation. To create a different collection, use a new X-Idempotency key and a new txId.
          in: header
          name: X-Idempotency
          required: true
          schema:
            maxLength: 64
            minLength: 1
            type: string
        - description: Receiver merchant account UUID (scopes DICT key validation)
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID (scopes DICT key validation)
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
      requestBody:
        content:
          application/json:
            examples:
              fictitiousExample:
                summary: Fictitious example
                value:
                  abatement:
                    modality: PERCENTAGE
                    value: '5.00'
                  additionalInfo:
                    - key: orderId
                      value: '12345'
                  amount: '100.50'
                  calendar:
                    dueDate: '2030-09-01'
                    validityAfterDue: 30
                  currency: BRL
                  debtor:
                    document: '39053344705'
                    name: João da Silva
                  description: Fatura de servicos
                  discount:
                    modality: VALUE_PER_CALENDAR_DAY_ADVANCE
                    value: '3.00'
                  fine:
                    modality: FIXED_VALUE
                    value: '10.00'
                  interest:
                    modality: VALUE_CALENDAR_DAYS
                    value: '1.50'
                  keyType: EVP
                  keyValue: 123e4567-e12b-12d1-a456-426655440000
                  merchantCity: Goiania
                  merchantName: Loja Teste
                  txId: TX1234567890123456789012345
            schema:
              $ref: '#/components/schemas/CreateDueDateCollectionBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DueDateCollectionOutput'
          description: Replay of an already-completed request under this X-Idempotency key -- the ORIGINAL response, verbatim, even when this request's body or txId differs from the first ( Never re-executes the command and never calls the provider a second time.
        '201':
          content:
            application/json:
              example:
                accountId: 0196a7b2-3e5f-7061-ac12-34567890abcd
                amount: '150.75'
                calendar:
                  dueDate: '2026-09-01'
                  validityAfterDue: 30
                createdAt: '2026-08-02T10:30:00Z'
                currency: BRL
                debtor:
                  document: '12345678909'
                  name: Maria Souza
                emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F
                expiresAt: '2026-10-01T00:00:00Z'
                externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab
                isExpired: false
                keyType: EMAIL
                keyValue: loja@example.com
                locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                merchantCity: Sao Paulo
                merchantDocument: '39053344705'
                merchantName: Loja Exemplo
                organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc
                status: ACTIVE
                txId: TX1234567890123456789012345
                type: DUE_DATE
                updatedAt: '2026-08-02T10:30:00Z'
              schema:
                $ref: '#/components/schemas/DueDateCollectionOutput'
          description: Created
        '400':
          content:
            application/json:
              example:
                code: PIX-0030
                title: Idempotency Key Required
                message: The X-Idempotency header is required for this operation and must be within the accepted length.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Missing or malformed headers/body fields, invalid collection input, a due-date/modifier rule failure, or provider-side request validation rejection (PIX-0001-0003, PIX-0017, PIX-0200, PIX-0224, PIX-0260-0267). X-Idempotency absent or longer than 64 bytes (PIX-0030) uses the legacy {code,title,message} envelope; other 400 errors use application/problem+json. Malformed request, a due-date/modifier validation rule failed (PIX-0001-0010, PIX-0200, PIX-0260-0267), or the provider rejected the create request (PIX-0224).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0225
                title: Not Found
                status: 404
                detail: The requested collection resource was not found at the provider.
                code: PIX-0225
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider reports that the addressed collection resource does not exist (PIX-0225). The provider reports the addressed resource as not found (PIX-0225).
        '409':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0012
                title: Conflict
                status: 409
                detail: The entity already exists or conflicts with an existing resource.
                code: PIX-0012
              schema:
                $ref: '#/components/schemas/Detail'
          description: The txId is already claimed, the provider reports a conflicting state, or an earlier create operation is still in progress (PIX-0012, PIX-0226, PIX-0244). txId already claimed by a non-replayable row -- divergent content, a different account, or a different collection type (PIX-0012) -- the provider reports a conflicting state (PIX-0226), or an earlier request for this BACEN key or this X-Idempotency key is still being processed (PIX-0244).
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '422':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0245
                title: Unprocessable Entity
                status: 422
                detail: The creation for this key can no longer be completed; use a new tx_id or contact support.
                code: PIX-0245
              schema:
                $ref: '#/components/schemas/Detail'
          description: The Pix key is absent or inactive, or an earlier create operation reached a terminal outcome (PIX-0201, PIX-0245). An earlier request for this BACEN key or this X-Idempotency key reached a terminal outcome that can never complete (PIX-0245). Use a new X-Idempotency key and a new txId.
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure comparing, recovering, or persisting the collection (PIX-0000). Unexpected internal failure comparing a replay against the existing row, or persisting the created collection.
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The DICT Hub or provider adapter is unreachable, or a successful provider response violates its contract (PIX-0223). The provider adapter is unreachable, or its response failed the contract check (PIX-0223).
        '504':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0054
                title: Gateway Timeout
                status: 504
                detail: The request timed out. Please try again later.
                code: PIX-0054
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider timed out handling the create request (PIX-0054).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Create a due-date Pix collection (cobv)
      tags:
        - Due-Date Collections
  /collections/duedate/provider-status:
    get:
      description: Reads the configured provider's current view of a due-date collection identified by its BACEN `tx_id` query parameter, alongside the Hub's persisted view, and reports whether they diverge. This operation is read-only and does not update the local collection. Authorization may be required when the deployment enables access management.
      operationId: getDueDateCollectionProviderStatus
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/get-due-date-provider-status
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            format: uuid
            type: string
        - description: BACEN transaction identifier
          explode: false
          in: query
          name: tx_id
          required: true
          schema:
            description: BACEN transaction identifier
            examples:
              - T1234567890123456789012345A
            maxLength: 35
            minLength: 26
            pattern: ^[a-zA-Z0-9]+$
            type: string
        - description: Bearer token; required when Access Manager is enabled
          in: header
          name: Authorization
          schema:
            description: Bearer token; required when Access Manager is enabled
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                divergent: false
                local:
                  accountId: 0196a7b2-3e5f-7061-ac12-34567890abcd
                  amount: '150.75'
                  calendar:
                    dueDate: '2026-09-01'
                    validityAfterDue: 30
                  createdAt: '2026-08-02T10:30:00Z'
                  currency: BRL
                  debtor:
                    document: '12345678909'
                    name: Maria Souza
                  emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F
                  expiresAt: '2026-10-01T00:00:00Z'
                  externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                  id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab
                  isExpired: false
                  keyType: EMAIL
                  keyValue: loja@example.com
                  locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                  merchantCity: Sao Paulo
                  merchantDocument: '39053344705'
                  merchantName: Loja Exemplo
                  organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc
                  status: ACTIVE
                  txId: TX1234567890123456789012345
                  type: DUE_DATE
                  updatedAt: '2026-08-02T10:30:00Z'
                provider:
                  amount: '150.75'
                  calendar:
                    dueDate: '2026-09-01'
                    validityAfterDue: 30
                  createdAt: '2026-08-02T10:30:00Z'
                  currency: BRL
                  debtor:
                    document: '12345678909'
                    name: Maria Souza
                  emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F
                  expiresAt: '2026-10-01T00:00:00Z'
                  externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                  locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                  revision: 0
                  status: PENDING
                  txId: TX1234567890123456789012345
              schema:
                $ref: '#/components/schemas/GetDueDateCollectionProviderStatusOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed X-Account-Id or txId, or the provider rejected the request (PIX-0200, PIX-0224).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: No local collection found for the given txId (PIX-0240), or the provider reports its resource as not found (PIX-0225).
        '409':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0226
                title: Conflict
                status: 409
                detail: The request conflicts with the provider's current state or with a request still in flight.
                code: PIX-0226
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider reports the collection in a conflicting state (PIX-0226).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure reading the local collection.
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider adapter is unreachable, or its response fails the contract check (PIX-0223).
        '504':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0054
                title: Gateway Timeout
                status: 504
                detail: The request timed out. Please try again later.
                code: PIX-0054
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider timed out handling the request (PIX-0054).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
        - {}
      summary: Poll the provider's current view of a due-date collection
      tags:
        - Due-Date Collections
  /collections/duedate/{id}:
    delete:
      description: 'Cancels a due-date collection synchronously and changes its status to `CANCELLED`. The operation is idempotent: cancelling a collection that is already `CANCELLED` returns the same `200` response.'
      operationId: cancelDueDateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/cancel-due-date-collection
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: Collection UUID
          in: path
          name: id
          required: true
          schema:
            description: Collection UUID
            examples:
              - 019e22f9-aabe-7ec9-ba6b-41608b9accf9
            type: string
      requestBody:
        content:
          application/json:
            example:
              reason: Customer requested cancellation
            schema:
              $ref: '#/components/schemas/CancelDueDateCollectionBody'
      responses:
        '200':
          content:
            application/json:
              example:
                accountId: 0196a7b2-3e5f-7061-ac12-34567890abcd
                amount: '150.75'
                calendar:
                  dueDate: '2026-09-01'
                  validityAfterDue: 30
                cancelledAt: '2026-08-10T14:00:00Z'
                cancelledReason: Customer requested cancellation
                createdAt: '2026-08-02T10:30:00Z'
                currency: BRL
                debtor:
                  document: '12345678909'
                  name: Maria Souza
                emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F
                expiresAt: '2026-10-01T00:00:00Z'
                externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab
                isExpired: false
                keyType: EMAIL
                keyValue: loja@example.com
                locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                merchantCity: Sao Paulo
                merchantDocument: '39053344705'
                merchantName: Loja Exemplo
                organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc
                status: CANCELLED
                txId: TX1234567890123456789012345
                type: DUE_DATE
                updatedAt: '2026-08-02T10:30:00Z'
              schema:
                $ref: '#/components/schemas/DueDateCollectionOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed id/X-Account-Id, or the cancellation reason exceeds 255 bytes (PIX-0200). Malformed collection UUID or X-Account-Id, or an invalid cancellation reason, including provider-side request validation rejection (PIX-0001-0003, PIX-0017, PIX-0200, PIX-0224).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: No collection found for the given id, including the cross-type isolation guard (PIX-0240). No due-date collection exists for the supplied UUID, or the provider reports the addressed resource missing (PIX-0240, PIX-0225).
        '409':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0226
                title: Conflict
                status: 409
                detail: The request conflicts with the provider's current state or with a request still in flight.
                code: PIX-0226
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider reports the collection in a conflicting state (PIX-0226).
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '422':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0241
                title: Unprocessable Entity
                status: 422
                detail: Collection is in a terminal state (already COMPLETED) and cannot transition.
                code: PIX-0241
              schema:
                $ref: '#/components/schemas/Detail'
          description: The collection is in a terminal state incompatible with cancellation -- already COMPLETED -- or a concurrent-modification reconciliation could not converge locally (PIX-0241). The collection is in a terminal state incompatible with cancellation, or reconciliation cannot converge (PIX-0241).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: The local persistence retry (and its own reconciliation retry) both failed after the provider already cancelled remotely. Unexpected internal failure persisting or reconciling the cancellation (PIX-0000).
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider adapter is unreachable (PIX-0223). The provider adapter is unreachable or returned an invalid success response (PIX-0223).
        '504':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0054
                title: Gateway Timeout
                status: 504
                detail: The request timed out. Please try again later.
                code: PIX-0054
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider timed out handling the cancel request (PIX-0054). The provider timed out handling the cancellation (PIX-0054).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Cancel a due-date collection
      tags:
        - Due-Date Collections
    get:
      description: Retrieves a due-date collection by its collection ID. A paid collection includes the payment block; a cancelled collection includes the cancellation details.
      operationId: getDueDateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/get-due-date-collection
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: Collection UUID
          in: path
          name: id
          required: true
          schema:
            description: Collection UUID
            examples:
              - 019e22f9-aabe-7ec9-ba6b-41608b9accf9
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                accountId: 0196a7b2-3e5f-7061-ac12-34567890abcd
                amount: '150.75'
                calendar:
                  dueDate: '2026-09-01'
                  validityAfterDue: 30
                createdAt: '2026-08-02T10:30:00Z'
                currency: BRL
                debtor:
                  document: '12345678909'
                  name: Maria Souza
                emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F
                expiresAt: '2026-10-01T00:00:00Z'
                externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab
                isExpired: false
                keyType: EMAIL
                keyValue: loja@example.com
                locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                merchantCity: Sao Paulo
                merchantDocument: '39053344705'
                merchantName: Loja Exemplo
                organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc
                status: ACTIVE
                txId: TX1234567890123456789012345
                type: DUE_DATE
                updatedAt: '2026-08-02T10:30:00Z'
              schema:
                $ref: '#/components/schemas/DueDateCollectionOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed id or X-Account-Id (PIX-0200). Malformed collection UUID or X-Account-Id (PIX-0001, PIX-0017, PIX-0200).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: No collection found for the given id, including the cross-type isolation guard (PIX-0240). No due-date collection exists for the supplied UUID in the account scope (PIX-0240).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure reading the collection. Unexpected internal failure reading the collection (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Get a due-date collection by ID
      tags:
        - Due-Date Collections
    patch:
      description: 'Revises the four BACEN value modifiers (fine, interest, abatement, discount) of an ACTIVE due-date collection. Each modifier is an independent RFC 7386 JSON Merge Patch slot: an object present in the body REPLACES that modifier outright, an explicit `null` REMOVES it, and an absent field leaves the currently-stored modifier unchanged. At least one modifier field is required. No other field (calendar, debtor, key, receiver) is revisable through this endpoint.


        **Replay:** retrying the same request with the same `X-Idempotency` returns the ORIGINAL 200 response unchanged rather than re-applying the modifiers a second time; retrying the same key with a divergent body is PIX-0031 @ 412. Unlike the other gated mutations, this route is FAIL-CLOSED: if the replay cache cannot serve the request it refuses with PIX-0032 @ 503 instead of re-applying the modifiers without replay protection.'
      operationId: reviseDueDateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/revise-due-date-collection
      parameters:
        - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412.
          in: header
          name: X-Idempotency
          required: true
          schema:
            maxLength: 64
            minLength: 1
            type: string
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: Collection UUID
          in: path
          name: id
          required: true
          schema:
            description: Collection UUID
            examples:
              - 019e22f9-aabe-7ec9-ba6b-41608b9accf9
            type: string
      requestBody:
        content:
          application/json:
            example:
              fine:
                modality: FIXED_VALUE
                value: '10.00'
            schema:
              additionalProperties: false
              minProperties: 1
              properties:
                abatement:
                  additionalProperties: false
                  description: Replace (object) or remove (null) the abatement (abatimento) modifier; omit to leave unchanged
                  properties:
                    modality:
                      description: Abatement calculation modality
                      enum:
                        - FIXED_VALUE
                        - PERCENTAGE
                      examples:
                        - PERCENTAGE
                      type: string
                    value:
                      description: Abatement value
                      examples:
                        - '5.00'
                      pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                      type: string
                  required:
                    - modality
                    - value
                  type:
                    - object
                    - 'null'
                discount:
                  description: Replace (object) or remove (null) the discount (desconto) modifier; omit to leave unchanged
                  oneOf:
                    - additionalProperties: false
                      properties:
                        fixedDates:
                          description: Date-anchored discount schedule (*_UNTIL_DATES modalities only, at most 3 entries)
                          items:
                            $ref: '#/components/schemas/DiscountFixedDateRequest'
                          maxItems: 3
                          minItems: 1
                          type: array
                        modality:
                          description: Discount calculation modality
                          enum:
                            - FIXED_VALUE_UNTIL_DATES
                            - PERCENT_UNTIL_DATES
                          examples:
                            - FIXED_VALUE_UNTIL_DATES
                          type: string
                        value:
                          description: Discount value (per-day advance modalities only)
                          pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                          type: string
                      required:
                        - modality
                        - fixedDates
                      type: object
                    - additionalProperties: false
                      properties:
                        fixedDates:
                          description: Date-anchored discount schedule (*_UNTIL_DATES modalities only, at most 3 entries)
                          items:
                            $ref: '#/components/schemas/DiscountFixedDateRequest'
                          type:
                            - array
                            - 'null'
                        modality:
                          description: Discount calculation modality
                          enum:
                            - VALUE_PER_CALENDAR_DAY_ADVANCE
                            - VALUE_PER_BUSINESS_DAY_ADVANCE
                            - PERCENT_PER_CALENDAR_DAY_ADVANCE
                            - PERCENT_PER_BUSINESS_DAY_ADVANCE
                          examples:
                            - VALUE_PER_CALENDAR_DAY_ADVANCE
                          type: string
                        value:
                          description: Discount value (per-day advance modalities only)
                          pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                          type: string
                      required:
                        - modality
                        - value
                      type: object
                    - type: 'null'
                fine:
                  additionalProperties: false
                  description: Replace (object) or remove (null) the fine (multa) modifier; omit to leave unchanged
                  properties:
                    modality:
                      description: Fine calculation modality
                      enum:
                        - FIXED_VALUE
                        - PERCENTAGE
                      examples:
                        - FIXED_VALUE
                      type: string
                    value:
                      description: Fine value
                      examples:
                        - '10.00'
                      pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                      type: string
                  required:
                    - modality
                    - value
                  type:
                    - object
                    - 'null'
                interest:
                  additionalProperties: false
                  description: Replace (object) or remove (null) the interest (juros) modifier; omit to leave unchanged
                  properties:
                    modality:
                      description: Interest calculation modality
                      enum:
                        - VALUE_CALENDAR_DAYS
                        - PERCENT_PER_DAY_CALENDAR_DAYS
                        - PERCENT_PER_MONTH_CALENDAR_DAYS
                        - PERCENT_PER_YEAR_CALENDAR_DAYS
                        - VALUE_BUSINESS_DAYS
                        - PERCENT_PER_DAY_BUSINESS_DAYS
                        - PERCENT_PER_MONTH_BUSINESS_DAYS
                        - PERCENT_PER_YEAR_BUSINESS_DAYS
                      examples:
                        - VALUE_CALENDAR_DAYS
                      type: string
                    value:
                      description: Interest value
                      examples:
                        - '1.50'
                      pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                      type: string
                  required:
                    - modality
                    - value
                  type:
                    - object
                    - 'null'
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                accountId: 0196a7b2-3e5f-7061-ac12-34567890abcd
                amount: '150.75'
                calendar:
                  dueDate: '2026-09-01'
                  validityAfterDue: 30
                createdAt: '2026-08-02T10:30:00Z'
                currency: BRL
                debtor:
                  document: '12345678909'
                  name: Maria Souza
                emvPayload: 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F
                expiresAt: '2026-10-01T00:00:00Z'
                externalId: 0196a7b2-4f60-7172-bd23-4567890abcde
                id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab
                isExpired: false
                keyType: EMAIL
                keyValue: loja@example.com
                locationUrl: https://pix.example.com/qr/v2/cobv-abc123
                merchantCity: Sao Paulo
                merchantDocument: '39053344705'
                merchantName: Loja Exemplo
                organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc
                status: ACTIVE
                txId: TX1234567890123456789012345
                type: DUE_DATE
                updatedAt: '2026-08-02T10:30:00Z'
              schema:
                $ref: '#/components/schemas/DueDateCollectionOutput'
          description: OK
        '400':
          content:
            application/json:
              example:
                code: PIX-0030
                title: Idempotency Key Required
                message: The X-Idempotency header is required for this operation and must be within the accepted length.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: X-Idempotency absent or longer than 64 bytes (PIX-0030) uses the legacy {code,title,message} envelope; other 400 errors use application/problem+json. Malformed id/X-Account-Id, a malformed fine/interest/abatement/discount modifier, or no modifier field present in the body at all (PIX-0200, PIX-0263-0266).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: No collection found for the given id, including the cross-type isolation guard (PIX-0240).
        '409':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0226
                title: Conflict
                status: 409
                detail: The request conflicts with the provider's current state or with a request still in flight.
                code: PIX-0226
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider reports the collection in a conflicting state (PIX-0226).
        '412':
          content:
            application/json:
              example:
                code: PIX-0031
                title: Idempotency Key Conflict
                message: The X-Idempotency header was already used with a different request.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: X-Idempotency replayed with a divergent request -- a different method, URL or body, or a different X-Account-Id (PIX-0031). Evidence that an earlier request under this key already succeeded. Legacy {code,title,message} envelope, NOT problem+json.
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '422':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0241
                title: Unprocessable Entity
                status: 422
                detail: Collection is in a terminal state (already CANCELLED or COMPLETED) and cannot transition.
                code: PIX-0241
              schema:
                $ref: '#/components/schemas/Detail'
          description: The collection is not ACTIVE -- already COMPLETED or CANCELLED (PIX-0241).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Persisting the revision failed even after the bounded local retry / reconciliation attempt -- the provider already applied it remotely and the divergence is durably recorded.
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider adapter is unreachable (PIX-0223).
        '503':
          content:
            application/json:
              example:
                code: PIX-0032
                title: Idempotency Unavailable
                message: The request was not processed because the idempotency store is unavailable. Please retry.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json.
        '504':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0054
                title: Gateway Timeout
                status: 504
                detail: The request timed out. Please try again later.
                code: PIX-0054
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider timed out handling the revise request (PIX-0054).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Revise a due-date collection's value modifiers
      tags:
        - Due-Date Collections
  /collections/immediate:
    get:
      description: Returns a page-based list envelope of immediate collections. When a `txId` query parameter is supplied the endpoint switches to a by-txId lookup and returns a single bare collection entity instead — the two 200 shapes are documented as a oneOf.
      operationId: listImmediateCollections
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/list-immediate-collections
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: BACEN transaction ID — routes to by-txId lookup
          explode: false
          in: query
          name: txId
          schema:
            description: BACEN transaction ID — routes to by-txId lookup
            examples:
              - T1234567890123456789012345A
            type: string
        - description: Page number (1-based, default 1)
          explode: false
          in: query
          name: page
          schema:
            description: Page number (1-based, default 1)
            examples:
              - '1'
            type: string
        - description: Rows per page (default 20, max 100)
          explode: false
          in: query
          name: limit
          schema:
            description: Rows per page (default 20, max 100)
            examples:
              - '20'
            type: string
        - description: Filter by status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status
            examples:
              - ACTIVE
            type: string
        - description: Filter by Pix key value (exact match)
          explode: false
          in: query
          name: keyValue
          schema:
            description: Filter by Pix key value (exact match)
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ListImmediateCollectionsOutput'
                  - $ref: '#/components/schemas/ImmediateCollectionOutput'
          description: List envelope in list mode, or a single ImmediateCollectionOutput when `txId` is supplied.
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0206
                title: Bad Request
                status: 400
                detail: Invalid filter parameter value.
                code: PIX-0206
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed X-Account-Id or invalid txId, page, limit, status, or keyValue filter input (PIX-0001, PIX-0017, PIX-0020, PIX-0200, PIX-0206).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: 'By-txId mode only: no immediate collection exists for the supplied txId in the account scope (PIX-0240).'
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure listing or retrieving the collection (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: List immediate collections or retrieve one by txId
      tags:
        - Immediate Collections
    post:
      description: Registers an immediate dynamic Pix collection. The Pix key is validated before creation. The collection includes its EMV payload, location URL, and expiration time.
      operationId: createImmediateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/create-immediate-collection
      parameters:
        - description: REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key returns the ORIGINAL response at 200, even when the body differs from the first request under this key -- the key alone decides replay for collection creation. To create a different collection, use a new X-Idempotency key and a new txId.
          in: header
          name: X-Idempotency
          required: true
          schema:
            maxLength: 64
            minLength: 1
            type: string
        - description: Receiver merchant account UUID (scopes DICT key validation)
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID (scopes DICT key validation)
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImmediateCollectionBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImmediateCollectionOutput'
          description: Replay of an already-completed request under this X-Idempotency key -- the ORIGINAL response, verbatim, even when this request's body or txId differs from the first ( Never re-executes the command and never calls the provider a second time.
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImmediateCollectionOutput'
          description: Created
        '400':
          content:
            application/json:
              example:
                code: PIX-0030
                title: Idempotency Key Required
                message: The X-Idempotency header is required for this operation and must be within the accepted length.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Missing or malformed headers/body fields, invalid collection input (PIX-0001-0003, PIX-0010, PIX-0017, PIX-0200), or provider-side request validation rejection (PIX-0224). X-Idempotency absent or longer than 64 bytes (PIX-0030) uses the legacy {code,title,message} envelope; other 400 errors use application/problem+json.
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0225
                title: Not Found
                status: 404
                detail: The requested collection resource was not found at the provider.
                code: PIX-0225
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider reports that the addressed collection resource does not exist (PIX-0225).
        '409':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0244
                title: Conflict
                status: 409
                detail: The creation for this key is already being processed; retry shortly.
                code: PIX-0244
              schema:
                $ref: '#/components/schemas/Detail'
          description: The txId is already claimed, the provider reports a conflicting state, or an earlier create operation is still in progress (PIX-0012, PIX-0226, PIX-0244). An earlier request for this BACEN key (organization, merchant_document, txId) or this X-Idempotency key is still being processed (PIX-0244). Retry shortly with the same key.
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '422':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0245
                title: Unprocessable Entity
                status: 422
                detail: The creation for this key can no longer be completed; use a new tx_id or contact support.
                code: PIX-0245
              schema:
                $ref: '#/components/schemas/Detail'
          description: The Pix key is absent or inactive, or an earlier create operation reached a terminal outcome (PIX-0201, PIX-0245). An earlier request for this BACEN key or this X-Idempotency key reached a terminal outcome that can never complete (PIX-0245). Use a new X-Idempotency key and a new txId.
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure comparing, recovering, or persisting the collection (PIX-0000).
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The DICT Hub or provider adapter is unreachable, or a successful provider response violates its contract (PIX-0223).
        '504':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0054
                title: Gateway Timeout
                status: 504
                detail: The request timed out. Please try again later.
                code: PIX-0054
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider timed out handling the create request (PIX-0054).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Create an immediate Pix collection (cob)
      tags:
        - Immediate Collections
  /collections/immediate/{id}:
    delete:
      description: Cancels an immediate collection synchronously and changes its status to `CANCELLED`. The operation is idempotent.
      operationId: cancelImmediateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/cancel-immediate-collection
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: Collection UUID
          in: path
          name: id
          required: true
          schema:
            description: Collection UUID
            examples:
              - 019e22f9-aabe-7ec9-ba6b-41608b9accf9
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelImmediateCollectionBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImmediateCollectionOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed collection UUID or X-Account-Id, or an invalid cancellation reason, including provider-side request validation rejection (PIX-0001-0003, PIX-0017, PIX-0200, PIX-0224).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: No immediate collection exists for the supplied UUID, or the provider reports the addressed resource missing (PIX-0240, PIX-0225).
        '409':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0226
                title: Conflict
                status: 409
                detail: The request conflicts with the provider's current state or with a request still in flight.
                code: PIX-0226
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider reports the collection in a conflicting state (PIX-0226).
        '415':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0016
                title: Unsupported Media Type
                status: 415
                detail: 'The request body must be sent with Content-Type: application/json.'
                code: PIX-0016
              schema:
                $ref: '#/components/schemas/Detail'
          description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016).
        '422':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0241
                title: Unprocessable Entity
                status: 422
                detail: Collection is in a terminal state (already CANCELLED or COMPLETED) and cannot transition.
                code: PIX-0241
              schema:
                $ref: '#/components/schemas/Detail'
          description: The collection is in a terminal state incompatible with cancellation (PIX-0241).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure persisting or reconciling the cancellation (PIX-0000).
        '502':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0223
                title: Bad Gateway
                status: 502
                detail: Provider adapter is unreachable.
                code: PIX-0223
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider adapter is unreachable or returned an invalid success response (PIX-0223).
        '504':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0054
                title: Gateway Timeout
                status: 504
                detail: The request timed out. Please try again later.
                code: PIX-0054
              schema:
                $ref: '#/components/schemas/Detail'
          description: The provider timed out handling the cancellation (PIX-0054).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Cancel an immediate collection
      tags:
        - Immediate Collections
    get:
      description: Retrieves an immediate collection by its collection ID. A paid collection includes the payment block; a cancelled collection includes the cancellation details.
      operationId: getImmediateCollection
      x-mint:
        href: /pt/reference/interfaces/pix-lerian/cob/get-immediate-collection
      parameters:
        - description: Receiver merchant account UUID
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Receiver merchant account UUID
            examples:
              - 019606a1-3b4c-7d8e-9f01-234567890abc
            type: string
        - description: Collection UUID
          in: path
          name: id
          required: true
          schema:
            description: Collection UUID
            examples:
              - 019e22f9-aabe-7ec9-ba6b-41608b9accf9
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImmediateCollectionOutput'
          description: OK
        '400':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0200
                title: Bad Request
                status: 400
                detail: Missing or malformed required fields.
                code: PIX-0200
              schema:
                $ref: '#/components/schemas/Detail'
          description: Malformed collection UUID or X-Account-Id (PIX-0001, PIX-0017, PIX-0200).
        '404':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0240
                title: Not Found
                status: 404
                detail: No collection found for the given identifiers.
                code: PIX-0240
              schema:
                $ref: '#/components/schemas/Detail'
          description: No immediate collection exists for the supplied UUID in the account scope (PIX-0240).
        '500':
          content:
            application/problem+json:
              example:
                type: https://errors.lerian.studio/v1/PIX-0000
                title: Internal Server Error
                status: 500
                detail: The server encountered an unexpected error. Please try again later.
                code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: Unexpected internal failure reading the collection (PIX-0000).
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      summary: Get an immediate collection by ID
      tags:
        - Immediate Collections
components:
  schemas:
    AbatementTermsDTO:
      additionalProperties: false
      properties:
        modality:
          examples:
            - PERCENTAGE
          type: string
        value:
          examples:
            - '5.00'
          type: string
      required:
        - modality
        - value
      type: object
    AbatementTermsRequest:
      additionalProperties: false
      properties:
        modality:
          description: Abatement calculation modality
          enum:
            - FIXED_VALUE
            - PERCENTAGE
          examples:
            - PERCENTAGE
          type: string
        value:
          description: Abatement value
          examples:
            - '5.00'
          pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
          type: string
      required:
        - modality
        - value
      type: object
    AdditionalInfoEntry:
      additionalProperties: false
      properties:
        key:
          description: Metadata key
          examples:
            - orderId
          type: string
        value:
          description: Metadata value
          examples:
            - '12345'
          type: string
      required:
        - key
        - value
      type: object
    CancelDueDateCollectionBody:
      additionalProperties: false
      properties:
        reason:
          description: Optional cancellation reason
          examples:
            - Customer requested cancellation
          type: string
      type: object
    CancelImmediateCollectionBody:
      additionalProperties: false
      properties:
        reason:
          description: Optional cancellation reason
          examples:
            - Customer requested cancellation
          type: string
      type: object
    CreateDueDateCollectionBody:
      additionalProperties: false
      properties:
        abatement:
          $ref: '#/components/schemas/AbatementTermsRequest'
          description: Optional abatement (abatimento) modifier
        additionalInfo:
          description: Free-form key/value metadata (max 50 entries)
          items:
            $ref: '#/components/schemas/AdditionalInfoEntry'
          type:
            - array
            - 'null'
        amount:
          description: Collection amount in BRL
          type: string
        calendar:
          $ref: '#/components/schemas/DueDateCalendarRequest'
          description: Due-date expiration calendar
        currency:
          description: Currency (BRL only)
          examples:
            - BRL
          type: string
        debtor:
          $ref: '#/components/schemas/DebtorRequest'
          description: Debtor block (mandatory for due-date collections)
        description:
          description: Free-form description
          examples:
            - Fatura de servicos
          type: string
        discount:
          description: Optional discount (desconto) modifier
          oneOf:
            - additionalProperties: false
              properties:
                fixedDates:
                  description: Date-anchored discount schedule (*_UNTIL_DATES modalities only, at most 3 entries)
                  items:
                    $ref: '#/components/schemas/DiscountFixedDateRequest'
                  maxItems: 3
                  minItems: 1
                  type: array
                modality:
                  description: Discount calculation modality
                  enum:
                    - FIXED_VALUE_UNTIL_DATES
                    - PERCENT_UNTIL_DATES
                  examples:
                    - FIXED_VALUE_UNTIL_DATES
                  type: string
                value:
                  description: Discount value (per-day advance modalities only)
                  pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                  type: string
              required:
                - modality
                - fixedDates
              type: object
            - additionalProperties: false
              properties:
                fixedDates:
                  description: Date-anchored discount schedule (*_UNTIL_DATES modalities only, at most 3 entries)
                  items:
                    $ref: '#/components/schemas/DiscountFixedDateRequest'
                  type:
                    - array
                    - 'null'
                modality:
                  description: Discount calculation modality
                  enum:
                    - VALUE_PER_CALENDAR_DAY_ADVANCE
                    - VALUE_PER_BUSINESS_DAY_ADVANCE
                    - PERCENT_PER_CALENDAR_DAY_ADVANCE
                    - PERCENT_PER_BUSINESS_DAY_ADVANCE
                  examples:
                    - VALUE_PER_CALENDAR_DAY_ADVANCE
                  type: string
                value:
                  description: Discount value (per-day advance modalities only)
                  pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
                  type: string
              required:
                - modality
                - value
              type: object
        fine:
          $ref: '#/components/schemas/FineTermsRequest'
          description: Optional fine (multa) modifier
        interest:
          $ref: '#/components/schemas/InterestTermsRequest'
          description: Optional interest (juros) modifier
        keyType:
          description: Pix key type
          examples:
            - EVP
          type: string
        keyValue:
          description: Pix key value
          examples:
            - 123e4567-e12b-12d1-a456-426655440000
          type: string
        merchantCity:
          description: Merchant city
          examples:
            - Goiania
          type: string
        merchantName:
          description: Merchant name
          examples:
            - Loja Teste
          type: string
        txId:
          description: BACEN transaction identifier
          examples:
            - TX1234567890123456789012345
          type: string
      required:
        - txId
        - keyType
        - keyValue
        - merchantName
        - merchantCity
        - amount
        - calendar
        - debtor
      type: object
    CreateImmediateCollectionBody:
      additionalProperties: false
      properties:
        additionalInfo:
          description: Free-form key/value metadata (max 50 entries)
          items:
            $ref: '#/components/schemas/AdditionalInfoEntry'
          type:
            - array
            - 'null'
        amount:
          description: Collection amount in BRL
          type: string
        currency:
          description: Currency (BRL only)
          examples:
            - BRL
          type: string
        debtor:
          $ref: '#/components/schemas/DebtorRequest'
          description: Optional debtor block
        description:
          description: Free-form description
          examples:
            - Pagamento do pedido 12345
          type: string
        expirationSeconds:
          description: Seconds until the collection expires
          examples:
            - 3600
          format: int64
          type: integer
        keyType:
          description: Pix key type
          examples:
            - EVP
          type: string
        keyValue:
          description: Pix key value
          examples:
            - 123e4567-e12b-12d1-a456-426655440000
          type: string
        merchantCity:
          description: Merchant city
          examples:
            - Goiania
          type: string
        merchantName:
          description: Merchant name
          examples:
            - Loja Teste
          type: string
        txId:
          description: BACEN transaction identifier
          examples:
            - TX1234567890123456789012345
          type: string
      required:
        - txId
        - keyType
        - keyValue
        - merchantName
        - merchantCity
        - amount
        - expirationSeconds
      type: object
    CreateStaticBRCodeBody:
      additionalProperties: false
      properties:
        amount:
          description: Fixed amount in BACEN-canonical decimal form (omit for open value)
          examples:
            - '100.50'
          type: string
        description:
          description: Free-form description
          examples:
            - Pagamento
          type: string
        keyType:
          description: Pix key type
          examples:
            - CPF
          type: string
        keyValue:
          description: Pix key value
          examples:
            - '39053344705'
          type: string
        merchantCity:
          description: Merchant city
          examples:
            - Goiania
          type: string
        merchantName:
          description: Merchant name
          examples:
            - Loja Teste
          type: string
        postalCode:
          description: 8-digit postal code
          examples:
            - '74000000'
          type: string
        txId:
          description: Optional merchant transaction identifier
          examples:
            - TX12345
          type: string
      required:
        - keyType
        - keyValue
        - merchantName
        - merchantCity
      type: object
    CreateStaticBRCodeOutput:
      additionalProperties: false
      properties:
        amount:
          examples:
            - '100.50'
          type: string
        createdAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
        currency:
          enum:
            - BRL
          examples:
            - BRL
          type: string
        description:
          examples:
            - Pagamento do pedido 12345
          type: string
        emvPayload:
          examples:
            - 00020101021126330014br.gov.bcb.pix0111390533447055204000053039865406100.505802BR5910Loja Teste6007Goiania62110507TX123456304AA54
          type: string
        id:
          examples:
            - 0196a7b2-1c3d-7e4f-8a90-1234567890ab
          type: string
        keyType:
          enum:
            - CPF
            - CNPJ
            - PHONE
            - EMAIL
            - EVP
          examples:
            - CPF
          type: string
        keyValue:
          examples:
            - '39053344705'
          type: string
        merchantCity:
          examples:
            - Goiania
          type: string
        merchantName:
          examples:
            - Loja Teste
          type: string
        organizationId:
          examples:
            - 0196a7b2-2d4e-7f50-9b01-234567890abc
          type: string
        status:
          enum:
            - ACTIVE
            - CANCELLED
          examples:
            - ACTIVE
          type: string
        type:
          enum:
            - STATIC
          examples:
            - STATIC
          type: string
        updatedAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - organizationId
        - type
        - keyType
        - keyValue
        - merchantName
        - merchantCity
        - emvPayload
        - status
        - createdAt
        - updatedAt
      type: object
    DebtorDTO:
      additionalProperties: false
      properties:
        document:
          examples:
            - '39053344705'
          type: string
        name:
          examples:
            - João da Silva
          type: string
      type: object
    DebtorRequest:
      additionalProperties: false
      properties:
        document:
          description: Debtor CPF (11 digits) or CNPJ (14 chars, digits or alphanumeric)
          examples:
            - '39053344705'
          type: string
        name:
          description: Debtor name
          examples:
            - João da Silva
          type: string
      type: object
    DecodeQRCodeBody:
      additionalProperties: false
      properties:
        emvPayload:
          description: EMV BR Code payload to decode
          examples:
            - 00020101021126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***630448CD
          type: string
      required:
        - emvPayload
      type: object
    DecodeQRCodeOutput:
      additionalProperties: false
      properties:
        amount:
          examples:
            - '100.50'
          type: string
        currency:
          enum:
            - BRL
          examples:
            - BRL
          type: string
        description:
          examples:
            - Pagamento do pedido 12345
          type: string
        expiresAt:
          examples:
            - '2026-05-06T11:30:00Z'
          format: date-time
          type: string
        isReusable:
          description: Whether the BR Code may be paid more than once. True for every STATIC payload, including one whose Point of Initiation method is absent.
          examples:
            - true
          type: boolean
        keyType:
          description: Pix key type inferred from keyValue, ABSENT when no type both matches and validates. A CPF/CNPJ must satisfy its Modulo 11 check digits — a document that does not is unregistrable at DICT, so no type is reported. A masked document ("529.982.247-25") IS recognised. A phone is any E.164 number, not only "+55".
          enum:
            - CPF
            - CNPJ
            - PHONE
            - EMAIL
            - EVP
          examples:
            - EVP
          type: string
        keyValue:
          description: 'Pix key exactly as the payload carries it, punctuation included. It is never normalized: this endpoint reports what was scanned.'
          examples:
            - 123e4567-e12b-12d1-a456-426655440000
          type: string
        merchantCity:
          examples:
            - Goiania
          type: string
        merchantName:
          examples:
            - Loja Teste
          type: string
        txId:
          examples:
            - TX12345
          type: string
        type:
          description: 'Type embedded in the payload. A payload that names NO Point of Initiation method (EMV tag 01 absent) is reported as STATIC: EMVCo makes the element optional and defines its absence as static, and BACEN''s own composed QR Code examples omit it.'
          enum:
            - STATIC
            - DYNAMIC_IMMEDIATE
            - DYNAMIC_DUEDATE
          examples:
            - STATIC
          type: string
      required:
        - type
        - merchantName
        - merchantCity
        - isReusable
      type: object
    Detail:
      additionalProperties: true
      properties:
        code:
          description: 'Stable, machine-readable domain error code scoped to the emitting service (format: <SERVICE>-NNNN).'
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
        upstream:
          $ref: '#/components/schemas/Upstream'
          description: 'RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one.'
      type: object
    DiscountFixedDateDTO:
      additionalProperties: false
      properties:
        date:
          examples:
            - '2026-08-25'
          format: date
          type: string
        value:
          examples:
            - '3.00'
          type: string
      required:
        - date
        - value
      type: object
    DiscountFixedDateRequest:
      additionalProperties: false
      properties:
        date:
          description: Discount cutoff date — a civil date, no time-of-day or timezone
          examples:
            - '2026-08-25'
          format: date
          type: string
        value:
          description: Discount value applicable through Date
          examples:
            - '3.00'
          type: string
      required:
        - date
        - value
      type: object
    DiscountTermsDTO:
      additionalProperties: false
      properties:
        fixedDates:
          items:
            $ref: '#/components/schemas/DiscountFixedDateDTO'
          type:
            - array
            - 'null'
        modality:
          examples:
            - FIXED_VALUE_UNTIL_DATES
          type: string
        value:
          type: string
      required:
        - modality
        - value
      type: object
    DueDateCalendarDTO:
      additionalProperties: false
      properties:
        dueDate:
          examples:
            - '2026-09-01'
          format: date
          type: string
        validityAfterDue:
          examples:
            - 30
          format: int64
          minimum: 0
          type: integer
      required:
        - dueDate
        - validityAfterDue
      type: object
    DueDateCalendarRequest:
      additionalProperties: false
      properties:
        dueDate:
          description: BACEN due date (calendario.dataDeVencimento) — a civil date, no time-of-day or timezone
          examples:
            - '2026-09-01'
          format: date
          type: string
        validityAfterDue:
          description: Calendar days of validity after the due date. Optional; defaults to 30 (BACEN API default) when omitted.
          examples:
            - 30
          format: int64
          type: integer
      required:
        - dueDate
      type: object
    DueDateCollectionOutput:
      additionalProperties: false
      properties:
        abatement:
          $ref: '#/components/schemas/AbatementTermsDTO'
        accountId:
          examples:
            - 0196a7b2-3e5f-7061-ac12-34567890abcd
          type: string
        additionalInfo:
          items:
            $ref: '#/components/schemas/KVDTO'
          type:
            - array
            - 'null'
        amount:
          examples:
            - '100.50'
          type: string
        calendar:
          $ref: '#/components/schemas/DueDateCalendarDTO'
        cancelledAt:
          examples:
            - '2026-05-06T10:40:00Z'
          format: date-time
          type: string
        cancelledReason:
          examples:
            - Customer requested cancellation
          type: string
        createdAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
        currency:
          enum:
            - BRL
          examples:
            - BRL
          type: string
        debtor:
          $ref: '#/components/schemas/DebtorDTO'
        description:
          examples:
            - Fatura de servicos
          type: string
        discount:
          $ref: '#/components/schemas/DiscountTermsDTO'
        emvPayload:
          examples:
            - 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F
          type: string
        expiresAt:
          examples:
            - '2026-05-06T11:30:00Z'
          format: date-time
          type: string
        externalId:
          examples:
            - 0196a7b2-4f60-7172-bd23-4567890abcde
          type: string
        fine:
          $ref: '#/components/schemas/FineTermsDTO'
        id:
          examples:
            - 0196a7b2-1c3d-7e4f-8a90-1234567890ab
          type: string
        interest:
          $ref: '#/components/schemas/InterestTermsDTO'
        isExpired:
          examples:
            - false
          type: boolean
        keyType:
          enum:
            - CPF
            - CNPJ
            - PHONE
            - EMAIL
            - EVP
          examples:
            - EVP
          type: string
        keyValue:
          examples:
            - 123e4567-e12b-12d1-a456-426655440000
          type: string
        locationUrl:
          examples:
            - https://pix.example.com/qr/v2/cobv-abc123
          type: string
        merchantCity:
          examples:
            - Goiania
          type: string
        merchantDocument:
          examples:
            - '39053344705'
          type: string
        merchantName:
          examples:
            - Loja Teste
          type: string
        organizationId:
          examples:
            - 0196a7b2-2d4e-7f50-9b01-234567890abc
          type: string
        payment:
          $ref: '#/components/schemas/PaymentDTO'
        status:
          enum:
            - ACTIVE
            - COMPLETED
            - CANCELLED
          examples:
            - ACTIVE
          type: string
        txId:
          examples:
            - TX1234567890123456789012345
          type: string
        type:
          enum:
            - IMMEDIATE
            - DUE_DATE
          examples:
            - DUE_DATE
          type: string
        updatedAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - organizationId
        - accountId
        - merchantDocument
        - type
        - status
        - txId
        - keyType
        - keyValue
        - merchantName
        - merchantCity
        - amount
        - currency
        - calendar
        - externalId
        - locationUrl
        - emvPayload
        - expiresAt
        - createdAt
        - updatedAt
        - isExpired
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    FineTermsDTO:
      additionalProperties: false
      properties:
        modality:
          examples:
            - FIXED_VALUE
          type: string
        value:
          examples:
            - '10.00'
          type: string
      required:
        - modality
        - value
      type: object
    FineTermsRequest:
      additionalProperties: false
      properties:
        modality:
          description: Fine calculation modality
          enum:
            - FIXED_VALUE
            - PERCENTAGE
          examples:
            - FIXED_VALUE
          type: string
        value:
          description: Fine value
          examples:
            - '10.00'
          pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
          type: string
      required:
        - modality
        - value
      type: object
    GetDueDateCollectionProviderStatusOutput:
      additionalProperties: false
      properties:
        divergent:
          type: boolean
        local:
          $ref: '#/components/schemas/DueDateCollectionOutput'
        provider:
          $ref: '#/components/schemas/ProviderDueDateCollectionView'
      required:
        - local
        - provider
        - divergent
      type: object
    GetStaticBRCodeOutput:
      additionalProperties: false
      properties:
        amount:
          examples:
            - '100.50'
          type: string
        createdAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
        currency:
          enum:
            - BRL
          examples:
            - BRL
          type: string
        description:
          examples:
            - Pagamento do pedido 12345
          type: string
        emvPayload:
          examples:
            - 00020101021126330014br.gov.bcb.pix0111390533447055204000053039865406100.505802BR5910Loja Teste6007Goiania62110507TX123456304AA54
          type: string
        id:
          examples:
            - 0196a7b2-1c3d-7e4f-8a90-1234567890ab
          type: string
        keyType:
          enum:
            - CPF
            - CNPJ
            - PHONE
            - EMAIL
            - EVP
          examples:
            - CPF
          type: string
        keyValue:
          examples:
            - '39053344705'
          type: string
        merchantCity:
          examples:
            - Goiania
          type: string
        merchantName:
          examples:
            - Loja Teste
          type: string
        organizationId:
          examples:
            - 0196a7b2-2d4e-7f50-9b01-234567890abc
          type: string
        status:
          enum:
            - ACTIVE
            - CANCELLED
          examples:
            - ACTIVE
          type: string
        type:
          enum:
            - STATIC
          examples:
            - STATIC
          type: string
        updatedAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - organizationId
        - type
        - keyType
        - keyValue
        - merchantName
        - merchantCity
        - emvPayload
        - status
        - createdAt
        - updatedAt
      type: object
    ImmediateCollectionOutput:
      additionalProperties: false
      properties:
        accountId:
          examples:
            - 0196a7b2-3e5f-7061-ac12-34567890abcd
          type: string
        additionalInfo:
          items:
            $ref: '#/components/schemas/KVDTO'
          type:
            - array
            - 'null'
        amount:
          examples:
            - '100.50'
          type: string
        cancelledAt:
          examples:
            - '2026-05-06T10:40:00Z'
          format: date-time
          type: string
        cancelledReason:
          examples:
            - Customer requested cancellation
          type: string
        createdAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
        currency:
          enum:
            - BRL
          examples:
            - BRL
          type: string
        debtor:
          $ref: '#/components/schemas/DebtorDTO'
        description:
          examples:
            - Pagamento do pedido 12345
          type: string
        emvPayload:
          examples:
            - 00020101021226500014br.gov.bcb.pix2528pix.example.com/qr/v2/abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041206
          type: string
        expirationSeconds:
          examples:
            - 3600
          format: int64
          type: integer
        expiresAt:
          examples:
            - '2026-05-06T11:30:00Z'
          format: date-time
          type: string
        externalId:
          examples:
            - 0196a7b2-4f60-7172-bd23-4567890abcde
          type: string
        id:
          examples:
            - 0196a7b2-1c3d-7e4f-8a90-1234567890ab
          type: string
        keyType:
          enum:
            - CPF
            - CNPJ
            - PHONE
            - EMAIL
            - EVP
          examples:
            - EVP
          type: string
        keyValue:
          examples:
            - 123e4567-e12b-12d1-a456-426655440000
          type: string
        locationUrl:
          examples:
            - https://pix.example.com/qr/v2/abc123
          type: string
        merchantCity:
          examples:
            - Goiania
          type: string
        merchantDocument:
          examples:
            - '39053344705'
          type: string
        merchantName:
          examples:
            - Loja Teste
          type: string
        organizationId:
          examples:
            - 0196a7b2-2d4e-7f50-9b01-234567890abc
          type: string
        payment:
          $ref: '#/components/schemas/PaymentDTO'
        status:
          enum:
            - ACTIVE
            - COMPLETED
            - CANCELLED
          examples:
            - ACTIVE
          type: string
        txId:
          examples:
            - TX1234567890123456789012345
          type: string
        type:
          enum:
            - IMMEDIATE
            - DUE_DATE
          examples:
            - IMMEDIATE
          type: string
        updatedAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - organizationId
        - accountId
        - merchantDocument
        - type
        - status
        - txId
        - keyType
        - keyValue
        - merchantName
        - merchantCity
        - amount
        - currency
        - expirationSeconds
        - externalId
        - locationUrl
        - emvPayload
        - expiresAt
        - createdAt
        - updatedAt
      type: object
    InterestTermsDTO:
      additionalProperties: false
      properties:
        modality:
          examples:
            - VALUE_CALENDAR_DAYS
          type: string
        value:
          examples:
            - '1.50'
          type: string
      required:
        - modality
        - value
      type: object
    InterestTermsRequest:
      additionalProperties: false
      properties:
        modality:
          description: Interest calculation modality
          enum:
            - VALUE_CALENDAR_DAYS
            - PERCENT_PER_DAY_CALENDAR_DAYS
            - PERCENT_PER_MONTH_CALENDAR_DAYS
            - PERCENT_PER_YEAR_CALENDAR_DAYS
            - VALUE_BUSINESS_DAYS
            - PERCENT_PER_DAY_BUSINESS_DAYS
            - PERCENT_PER_MONTH_BUSINESS_DAYS
            - PERCENT_PER_YEAR_BUSINESS_DAYS
          examples:
            - VALUE_CALENDAR_DAYS
          type: string
        value:
          description: Interest value
          examples:
            - '1.50'
          pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$
          type: string
      required:
        - modality
        - value
      type: object
    KVDTO:
      additionalProperties: false
      properties:
        key:
          examples:
            - orderId
          type: string
        value:
          examples:
            - '12345'
          type: string
      required:
        - key
        - value
      type: object
    LegacyErrorEnvelope:
      additionalProperties: false
      properties:
        code:
          description: PIX-XXXX error code
          type: string
        message:
          description: Human-readable error message
          type: string
        title:
          description: Short error title
          type: string
      required:
        - code
        - title
        - message
      type: object
    ListDueDateCollectionsOutput:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/DueDateCollectionOutput'
          type:
            - array
            - 'null'
        limit:
          examples:
            - 20
          format: int64
          type: integer
        page:
          examples:
            - 1
          format: int64
          type: integer
        total:
          examples:
            - 1
          format: int64
          type: integer
      required:
        - items
        - total
        - page
        - limit
      type: object
    ListImmediateCollectionsOutput:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ImmediateCollectionOutput'
          type:
            - array
            - 'null'
        limit:
          examples:
            - 20
          format: int64
          type: integer
        page:
          examples:
            - 1
          format: int64
          type: integer
        total:
          examples:
            - 1
          format: int64
          type: integer
      required:
        - items
        - total
        - page
        - limit
      type: object
    ListStaticBRCodesOutput:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetStaticBRCodeOutput'
          type:
            - array
            - 'null'
        limit:
          examples:
            - 20
          format: int64
          type: integer
        page:
          examples:
            - 1
          format: int64
          type: integer
        total:
          examples:
            - 1
          format: int64
          type: integer
      required:
        - items
        - total
        - page
        - limit
      type: object
    PayerDTO:
      additionalProperties: false
      properties:
        ispb:
          examples:
            - '12345678'
          type: string
        name:
          examples:
            - João da Silva
          type: string
        taxId:
          examples:
            - '39053344705'
          type: string
      type: object
    PaymentDTO:
      additionalProperties: false
      properties:
        amount:
          examples:
            - '100.50'
          type: string
        endToEndId:
          examples:
            - E12345678202605061030abcdef12345
          type: string
        paidAt:
          examples:
            - '2026-05-06T10:35:00Z'
          format: date-time
          type: string
        payer:
          $ref: '#/components/schemas/PayerDTO'
      required:
        - endToEndId
        - amount
        - paidAt
      type: object
    ProviderDueDateCollectionView:
      additionalProperties: false
      properties:
        abatement:
          $ref: '#/components/schemas/AbatementTermsDTO'
        amount:
          examples:
            - '100.50'
          type: string
        calendar:
          $ref: '#/components/schemas/DueDateCalendarDTO'
        createdAt:
          examples:
            - '2026-05-06T10:30:00Z'
          format: date-time
          type: string
        currency:
          examples:
            - BRL
          type: string
        debtor:
          $ref: '#/components/schemas/DebtorDTO'
        discount:
          $ref: '#/components/schemas/DiscountTermsDTO'
        emvPayload:
          examples:
            - 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F
          type: string
        expiresAt:
          examples:
            - '2026-05-06T11:30:00Z'
          format: date-time
          type: string
        externalId:
          examples:
            - 0196a7b2-4f60-7172-bd23-4567890abcde
          type: string
        fine:
          $ref: '#/components/schemas/FineTermsDTO'
        interest:
          $ref: '#/components/schemas/InterestTermsDTO'
        locationUrl:
          examples:
            - https://pix.example.com/qr/v2/cobv-abc123
          type: string
        payments:
          items:
            $ref: '#/components/schemas/ProviderDueDatePaymentDTO'
          type:
            - array
            - 'null'
        revision:
          examples:
            - 0
          format: int64
          minimum: 0
          type: integer
        status:
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - REJECTED
            - FAILED
          type: string
        txId:
          examples:
            - TX1234567890123456789012345
          type: string
      required:
        - externalId
        - txId
        - status
        - revision
        - calendar
        - amount
        - currency
        - expiresAt
        - createdAt
      type: object
    ProviderDueDatePaymentDTO:
      additionalProperties: false
      properties:
        amount:
          examples:
            - '100.50'
          type: string
        currency:
          examples:
            - BRL
          type: string
        endToEndId:
          examples:
            - E12345678202609011200abcdefghijkl
          type: string
        paidAt:
          examples:
            - '2026-09-01T11:30:00Z'
          format: date-time
          type: string
      required:
        - endToEndId
        - amount
        - currency
        - paidAt
      type: object
    Upstream:
      additionalProperties: false
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: The upstream provider's own error message, verbatim (bounded, never its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http