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

# Decode a Pix QR Code

> Use this endpoint to decode a Pix BR Code payload and extract the payment data it contains. This service supports all Pix QR Code types: static, immediate collections, and due date collections. When the code carries a Pix Automático recurrence location, the response includes a `recurrence` block. When an immediate collection carries Pix Saque or Pix Troco data, the response includes a `withdrawal` block. The response type varies with the QR code type (STATIC, IMMEDIATE, DUE_DATE, or RECURRENCE).



## OpenAPI

````yaml /pt/openapi/v3-current/indirect-pix.yaml post /v1/qrcodes/decode
openapi: 3.1.0
info:
  contact:
    email: contact@lerian.studio
    name: Lerian Studio
    url: https://lerian.studio
  description: >-
    API for Pix Indirect via BTG. It covers DICT keys and claims; MED infraction
    reports, fraud markers, refund requests, and funds recoveries; DICT
    statistics and reconciliation; Pix transfers, refunds, and schedules; static
    QR codes and QR code decoding; immediate and due-date collections; Pix
    Automático for the payer; transaction reports and TemposTransacoes
    statistics; and inbound and outbound webhook records.
  license:
    name: Lerian Studio General License
  title: Pix BTG API
  version: 1.14.0
servers:
  - url: https://api.example.com
    description: >-
      Replace the example host with the URL provided during environment
      onboarding.
security:
  - BearerAuth: []
paths:
  /v1/qrcodes/decode:
    post:
      tags:
        - Decode
      summary: Decode a Pix QR Code
      description: >-
        Use this endpoint to decode a Pix BR Code payload and extract the
        payment data it contains. This service supports all Pix QR Code types:
        static, immediate collections, and due date collections. When the code
        carries a Pix Automático recurrence location, the response includes a
        `recurrence` block. When an immediate collection carries Pix Saque or
        Pix Troco data, the response includes a `withdrawal` block. The response
        type varies with the QR code type (STATIC, IMMEDIATE, DUE_DATE, or
        RECURRENCE).
      operationId: decode-qr-code
      parameters:
        - description: Unique identifier of the Midaz Ledger Account (UUID format)
          in: header
          name: X-Account-Id
          required: true
          schema:
            description: Unique identifier of the Midaz Ledger Account (UUID format)
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecodeInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/StaticDecodeOutput'
                  - $ref: '#/components/schemas/ImmediateDecodeOutput'
                  - $ref: '#/components/schemas/DueDateDecodeOutput'
                  - $ref: '#/components/schemas/RecurrenceDecodeOutput'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorBody'
          description: Bad Request
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorBody'
          description: Request Entity Too Large
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorBody'
          description: Internal Server Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorBody'
          description: Error
components:
  schemas:
    DecodeInput:
      additionalProperties: false
      properties:
        cityCode:
          description: >-
            City code based on IBGE Municipal Code Table (optional, used for
            COBV)
          examples:
            - '3550308'
          type: string
        emv:
          description: >-
            EMV QR Code payload string to decode (text content from scanned QR
            Code)
          examples:
            - 00020126580014br.gov.bcb.pix...
          minLength: 1
          type: string
        paymentDate:
          description: >-
            Payment date in ISO8601 format (defaults to current date if not
            provided)
          examples:
            - '2024-12-31'
          type: string
      required:
        - emv
      type: object
    StaticDecodeOutput:
      additionalProperties: false
      properties:
        amount:
          description: Fixed payment amount (optional)
          examples:
            - '100.00'
          type: string
        description:
          description: Custom message or description shown to the payer
          examples:
            - 'Payment for order #12345'
          type: string
        merchant:
          $ref: '#/components/schemas/StaticDecodeMerchant'
          description: Merchant information from the QR code
        receiverKey:
          description: Pix key that will receive the payment
          examples:
            - '+5511999999999'
          type: string
        recurrence:
          $ref: '#/components/schemas/RecurrenceDecodeData'
          description: >-
            Pix Automático recurrence data (present only for recurrence-bearing
            QR codes)
        txId:
          description: Transaction identification (txid) sent on the payment message
          examples:
            - TX123ABC
          type: string
        type:
          description: QR Code type identifier (STATIC)
          examples:
            - STATIC
          type: string
      required:
        - type
        - receiverKey
      type: object
    ImmediateDecodeOutput:
      additionalProperties: false
      properties:
        additionalInfo:
          additionalProperties:
            type: string
          description: Key-value map containing additional information
          type: object
        amount:
          description: >-
            Charge original amount in decimal format with 2 decimal places. NOT
            the payable total for withdrawal-bearing charges: 0.00 for Pix Saque
            and the purchase value only for Pix Troco — the payable total is
            withdrawalAmount, resp. transactionAmount + withdrawalAmount
          examples:
            - '100.00'
          type: string
        debtor:
          $ref: '#/components/schemas/ImmediateDecodeDebtor'
          description: Payer identification information (optional)
        description:
          description: Custom message or description for the collection
          examples:
            - 'Payment for order #12345'
          type: string
        emv:
          description: Original EMV payload from the QR code
          examples:
            - 00020126580014br.gov.bcb.pix...
          type: string
        expirationInSeconds:
          description: Time in seconds until the collection expires
          examples:
            - 3600
          format: int64
          type: integer
        receiverKey:
          description: Pix key that will receive the payment
          examples:
            - '+5511999999999'
          type: string
        recurrence:
          $ref: '#/components/schemas/RecurrenceDecodeData'
          description: >-
            Pix Automático recurrence data (present only for recurrence-bearing
            QR codes)
        review:
          description: Review number of the collection
          examples:
            - 0
          format: int64
          type: integer
        status:
          description: Status of the collection, as BTG returns it
          examples:
            - ATIVA
          type: string
        txId:
          description: Unique transaction identifier for this collection
          examples:
            - TXabcdefghijklmno123456789
          type: string
        type:
          description: QR Code type identifier (IMMEDIATE)
          examples:
            - IMMEDIATE
          type: string
        withdrawal:
          $ref: '#/components/schemas/WithdrawalDecodeData'
          description: Pix Saque/Troco data (present only for withdrawal or change charges)
      required:
        - type
        - review
        - amount
        - expirationInSeconds
        - receiverKey
        - txId
        - emv
        - status
      type: object
    DueDateDecodeOutput:
      additionalProperties: false
      properties:
        additionalInfo:
          description: List of additional information strings
          examples:
            - - 'Invoice: 12345'
          items:
            type: string
          type: array
        amount:
          $ref: '#/components/schemas/DecodeAmountObject'
          description: >-
            Amount structure containing original value, fines, interest,
            discounts and abatement
        debtor:
          $ref: '#/components/schemas/DueDateDecodeDebtor'
          description: Payer identification information
        description:
          description: Custom message or description for the collection
          examples:
            - 'Payment for invoice #12345'
          type: string
        dueDate:
          description: Due date for the collection (ISO8601 format)
          examples:
            - '2024-12-31'
          type: string
        receiver:
          $ref: '#/components/schemas/DueDateDecodeReceiver'
          description: Receiver or merchant identification information
        receiverKey:
          description: Pix key that will receive the payment
          examples:
            - '+5511999999999'
          type: string
        recurrence:
          $ref: '#/components/schemas/RecurrenceDecodeData'
          description: >-
            Pix Automático recurrence data (present only for recurrence-bearing
            QR codes)
        review:
          description: Review number of the collection
          examples:
            - 0
          format: int64
          type: integer
        status:
          description: Status of the collection, as BTG returns it
          examples:
            - ATIVA
          type: string
        txId:
          description: Unique transaction identifier for this collection
          examples:
            - TXabcdefghijklmno123456789
          type: string
        type:
          description: QR Code type identifier (DUE_DATE)
          examples:
            - DUE_DATE
          type: string
        validAfterDue:
          description: Number of days the collection remains valid after the due date
          examples:
            - 30
          format: int64
          type: integer
      required:
        - type
        - review
        - dueDate
        - validAfterDue
        - receiverKey
        - txId
        - debtor
        - receiver
        - amount
        - status
      type: object
    RecurrenceDecodeOutput:
      additionalProperties: false
      properties:
        recurrence:
          $ref: '#/components/schemas/RecurrenceDecodeData'
          description: Pix Automático recurrence data
        type:
          description: QR Code type identifier (RECURRENCE)
          examples:
            - RECURRENCE
          type: string
      required:
        - type
        - recurrence
      type: object
    LegacyErrorBody:
      additionalProperties: false
      properties:
        code:
          type: string
        fields:
          additionalProperties:
            type: string
          type: object
        headers:
          additionalProperties:
            type: string
          type: object
        message:
          type: string
        paths:
          additionalProperties:
            type: string
          type: object
        queryParams:
          additionalProperties:
            type: string
          type: object
        raw:
          type: string
        title:
          type: string
      required:
        - code
        - title
        - message
      type: object
    StaticDecodeMerchant:
      additionalProperties: false
      properties:
        categoryCode:
          description: Merchant category code (MCC)
          examples:
            - '5411'
          type: string
        city:
          description: City where the merchant is located
          examples:
            - São Paulo
          type: string
        name:
          description: Name of the merchant
          examples:
            - Loja ABC
          type: string
        postalCode:
          description: Postal code (CEP) of the merchant
          examples:
            - 01310-100
          type: string
      type: object
    RecurrenceDecodeData:
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/RecurrenceDecodeAmount'
          description: Recurrence value profile
        calendar:
          $ref: '#/components/schemas/RecurrenceDecodeCalendar'
          description: Recurrence schedule
        idRec:
          description: BACEN recurrence identifier
          examples:
            - RR0000000000000000001
          type: string
        link:
          $ref: '#/components/schemas/RecurrenceDecodeLink'
          description: Recurrence contract/debtor binding
        payee:
          $ref: '#/components/schemas/RecurrenceDecodePayee'
          description: Recurrence receiver/merchant
        recLocationUrl:
          description: Recurrence location URL (cache token for the recurrence payload)
          examples:
            - https://pix.example.com/rec/v2/abc123
          type: string
        recurrenceCreationDate:
          description: Recurrence creation timestamp
          examples:
            - '2026-05-28T12:00:00Z'
          format: date-time
          type: string
        retryPolicy:
          description: Receiver multi-day retry policy (NO_RETRY, RETRY_3X_7D)
          enum:
            - NO_RETRY
            - RETRY_3X_7D
          examples:
            - RETRY_3X_7D
          type: string
      required:
        - idRec
        - recLocationUrl
      type: object
    ImmediateDecodeDebtor:
      additionalProperties: false
      properties:
        document:
          description: CPF or CNPJ of the debtor
          examples:
            - '52998224725'
          type: string
        name:
          description: Name of the debtor (payer)
          examples:
            - John Doe
          type: string
      required:
        - name
        - document
      type: object
    WithdrawalDecodeData:
      additionalProperties: false
      properties:
        agentMode:
          description: BACEN withdrawal agent modality
          examples:
            - AGTOT
          type: string
        amountEditable:
          description: Whether the payer may change the withdrawal amount
          examples:
            - false
          type: boolean
        nature:
          description: Withdrawal nature (WITHDRAWAL for Pix Saque, CHANGE for Pix Troco)
          enum:
            - WITHDRAWAL
            - CHANGE
          examples:
            - WITHDRAWAL
          type: string
        transactionAmount:
          description: Purchase amount (present only for Pix Troco)
          examples:
            - '80.00'
          type: string
        withdrawalAmount:
          description: Withdrawal amount handed to the payer as cash
          examples:
            - '50.00'
          type: string
        withdrawalServiceProvider:
          description: ISPB of the withdrawal service provider
          examples:
            - '12345678'
          type: string
      required:
        - nature
        - withdrawalAmount
        - agentMode
        - withdrawalServiceProvider
        - amountEditable
      type: object
    DecodeAmountObject:
      additionalProperties: false
      properties:
        abatement:
          description: Abatement configuration (optional)
          type: string
        discount:
          description: Discount configuration (optional)
          type: string
        final:
          description: >-
            Final amount considering all adjustments (discounts, fines,
            abatements, interests)
          examples:
            - '100.00'
          type: string
        fine:
          description: Fine configuration (optional)
          type: string
        interest:
          description: Interest configuration (optional)
          type: string
        original:
          description: Original collection amount in decimal format
          examples:
            - '100.00'
          type: string
      required:
        - original
        - final
      type: object
    DueDateDecodeDebtor:
      additionalProperties: false
      properties:
        address:
          description: Debtor address
          examples:
            - Rua Example, 123
          type: string
        city:
          description: Debtor city
          examples:
            - São Paulo
          type: string
        document:
          description: Debtor CPF or CNPJ identifier
          examples:
            - '52998224725'
          type: string
        email:
          description: Debtor email
          examples:
            - john.doe@example.com
          type: string
        name:
          description: Debtor name
          examples:
            - John Doe
          type: string
        state:
          description: Debtor state
          examples:
            - SP
          type: string
        zipCode:
          description: Debtor postal code
          examples:
            - 01310-100
          type: string
      required:
        - name
        - document
      type: object
    DueDateDecodeReceiver:
      additionalProperties: false
      properties:
        address:
          description: Street address of the receiver
          examples:
            - Av. Paulista, 1000
          type: string
        city:
          description: City of the receiver
          examples:
            - São Paulo
          type: string
        document:
          description: CPF or CNPJ of the receiver
          examples:
            - '11222333000181'
          type: string
        name:
          description: Name of the receiver
          examples:
            - Merchant ABC
          type: string
        state:
          description: State (UF) of the receiver
          examples:
            - SP
          type: string
        tradeName:
          description: Trade name of the receiver
          examples:
            - ABC Store
          type: string
        zipCode:
          description: Postal code (CEP) of the receiver
          examples:
            - 01310-100
          type: string
      required:
        - name
        - document
        - address
        - city
        - state
        - zipCode
      type: object
    RecurrenceDecodeAmount:
      additionalProperties: false
      properties:
        amountRec:
          description: Fixed recurrence amount
          examples:
            - '29.90'
          type: string
        debitorMinimumAmount:
          description: Minimum debit amount for variable recurrences
          examples:
            - '10.00'
          type: string
      type: object
    RecurrenceDecodeCalendar:
      additionalProperties: false
      properties:
        finalDate:
          description: Last eligible debit date (optional)
          examples:
            - '2027-06-01'
          format: date
          type: string
        initialDate:
          description: First eligible debit date
          examples:
            - '2026-06-01'
          format: date
          type: string
        periodicity:
          description: >-
            Recurrence periodicity (WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL,
            ANNUAL, CUSTOM)
          enum:
            - WEEKLY
            - MONTHLY
            - QUARTERLY
            - SEMIANNUAL
            - ANNUAL
            - CUSTOM
          examples:
            - MONTHLY
          type: string
      required:
        - initialDate
        - periodicity
      type: object
    RecurrenceDecodeLink:
      additionalProperties: false
      properties:
        contract:
          description: Receiver contract reference
          examples:
            - contract-2026-001
          type: string
        debtor:
          $ref: '#/components/schemas/RecurrenceDecodeDebtor'
          description: Recurrence debtor
        object:
          description: Recurrence object/description (optional)
          examples:
            - Streaming subscription
          type: string
      required:
        - contract
      type: object
    RecurrenceDecodePayee:
      additionalProperties: false
      properties:
        cnpj:
          description: Receiver CNPJ
          examples:
            - '81626496000105'
          type: string
        name:
          description: Receiver name
          examples:
            - Streaming Co
          type: string
        participantIspb:
          description: Receiver PSP ISPB
          examples:
            - '12345678'
          type: string
      required:
        - cnpj
        - name
        - participantIspb
      type: object
    RecurrenceDecodeDebtor:
      additionalProperties: false
      properties:
        cnpj:
          description: Debtor CNPJ (legal person)
          examples:
            - '96256999000103'
          type: string
        cpf:
          description: Debtor CPF (natural person)
          examples:
            - '61869782062'
          type: string
        name:
          description: Debtor name
          examples:
            - John Doe
          type: string
      required:
        - name
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.