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

# Criar Cobrança

> Cria uma cobrança Pix avulsa e retorna o QR Code e o código Copia e Cola. Valor em reais, mínimo de R$ 1,00.

Cria uma cobrança Pix sem produtos vinculados e devolve o QR Code e o Copia e Cola para o cliente pagar.

**Método:** `POST /api/v1/transactions`

**Autenticação:** Obrigatória — inclua o header `Authorization: Bearer sk_live_sua_api_key`.

<Note>
  Para vender produtos do catálogo, use `POST /api/v1/orders` em vez deste endpoint.
</Note>

## Antes de começar

Cadastre a URL do seu servidor nas configurações de API do painel e marque o evento `payment.paid`. A confirmação do pagamento chega por webhook, não na resposta desta chamada. Sem isso, você cria a cobrança mas não fica sabendo quando o cliente paga.

## Parâmetros do corpo

<ParamField body="type" type="string" required>
  Use `PIX_IN`.
</ParamField>

<ParamField body="amount" type="number" required>
  Valor **em reais**, com decimais. Mínimo de `1.00`. Exemplo: `50` = R\$50,00 e `19.9` = R\$19,90.
</ParamField>

<ParamField body="description" type="string">
  Descrição da cobrança.
</ParamField>

<ParamField body="customer" type="object">
  Dados de quem vai pagar, com `name`, `email` e `document` (CPF ou CNPJ).
</ParamField>

<ParamField body="include_qr_image" default="true" type="boolean">
  Envie `false` para receber somente o Copia e Cola, sem a imagem do QR Code.
</ParamField>

## Exemplo de requisição

O corpo não leva URL de webhook: a cobrança usa a URL já cadastrada na sua api\_key.

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/transactions' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "PIX_IN",
    "amount": 50,
    "description": "Mensalidade de agosto",
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com"
    }
  }'
```

A resposta traz o QR Code e o status `PENDING`. O aviso de que o cliente pagou chega depois, no seu webhook — veja [Receber o aviso de pagamento](#receber-o-aviso-de-pagamento).

## Resposta

```json theme={null}
{
  "success": true,
  "message": "Transação PIX criada com sucesso",
  "data": {
    "id": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
    "type": "PIX_IN",
    "status": "PENDING",
    "amount": 50,
    "feeAmount": 2.49,
    "netAmount": 47.51,
    "coverFee": false,
    "currency": "BRL",
    "description": "Mensalidade de agosto",
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com"
    },
    "payment": {
      "copyPaste": "00020126580014BR.GOV.BCB.PIX...",
      "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
    },
    "externalReference": "2IH180IE",
    "expiresAt": "2026-08-26T12:28:00.000Z",
    "createdAt": "2026-08-26T11:58:00.000Z"
  },
  "requestId": "req_a1b2c3d4"
}
```

## Valores e taxa

<ResponseField name="amount" type="number">
  Valor da venda, em reais.
</ResponseField>

<ResponseField name="feeAmount" type="number">
  Taxa da plataforma sobre a venda.
</ResponseField>

<ResponseField name="netAmount" type="number">
  O que entra na sua carteira.
</ResponseField>

<ResponseField name="coverFee" type="boolean">
  `true` quando a loja repassa a taxa ao cliente. Nesse caso o cliente paga `amount + feeAmount` e você recebe o valor cheio.
</ResponseField>

## Confirmação pendente

Se a API responder `502` com `code: "PaymentPendingConfirmation"`, a cobrança **pode** ter sido criada. Consulte a transação pelo `id` antes de tentar de novo, para não cobrar o cliente duas vezes. O campo `retryable` indica se é seguro repetir.

## Confirmar o pagamento

O Pix é confirmado em segundos, mas a confirmação chega ao seu sistema pelo webhook, não na resposta desta chamada. A cobrança nasce como `PENDING`.

<Warning>
  Nunca libere o produto com base no que o navegador do cliente informa. Espere o webhook ou consulte a cobrança pela API.
</Warning>

### Receber o aviso de pagamento

Com a URL cadastrada e o evento `payment.paid` marcado, você recebe no seu servidor:

```json theme={null}
{
  "event": "payment.paid",
  "data": {
    "id": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
    "type": "PIX_IN",
    "status": "paid",
    "amount": 50,
    "currency": "BRL",
    "hasProducts": false,
    "externalReference": "2IH180IE",
    "paidAt": "2026-08-26T12:00:00.000Z"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-26T12:00:01.000Z"
}
```

O `data.id` é o mesmo id que esta chamada devolveu, então use-o para achar a cobrança no seu banco. O `externalReference` serve para conciliação.

<Steps>
  <Step title="Valide a assinatura">
    Confira o header `X-Webhook-Signature` antes de confiar no conteúdo. Veja [Validar a assinatura](/api-reference/webhooks/assinatura).
  </Step>

  <Step title="Responda 2xx rápido">
    O tempo limite é de 15 segundos. Se o processamento for demorado, enfileire e responda antes.
  </Step>

  <Step title="Trate como idempotente">
    Use `requestId` como chave para não processar a mesma entrega duas vezes.
  </Step>
</Steps>

Vale assinar também `payment.failed` e `payment.pix.expired`, para liberar o carrinho quando a cobrança não for paga. A lista completa está em [Eventos](/api-reference/webhooks/eventos).

### Sem webhook

Dá para consultar `GET /api/v1/transactions/:id` e verificar se o `status` virou `COMPLETED`. Serve para conciliação, mas não substitui o webhook: consultar em laço gasta requisição do seu limite e atrasa a entrega ao cliente.


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