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

# Primeira Cobrança Pix na BukioPay

> Crie sua primeira cobrança Pix, exiba o QR Code e receba a confirmação do pagamento por webhook.

Em poucos minutos você cria sua primeira cobrança Pix e recebe a confirmação do pagamento no seu servidor.

<Steps>
  <Step title="Gere sua API Key">
    No painel da BukioPay, abra as configurações de API e gere uma chave. Ela começa com `sk_live_` e aparece por completo uma única vez — guarde em variável de ambiente.

    <Warning>
      A API Key dá acesso total à sua conta. Use apenas no servidor, nunca em código que roda no navegador ou no aplicativo.
    </Warning>
  </Step>

  <Step title="Cadastre a URL do seu webhook">
    Ainda nas configurações de API, informe a URL do seu servidor e marque o evento `payment.paid`. A confirmação do pagamento chega por webhook, não na resposta da criação da cobrança.
  </Step>

  <Step title="Crie a cobrança">
    Envie o valor em reais e os dados de quem vai pagar:

    ```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": "Primeira cobrança",
        "customer": {
          "name": "João Silva",
          "email": "joao@exemplo.com"
        }
      }'
    ```
  </Step>

  <Step title="Exiba o QR Code ao cliente">
    A resposta traz o id da cobrança, o QR Code em Base64 e o Copia e Cola:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
        "status": "PENDING",
        "amount": 50,
        "feeAmount": 2.49,
        "netAmount": 47.51,
        "payment": {
          "copyPaste": "00020126580014BR.GOV.BCB.PIX...",
          "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
        },
        "externalReference": "2IH180IE",
        "expiresAt": "2026-08-26T12:28:00.000Z"
      }
    }
    ```

    Guarde o `id` — é por ele que você reconhece a cobrança quando o webhook chegar.
  </Step>

  <Step title="Receba a confirmação">
    Quando o cliente pagar, seu servidor recebe:

    ```json theme={null}
    {
      "event": "payment.paid",
      "data": {
        "id": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
        "status": "paid",
        "amount": 50,
        "paidAt": "2026-08-26T12:00:00.000Z"
      },
      "requestId": "req_0123456789abcdef"
    }
    ```

    Valide o header `X-Webhook-Signature`, responda `2xx` em até 15 segundos e trate a entrega de forma idempotente usando o `requestId`.

    <Warning>
      Só libere o produto depois da confirmação do pagamento. Nunca entregue com base no que o navegador do cliente informa.
    </Warning>
  </Step>
</Steps>

## Valores em reais

Os valores da API são em **reais com decimais**, não em centavos. `50` é R\$ 50,00 e `19.9` é R\$ 19,90. O mínimo de uma cobrança é `1.00`.

## Repita com segurança

Se uma requisição falhar sem resposta clara, não crie outra cobrança às cegas: você pode cobrar o cliente duas vezes. Consulte a cobrança pelo `id` antes de repetir, ou use uma chave de idempotência quando o endpoint aceitar.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cobranças Pix" icon="qrcode" href="/api-reference/pix-charges/create">
    Todos os parâmetros, respostas e códigos de erro do endpoint de cobranças.
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/webhooks/eventos">
    A lista completa de eventos e como validar a assinatura.
  </Card>

  <Card title="Pedidos" icon="cart-shopping" href="/concepts/orders">
    Venda produtos do catálogo com checkout público e cálculo de total no servidor.
  </Card>

  <Card title="Saques" icon="money-bill-transfer" href="/api-reference/withdrawals/create">
    Transfira o saldo da carteira para uma chave Pix.
  </Card>
</CardGroup>


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