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

# Pagar com QR Pix

> Pré-visualize, confirme e acompanhe pagamentos Pix iniciados por QR Code.

Use este fluxo para pagar um QR Pix pela API. Antes de enviar o pagamento, confira o recebedor, o valor, a tarifa, o total debitado e a validade da prévia.

## Disponibilidade

O Pix por QR Code está disponível para contas elegíveis com pagamentos Pix habilitados. A API valida o QR Code e mostra os dados da cobrança antes da confirmação.

## Fluxo

**1. Gere a prévia**

Envie o conteúdo do QR Code para [Pré-visualizar pagamento por QR Pix](https://docs.turbofypay.com/pages/reference/payouts/pre-visualizar-pagamento-qr-pix.md). A resposta inclui `previewId`, validade, tipo de QR, recebedor com documento mascarado, valor, tarifa, total debitado e moeda.

**2. Revise os dados**

Mostre os dados da prévia e confirme o pagamento somente depois de verificar o recebedor, o valor e o total debitado. O valor total é informado em centavos e a moeda é `BRL`.

**3. Solicite o pagamento**

Envie `previewId` e uma `idempotencyKey` para [Solicitar pagamento por QR Pix](https://docs.turbofypay.com/pages/reference/payouts/solicitar-pagamento-qr-pix.md). Use o `paymentId` retornado para acompanhamento. Não derive esse ID do `previewId`.

**4. Acompanhe o resultado**

Consulte [Consultar pagamento por QR Pix](https://docs.turbofypay.com/pages/reference/payouts/consultar-pagamento-qr-pix.md) até obter o estado do pagamento. Se o status for `RECONCILIATION_REQUIRED`, aguarde a conciliação antes de tratar o pagamento como concluído ou falho.

## Autenticação e escopos

As duas operações `POST` exigem `x-client-id`, `x-client-secret`, `x-turbofy-timestamp` e `x-turbofy-signature`, além do escopo `payout:write`. A assinatura HMAC é obrigatória também em ambientes locais e de teste.

A operação `GET` exige `x-client-id`, `x-client-secret` e o escopo `payout:read`.

Consulte [Autenticação](https://docs.turbofypay.com/pages/integracao/autenticacao.md) para calcular a assinatura HMAC. Gere uma assinatura nova para cada requisição e assine o método, o caminho e o corpo exatos enviados.

## Respostas e erros

* `POST /v1/payouts/pix-qr/preview` retorna `200` com os dados da prévia.
* `POST /v1/payouts/pix-qr` retorna `202` para uma solicitação aceita ou `200` no replay idempotente. Ambos retornam o mesmo formato público da consulta.
* `GET /v1/payouts/pix-qr/{paymentId}` retorna `200`. Um pagamento inexistente ou de outro merchant retorna `404`.
* `409` indica prévia expirada ou alterada, prévia ou cobrança já confirmada, conflito de idempotência, saldo insuficiente ou bloqueio.
* `422` indica QR não verificado ou expirado, valor divergente, tipo não disponível ou valor fora do intervalo permitido.
* `503` com `PIX_QR_UNAVAILABLE` indica serviço indisponível ou recurso desabilitado para o merchant ou tipo de QR.

Todos os valores monetários são inteiros em centavos. A API retorna a tarifa e o total debitado separadamente para facilitar a conferência.


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