Eventos · Assinaturas
Assinaturas
Ciclo de vida de assinaturas criadas via checkout de assinatura no dashboard. Use para liberar plano, suspender acesso e contabilidade.
No primeiro pagamento, disparamos
payment.paid, checkout.completed e subscription.activated. Prefira subscription.activated para liberar o plano recorrente.Eventos
| Evento | Quando | Uso |
|---|---|---|
subscription.created | Checkout de assinatura + registro pendente | Pré-cadastro no seu CRM |
| subscription.activated | Primeiro pagamento confirmado | Liberar plano / acesso |
subscription.canceled | Assinatura cancelada | Revogar acesso |
subscription.past_due | Renovação pendente ou falha | Cobrança / dunning |
Objeto subscription
| Campo | Tipo | Descrição |
|---|---|---|
id | string | UUID da assinatura |
code | string | Código sub_… |
status | string | pending | active | past_due | canceled |
amount_cents | number | Valor em centavos |
payment_method | string | null | pix, card… |
checkout_id | string | null | Checkout de origem |
customer | object | id, name, email |
payment_id | string | null | Pedido que ativou (activated) |
Exemplo de payload
{
"id": "evt_…",
"type": "subscription.activated",
"api_version": "v2",
"created": 1710000000,
"created_at": "2026-03-09T12:00:00.000Z",
"livemode": true,
"data": {
"object": {
"id": "uuid-assinatura",
"code": "sub_…",
"status": "active",
"amount_cents": 4990,
"amount_label": "R$ 49,90",
"currency": "BRL",
"payment_method": "pix",
"checkout_id": "uuid-checkout",
"customer": {
"id": "uuid-cliente",
"name": "Maria Silva",
"email": "maria@email.com"
},
"created_at": "…",
"updated_at": "…",
"payment_id": "uuid-pedido"
}
},
"source": "hyzepay"
}Fluxo recomendado
- Merchant cria checkout de assinatura →
subscription.created - Cliente paga no /pay
- HyzePay confirma PIX →
subscription.activated+payment.paid - Seu backend libera o plano com idempotência por
event.id