Transações PIX na BukioPay: Ciclo de Vida e QR Code

A BukioPay utiliza transações do tipo PIX_IN para processar cobranças PIX de forma simples e segura. Esta página explica o ciclo de vida completo de uma transação PIX, incluindo as mudanças de status, os campos mais importantes da resposta e as melhores práticas para integrar os pagamentos.

O que é uma transação PIX

Uma transação PIX_IN é uma solicitação de pagamento que gera dois recursos para o cliente:

QR Code — imagem que pode ser escaneada pelo aplicativo bancário.
Código Copia e Cola — código de texto que pode ser inserido manualmente no aplicativo bancário.

A transação é criada usando:

POST /api/v1/transactions

No corpo da requisição, envie type: "PIX_IN". Após o pagamento, a confirmação é recebida pela BukioPay e o status da transação é atualizado para COMPLETED.

Pagamentos PIX no Brasil normalmente são confirmados em segundos e funcionam 24 horas por dia, 7 dias por semana, incluindo feriados.

Ciclo de vida

Toda transação PIX possui um status que representa sua situação atual.

Status	Descrição
`PENDING`	Transação criada e aguardando pagamento ou reconciliação.
`COMPLETED`	Pagamento confirmado com sucesso.
`CANCELLED`	Transação cancelada antes da confirmação do pagamento.
`FAILED`	Não foi possível criar ou processar definitivamente a cobrança PIX.

O fluxo mais comum é:

PENDING → COMPLETED

Quando uma cobrança não paga é cancelada:

PENDING → CANCELLED

Quando a criação falha definitivamente:

PENDING → FAILED

Nunca libere um produto, serviço ou acesso apenas porque a transação foi criada. Libere somente após receber o evento payment.paid ou confirmar que o status da transação é COMPLETED.

Campos importantes

Ao criar ou consultar uma transação, a API retorna os seguintes campos principais dentro do objeto data:

Campo	Tipo	Descrição
`id`	`string`	UUID interno da transação. Use este valor para consultar ou cancelar a transação.
`type`	`string`	Tipo da transação. Para cobranças PIX, o valor é `PIX_IN`.
`status`	`string`	Status atual: `PENDING`, `COMPLETED`, `CANCELLED` ou `FAILED`.
`amount`	`number`	Valor original da cobrança em reais.
`feeAmount`	`number`	Taxa de processamento aplicada à transação.
`netAmount`	`number`	Valor líquido calculado após a taxa, salvo quando ela é coberta pelo pagador.
`coverFee`	`boolean`	Indica se a taxa foi repassada ao pagador.
`has_products`	`boolean`	Indica se a transação representa uma cobrança associada a produtos.
`description`	`string`	Descrição da transação.
`customer`	`object`	Dados do cliente ou pagador.
`payment.copyPaste`	`string`	Código PIX Copia e Cola.
`payment.qrCodeBase64`	`string`	Imagem PNG do QR Code em base64 puro.
`payment.qrcodeUrl`	`string`	Data URL completa da imagem, pronta para uso em uma tag `img`.
`externalReference`	`string`	Referência pública curta utilizada para identificação e rastreabilidade.
`expiresAt`	`string`	Data de expiração informada pelo processador. Pode ser `null`.
`createdAt`	`string`	Data e hora de criação no formato ISO 8601.
`paidAt`	`string`	Data e hora da confirmação do pagamento. Pode ser `null`.

Os endpoints de consulta e cancelamento exigem o UUID interno retornado no campo data.id. Não utilize externalReference como parâmetro :id.

Exemplo de resposta

{
  "success": true,
  "message": "Transação PIX criada com sucesso",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PIX_IN",
    "status": "PENDING",
    "amount": 49.90,
    "feeAmount": 3.34,
    "netAmount": 46.56,
    "has_products": false,
    "coverFee": false,
    "currency": "BRL",
    "description": "Pagamento de serviço",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com"
    },
    "payment": {
      "copyPaste": "00020101021226820014br.gov.bcb.pix...",
      "qrCodeBase64": "iVBORw0KGgo...",
      "qrcodeUrl": "data:image/png;base64,iVBORw0KGgo..."
    },
    "externalReference": "A1B2C3D4",
    "expiresAt": "2026-08-15T15:30:00.000Z",
    "createdAt": "2026-08-15T14:30:00.000Z"
  },
  "requestId": "req_A1B2C3D4"
}

Exibindo o QR Code

O campo payment.qrcodeUrl contém uma Data URL completa e pode ser utilizado diretamente no atributo src de uma imagem:

<img
  src="data:image/png;base64,iVBORw0KGgo..."
  alt="QR Code PIX"
/>

Se você utilizar payment.qrCodeBase64, adicione o prefixo data:image/png;base64,:

<img
  src="data:image/png;base64,iVBORw0KGgo..."
  alt="QR Code PIX"
/>

Quando include_qr_image for false na criação da transação, os campos relacionados à imagem podem ser null. O campo payment.copyPaste continua disponível para pagamento.

Exibindo o código Copia e Cola

Para facilitar o pagamento, exiba o código em um campo somente leitura com um botão de cópia:

<input
  type="text"
  value="00020101021226820014br.gov.bcb.pix..."
  readonly
  id="pix-copy-paste"
/>

<button
  type="button"
  onclick="navigator.clipboard.writeText(document.getElementById('pix-copy-paste').value)"
>
  Copiar código PIX
</button>

Consultando uma transação

Para consultar uma transação específica, utilize o UUID interno retornado em data.id:

GET /api/v1/transactions/:id

Exemplo:

curl -X GET 'https://api.bukiopay.com/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer sk_live_sua_api_key'

A API Key precisa ter o escopo transaction.verify.

Cancelando uma transação

Para cancelar uma transação que ainda não foi concluída, utilize:

DELETE /api/v1/transactions/:id

Exemplo:

curl -X DELETE 'https://api.bukiopay.com/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer sk_live_sua_api_key'

A API Key precisa ter o escopo transaction.create.

Não é possível cancelar uma transação com status COMPLETED. O cancelamento também não representa o estorno de um pagamento concluído.

Confirmação por webhook

Utilize webhooks para receber atualizações em tempo real sobre a transação. Os principais eventos são:

Evento	Descrição
`payment.created`	A cobrança PIX foi criada.
`payment.paid`	O pagamento foi confirmado.
`payment.failed`	A criação ou o processamento falhou definitivamente.
`payment.pix.expired`	O código PIX expirou.

Use o evento payment.paid como forma principal de confirmação. A consulta por GET /api/v1/transactions/:id deve ser utilizada para conferência e reconciliação, não para polling contínuo.

Boas práticas

Confirme o pagamento antes de liberar o pedido

Nunca libere um produto, serviço ou acesso apenas porque a transação foi criada. Aguarde o evento payment.paid ou confirme que o status retornado por GET /api/v1/transactions/:id é COMPLETED.

Processe webhooks de forma idempotente

O mesmo evento pode ser entregue novamente. Registre o identificador da entrega e ignore reprocessamentos para evitar liberar o mesmo pedido mais de uma vez.

Não faça polling contínuo

Utilize webhooks para receber atualizações em tempo real. Consulte o endpoint de detalhes apenas quando precisar conferir ou reconciliar uma transação.

Não reutilize um código cancelado ou expirado

Após o cancelamento ou a expiração, não exiba novamente o mesmo código Copia e Cola. Crie uma nova transação para gerar um novo pagamento.

Não duplique uma criação com resultado incerto

Se a criação retornar PaymentCreationUnknown, a cobrança pode ter sido criada e permanecerá em reconciliação. Consulte a transação retornada em data.id e não crie outra imediatamente.

Pronto para começar? Consulte a referência completa dos endpoints de Transações PIX. Ver endpoint para criar uma Transação PIX →

Introdução

Conceitos

Transações PIX na BukioPay: Ciclo de Vida e QR Code

O que é uma transação PIX

Ciclo de vida

Campos importantes

Exemplo de resposta

Exibindo o QR Code

Exibindo o código Copia e Cola

Consultando uma transação

Cancelando uma transação

Confirmação por webhook

Boas práticas

​O que é uma transação PIX

​Ciclo de vida

​Campos importantes

​Exemplo de resposta

​Exibindo o QR Code

​Exibindo o código Copia e Cola

​Consultando uma transação

​Cancelando uma transação

​Confirmação por webhook

​Boas práticas

O que é uma transação PIX

Ciclo de vida

Campos importantes

Exemplo de resposta

Exibindo o QR Code

Exibindo o código Copia e Cola

Consultando uma transação

Cancelando uma transação

Confirmação por webhook

Boas práticas