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

# Cobranças

> payment.created, payment.paid, payment.expired e payment.refunded: quando disparam, o corpo e o jeito certo de tratar.

| Evento | Quando | `data.status` |
| - | - | - |
| `payment.created` | a cobrança foi criada (pela API, pelo painel ou por um link de pagamento) | `pending` |
| `payment.paid` | o pagamento foi confirmado: Pix caiu, cartão aprovado ou cripto confirmada na rede | `paid` |
| `payment.expired` | passou da validade sem pagamento | `expired` |
| `payment.refunded` | um estorno (total ou parcial) foi concluído | (sem `status`) |

`data.id` é sempre o código da cobrança (`BKY-`). Valores em centavos.

## `payment.created` e `payment.expired`

```json theme={null}
{
  "id": "evt_01JA7X9K2M4Q8W3Z5F6H1N0P",
  "type": "payment.created",
  "created_at": "2026-10-08T15:00:00.120Z",
  "data": {
    "id": "BKY-7KQ2M9XP4RZT",
    "status": "pending",
    "method": "pix",
    "amount": 15000,
    "description": "Pedido 1842",
    "txid": "7kq2m9xp4rzt...",
    "expiresAt": "2026-10-08T15:30:00.000Z",
    "customerId": "0d6c1a7e-5b7f-4f3e-9b2a-1c2d3e4f5a6b",
    "paymentLinkId": "LNK-4H8W2PQ7ZM3K",
    "createdAt": "2026-10-08T15:00:00.000Z"
  }
}
```

| Campo | O que é |
| - | - |
| `method` | forma de pagamento: `pix`, `card` ou `crypto` |
| `amount` | valor da cobrança |
| `description` | a descrição que você mandou (ou `null`) |
| `txid` | identificador da cobrança na rede de pagamento |
| `expiresAt` | validade |
| `customerId` | cliente ligado, ou `null` |
| `paymentLinkId` | só em cobranças geradas por um link de pagamento |

## `payment.paid`

Os mesmos campos, mais a tarifa e os dados do pagamento:

```json theme={null}
{
  "id": "evt_01JA7XB2R6T8V0X2Z4B6D8F0H2",
  "type": "payment.paid",
  "created_at": "2026-10-08T15:04:12.318Z",
  "data": {
    "id": "BKY-7KQ2M9XP4RZT",
    "status": "paid",
    "amount": 15000,
    "fee": 50,
    "description": "Pedido 1842",
    "txid": "7kq2m9xp4rzt...",
    "expiresAt": "2026-10-08T15:30:00.000Z",
    "customerId": null,
    "paidAt": "2026-10-08T15:04:11.000Z",
    "endToEndId": "E12345678202610081504abcdef123456",
    "createdAt": "2026-10-08T15:00:00.000Z"
  }
}
```

| Campo | O que é |
| - | - |
| `fee` | tarifa descontada; o líquido é `amount - fee` |
| `paidAt` | hora em que o pagamento foi confirmado |
| `endToEndId` | só no Pix: identificador do Pix no sistema bancário (o "E2E" do comprovante) |
| `card` | só no cartão: `brand` (bandeira) e `last4` (final) |
| `availableAt` | só no cartão: quando o valor líquido entra no saldo disponível, 15 dias depois da aprovação (até lá, fica a liberar) |

No cartão, o evento chega assim:

```json theme={null}
{
  "id": "evt_01JA7XC9M2P4R6T8V0X2Z4B6D8",
  "type": "payment.paid",
  "created_at": "2026-10-08T15:06:30.410Z",
  "data": {
    "id": "BKY-8RP3N2WQ5XZA",
    "status": "paid",
    "method": "card",
    "amount": 15000,
    "fee": 1249,
    "description": "Pedido 1843",
    "paidAt": "2026-10-08T15:06:29.000Z",
    "card": { "brand": "visa", "last4": "4242" },
    "availableAt": "2026-10-23T15:06:29.000Z",
    "createdAt": "2026-10-08T15:00:00.000Z"
  }
}
```

Quem pagou no Pix (`payer`: nome, CPF mascarado e banco) está em `GET /v1/payments/{id}`.

## `payment.refunded`

```json theme={null}
{
  "id": "evt_01JA7XD4T8V0X2Z4B6D8F0H2J4",
  "type": "payment.refunded",
  "created_at": "2026-10-08T16:10:40.002Z",
  "data": {
    "id": "BKY-7KQ2M9XP4RZT",
    "refundId": "EST-9Q2W8M4Z3F7K",
    "amount": 5000,
    "endToEndId": "E12345678202610081610fedcba654321"
  }
}
```

`amount` é o valor devolvido **neste** estorno (pode ser parcial); um evento por estorno concluído. Some os estornos do mesmo `BKY-` para saber o total devolvido, ou leia `refundedAmount` em `GET /v1/payments/{id}`.

## O jeito certo de tratar

* **Libere o pedido só em `payment.paid`.** `payment.created` serve para registrar; não entregue nada por ele.
* **Confira o valor.** Compare `data.amount` com o valor do seu pedido antes de liberar.
* **Cartão aprovado já é venda.** Libere o pedido no `payment.paid` do cartão; `availableAt` diz só quando o dinheiro fica disponível para saque.
* **Pago depois de expirar acontece.** Se o seu sistema já marcou o pedido como expirado, `payment.paid` do mesmo `BKY-` reabre e libera.
* **Ordem não é garantida.** `payment.paid` pode chegar antes de `payment.created`. Trate pelo `type` e pelo `data.id`.
* **Dedupe pelo `id` do evento.** O mesmo `evt_` chega em todas as URLs e em todo reenvio.
* **Estorno parcial é comum.** Não cancele o pedido inteiro em `payment.refunded` sem olhar o `amount`.


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