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. 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. Use o paymentId retornado para acompanhamento. Não derive esse ID do previewId.4
Acompanhe o resultado
Consulte Consultar pagamento por QR Pix 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çõesPOST 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 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/previewretorna200com os dados da prévia.POST /v1/payouts/pix-qrretorna202para uma solicitação aceita ou200no replay idempotente. Ambos retornam o mesmo formato público da consulta.GET /v1/payouts/pix-qr/{paymentId}retorna200. Um pagamento inexistente ou de outro merchant retorna404.409indica prévia expirada ou alterada, prévia ou cobrança já confirmada, conflito de idempotência, saldo insuficiente ou bloqueio.422indica QR não verificado ou expirado, valor divergente, tipo não disponível ou valor fora do intervalo permitido.503comPIX_QR_UNAVAILABLEindica serviço indisponível ou recurso desabilitado para o merchant ou tipo de QR.