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

{
  "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:

{
  "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:

{
  "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

{
  "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.