Eventos de Webhook

Lista completa de todos os eventos que podem ser enviados via webhook global ou callback_url.

💡 Sobre o campo id: O campo id em todos os payloads é o identificador único e opaco da ApexPy (ex: ci_k7m2p9xr4nqs). Para cobranças PIX, o campo txid também é enviado e representa o identificador imutável do sistema bancário — recomendamos armazená-lo e usá-lo como fallback de identificação.

Eventos de Cobrança

`charge.created`

Disparado quando uma nova cobrança é criada.

{
  "event": "charge.created",
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "pending",
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "pix",
    "created_at": "2025-11-28T20:30:00-03:00"
  }
}

`charge.paid`

Disparado quando uma cobrança é paga. Para PIX, inclui o txid da transação bancária.

{
  "event": "charge.paid",
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "paid",
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "pix",
    "paid_at": "2025-11-28T20:35:00-03:00"
  }
}

// Payload simplificado via callback_url (inclui txid para PIX):
{
  "id": "ci_k7m2p9xr4nqs",
  "status": "paid",
  "amount": 10000,
  "txid": "E12345678202511281234567890123456"
}

⚠️ Identificação no callback: Ao receber um evento via callback_url, use o id para localizar o pedido no seu banco de dados. Se não encontrar, use o txid como fallback (campo pix_txid ou equivalente que você armazenou na criação). Veja o guia de identificadores.

`charge.failed`

Disparado quando uma cobrança falha.

{
  "event": "charge.failed",
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "failed",
    "amount": 10000,
    "payment_method": "pix"
  }
}

`charge.refunded`

Disparado quando uma cobrança é reembolsada.

{
  "event": "charge.refunded",
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "refunded",
    "amount": 10000,
    "refunded_amount": 10000,
    "refunded_at": "2025-11-28T21:00:00-03:00"
  }
}

`charge.expired`

Disparado quando o prazo de pagamento de uma cobrança PIX expira.

{
  "event": "charge.expired",
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "expired",
    "payment_method": "pix",
    "expired_at": "2025-11-28T21:00:00-03:00"
  }
}

`charge.cancelled`

Disparado quando uma cobrança é cancelada via POST /v1/charges/{id}/cancel.

{
  "event": "charge.cancelled",
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "failed",
    "cancelled_at": "2025-11-28T20:40:00-03:00"
  }
}

Eventos de Saque

`payout.created`

Disparado quando um novo saque é criado.

{
  "event": "payout.created",
  "data": {
    "id": "co_n4hpw7zqr2xs",
    "status": "pending",
    "amount": 50000,
    "currency": "BRL"
  }
}

`payout.completed`

Disparado quando um saque é concluído com sucesso.

{
  "event": "payout.completed",
  "data": {
    "id": "co_n4hpw7zqr2xs",
    "status": "paid",
    "amount": 50000,
    "net_amount": 49500,
    "processed_at": "2025-11-28T21:00:00-03:00"
  }
}

`payout.failed`

Disparado quando um saque falha.

{
  "event": "payout.failed",
  "data": {
    "id": "co_n4hpw7zqr2xs",
    "status": "failed",
    "amount": 50000,
    "error_message": "Chave PIX não encontrada"
  }
}