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

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

> Entenda o ciclo de vida de uma transação PIX na BukioPay: status PENDING, COMPLETED, CANCELLED e FAILED, campos da resposta, exibição do QR Code e boas práticas.

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:

```text theme={null}
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`.

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

## 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 é:

```text theme={null}
PENDING → COMPLETED
```

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

```text theme={null}
PENDING → CANCELLED
```

Quando a criação falha definitivamente:

```text theme={null}
PENDING → FAILED
```

<Warning>
  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`.
</Warning>

## 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`. |

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

## Exemplo de resposta

```json theme={null}
{
  "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:

```html theme={null}
<img
  src="data:image/png;base64,iVBORw0KGgo..."
  alt="QR Code PIX"
/>
```

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

```html theme={null}
<img
  src="data:image/png;base64,iVBORw0KGgo..."
  alt="QR Code PIX"
/>
```

<Note>
  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.
</Note>

## 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:

```html theme={null}
<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`:

```text theme={null}
GET /api/v1/transactions/:id
```

Exemplo:

```bash theme={null}
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:

```text theme={null}
DELETE /api/v1/transactions/:id
```

Exemplo:

```bash theme={null}
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`.

<Warning>
  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.
</Warning>

## 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. |

<Note>
  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.
</Note>

## Boas práticas

<AccordionGroup>
  <Accordion title="Confirme o pagamento antes de liberar o pedido" icon="circle-check">
    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`.
  </Accordion>

  <Accordion title="Processe webhooks de forma idempotente" icon="shield">
    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.
  </Accordion>

  <Accordion title="Não faça polling contínuo" icon="clock">
    Utilize webhooks para receber atualizações em tempo real. Consulte o endpoint de detalhes apenas quando precisar conferir ou reconciliar uma transação.
  </Accordion>

  <Accordion title="Não reutilize um código cancelado ou expirado" icon="ban">
    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.
  </Accordion>

  <Accordion title="Não duplique uma criação com resultado incerto" icon="triangle-exclamation">
    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.
  </Accordion>
</AccordionGroup>

***

Pronto para começar? Consulte a referência completa dos endpoints de Transações PIX.

[Ver endpoint para criar uma Transação PIX →](/api-reference/transactions/create)


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