Skip to main content
POST
Pré-visualizar pagamento Pix por QR Code

Caso de uso

Use esta operação para obter os dados do QR Pix e revisar o pagamento antes de confirmá-lo.

Autenticação

  • x-client-id
  • x-client-secret
  • x-turbofy-timestamp
  • x-turbofy-signature
  • Escopo payout:write
A assinatura HMAC é obrigatória em todos os ambientes, inclusive local e teste. Assine o corpo exato que enviar.

Requisitos

  • O merchant e o tipo de QR precisam estar habilitados após homologação.
  • qrCode contém o texto lido do QR Pix.
  • qrCode aceita até 4096 caracteres.
  • amountCents, quando enviado, deve ser um inteiro positivo de até 1500000 centavos.
Corpo mínimo:

Resposta

Em 200, a resposta contém previewId, expiresAt, qrType, recipient.name, recipient.documentMasked, amountCents, feeCents, totalDebitedCents e currency. O documento do recebedor é mascarado. A moeda é BRL. O campo qrType identifica o tipo como STATIC, DYNAMIC_IMMEDIATE ou DYNAMIC_DUE_DATE. A API só aceita QR Codes cujos dados sejam coerentes e cujo merchant e tipo estejam habilitados após homologação.

Erros

  • 409: prévia expirada ou divergência encontrada ao usar a prévia.
  • 422 PIX_QR_UNVERIFIED: QR inválido, não verificado, não suportado ou ambíguo.
  • 422 PIX_QR_AMOUNT_MISMATCH: o valor enviado diverge do valor identificado no QR.
  • 422 PIX_QR_EXPIRED: o QR expirou.
  • 422 PIX_QR_TYPE_UNAVAILABLE: o tipo de QR não está disponível.
  • 422 PIX_QR_AMOUNT_OUT_OF_RANGE: o valor está fora do intervalo permitido.
  • 503 PIX_QR_UNAVAILABLE: serviço indisponível ou recurso desabilitado para o merchant ou tipo de QR.

Próximos passos

  1. Revise o recebedor, o valor, a tarifa e o total debitado na prévia.
  2. Após a confirmação do cliente, use Solicitar pagamento por QR Pix.

Authorizations

x-client-id
string
header
required

Client ID fornecido pela TurbofyPay.

x-client-secret
string
header
required

Client Secret fornecido pela TurbofyPay.

Headers

x-client-id
string
required

Identificador do integrador.

x-client-secret
string
required

Segredo de autenticacao do integrador.

x-turbofy-timestamp
string
required

Timestamp utilizado na assinatura HMAC.

x-turbofy-signature
string
required

Assinatura HMAC SHA-256 da requisicao.

Body

application/json
qrCode
string
required
Required string length: 1 - 4096
amountCents
integer
Required range: 1 <= x <= 1500000

Response

Default Response

previewId
string<uuid>
required
expiresAt
string<date-time>
required
qrType
enum<string>
required
Available options:
STATIC,
DYNAMIC_IMMEDIATE,
DYNAMIC_DUE_DATE
recipient
object
required
amountCents
integer
required
Required range: x >= 0
feeCents
integer
required
Required range: x >= 0
totalDebitedCents
integer
required
Required range: x >= 0
currency
enum<string>
required
Available options:
BRL
Last modified on November 12, 2026