Skip to main content
POST
Confirmar pagamento Pix por QR Code

Caso de uso

Use esta operação depois de revisar a prévia e confirmar o pagamento. Envie o previewId e uma idempotencyKey para evitar duplicidade em reenvios da mesma solicitação.

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. Recalcule a assinatura para cada requisição.

Requisitos

  • previewId deve ser um UUID de uma prévia ainda válida.
  • idempotencyKey deve conter de 8 a 100 caracteres ASCII imprimíveis sem espaços.
  • O merchant e o tipo de QR precisam estar habilitados após homologação.

Resposta

  • 202: pagamento entrou na fila TurboFy para processamento. Consulte o paymentId retornado para acompanhar o estado.
  • 200: replay idempotente. A resposta usa o mesmo formato público de Consultar pagamento por QR Pix.
Os dois códigos retornam paymentId, status, amountCents, feeCents, totalDebitedCents, currency, endToEndId e failureCode. endToEndId e failureCode podem ser null.

Erros

  • 409 PIX_QR_PREVIEW_EXPIRED: a prévia expirou.
  • 409 PIX_QR_PREVIEW_CHANGED: os dados da prévia mudaram.
  • 409 PIX_QR_PREVIEW_ALREADY_CONFIRMED: a prévia já foi confirmada.
  • 409 PIX_QR_CHARGE_ALREADY_CONFIRMED: a cobrança já foi confirmada.
  • 409 PIX_QR_IDEMPOTENCY_CONFLICT: a chave de idempotência foi reutilizada com outra solicitação.
  • Outros conflitos financeiros retornam os códigos canônicos de saldo ou bloqueio.
  • 422: QR não verificado ou expirado, valor divergente, tipo não disponível ou valor fora do intervalo permitido.
  • 503 PIX_QR_UNAVAILABLE: serviço indisponível ou recurso desabilitado para o merchant ou tipo de QR.

Próximo passo

Consulte Consultar pagamento por QR Pix com o paymentId para acompanhar o resultado.

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
previewId
string<uuid>
required
idempotencyKey
string
required
Required string length: 8 - 100
Pattern: ^[!-~]+$

Response

Default Response

paymentId
string<uuid>
required
status
enum<string>
required
Available options:
QUEUED,
PROCESSING,
RECONCILIATION_REQUIRED,
COMPLETED,
FAILED
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
endToEndId
string | null
required
failureCode
string | null
required
Last modified on November 12, 2026