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

# Cobranças PIX

> QR Code PIX, expiração, devoluções e idempotência.

Receba pagamentos gerando um QR Code PIX para compartilhar com seu cliente.

## Como funciona

1. **Gere a cobrança** — Use o endpoint de criar cobrança, que retorna o código PIX copia e cola
2. **Apresente ao cliente** — Exiba o QR Code ou o código copia e cola
3. **Teste em homologação** — No ambiente de testes, use o endpoint de simular pagamento para confirmar a cobrança manualmente
4. **Receba a confirmação** — Cadastre um endpoint de webhook assinando os eventos `pix_in.paid` e `pix_in.refunded` para receber uma notificação automática quando o pagamento for confirmado e a cada devolução (parcial ou total)
5. **Consulte quando precisar** — Verifique o status de qualquer cobrança a qualquer momento

## Status da Cobrança

| Status | Descrição |
| - | - |
| `CREATED` | Cobrança criada, aguardando geração do QR Code |
| `WAITING_PAYMENT` | QR Code gerado, aguardando pagamento do cliente |
| `PAID` | Pagamento confirmado |
| `EXPIRED` | QR Code expirou sem pagamento |
| `REFUNDED` | Pagamento devolvido por completo ao pagador |

## Devoluções

Um PIX recebido pode ser devolvido ao pagador em uma ou mais devoluções parciais. Cada devolução concluída no banco é descontada do seu saldo pelo valor que saiu da conta (a taxa da cobrança não é devolvida) e gera um evento `pix_in.refunded`: com status `PARTIALLY_REFUNDED` e `partial: true` enquanto a soma das devoluções não chega ao valor do PIX, e com status `REFUNDED` e `partial: false` na devolução que completa o valor. A cobrança continua `PAID` até completar o valor; ao completar, passa a `REFUNDED`. Veja **Devoluções no webhook** na seção Webhooks.

## Webhook de Cobranças

Quando um pagamento é confirmado ou devolvido por completo, você recebe uma notificação nos endpoints que assinam os eventos `pix_in.paid` e `pix_in.refunded`.

**Exemplo de payload:**

```json theme={null}
{
  "event": "PIX_IN_UPDATE",
  "method": "PIX_IN",
  "status": "PAYED",
  "payer": {
    "fullname": "Nome do Pagador",
    "document": "12345678900"
  },
  "pix": {
    "endToEndId": "E12345678202301011200abcdefghijkl",
    "txid": "txid-unico",
    "value": 100.00,
    "devolutions": []
  },
  "transactionId": "uuid-da-transacao",
  "idempotency": "sua-chave-idempotencia"
}
```

> A URL do endpoint deve ser publicamente acessível (HTTPS recomendado) e retornar HTTP 200 para confirmar o recebimento. Veja [Configurar webhooks](https://docs.alphagateway.com.br/webhooks/configurar.md) para detalhes de eventos e validação da assinatura HMAC.


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