Webhooks de Assinatura

Eventos relacionados ao ciclo de vida das assinaturas recorrentes na FastPay.

Eventos Disponíveis

Evento	Descrição
subscription.created	Enviado quando uma nova assinatura é criada
subscription.activated	Enviado quando a assinatura é ativada (primeira cobrança bem-sucedida)
subscription.renewed	Enviado quando uma cobrança recorrente é processada com sucesso
subscription.payment_failed	Enviado quando uma cobrança recorrente falha
subscription.cancelled	Enviado quando a assinatura é cancelada
subscription.paused	Enviado quando a assinatura é pausada
subscription.expired	Enviado quando a assinatura expira

Payload

subscription.created

Enviado imediatamente após a criação de uma nova assinatura.

Com validateCard: true (padrão):

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.created",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pending_card_activation",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "cardTokenId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "billingDay": 15,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Com validateCard: false (cobrança falhou):

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.created",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pending_activation",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "cardTokenId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "billingDay": 15,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

subscription.activated

Enviado quando a primeira cobrança é processada com sucesso e a assinatura se torna ativa.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.activated",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "active",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "billingDay": 15,
    "currentPeriodStart": "2024-01-15T10:30:00.000Z",
    "currentPeriodEnd": "2024-02-15T10:30:00.000Z",
    "charge": {
      "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
      "billingCycle": 1,
      "amount": 99.90,
      "currency": "BRL",
      "status": "paid"
    },
    "activatedAt": "2024-01-15T10:30:00.000Z"
  }
}

subscription.renewed

Enviado quando uma cobrança recorrente é processada com sucesso.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.renewed",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "active",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "billingDay": 15,
    "currentPeriodStart": "2024-02-15T10:30:00.000Z",
    "currentPeriodEnd": "2024-03-15T10:30:00.000Z",
    "charge": {
      "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
      "billingCycle": 2,
      "amount": 99.90,
      "currency": "BRL",
      "status": "paid"
    }
  }
}

subscription.payment_failed

Enviado quando uma cobrança recorrente falha.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.payment_failed",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "active",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "billingDay": 15,
    "charge": {
      "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
      "billingCycle": 2,
      "amount": 99.90,
      "currency": "BRL",
      "status": "failed",
      "failureReason": "insufficient_funds"
    },
    "retryCount": 1,
    "nextRetryAt": "2024-02-16T10:30:00.000Z"
  }
}

subscription.cancelled

Enviado quando a assinatura é cancelada (pelo usuário ou sistema).

Cancelamento por arrependimento (até 7 dias):

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.cancelled",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "cancelled",
    "cancellationType": "regret",
    "refunded": true,
    "refundId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "accessRevokedAt": "2024-01-16T10:30:00.000Z",
    "reason": "Cliente solicitou cancelamento",
    "cancelledAt": "2024-01-16T10:30:00.000Z"
  }
}

Cancelamento regular (após 7 dias):

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.cancelled",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "cancelled",
    "cancellationType": "regular",
    "refunded": false,
    "accessRevokedAt": "2024-02-15T10:30:00.000Z",
    "reason": "Cliente solicitou cancelamento",
    "cancelledAt": "2024-01-20T10:30:00.000Z"
  }
}

subscription.paused

Enviado quando a assinatura é pausada temporariamente.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.paused",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paused",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "pausedAt": "2024-01-20T10:30:00.000Z"
  }
}

subscription.expired

Enviado quando a assinatura expira (por falhas consecutivas ou término do plano).

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "subscription.expired",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "expired",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "expirationReason": "payment_failures",
    "expiredAt": "2024-02-20T10:30:00.000Z"
  }
}

Exemplo de Implementação

app.post('/webhooks/fastpay', (req, res) => {
  const { id, event, data } = req.body;

  switch (event) {
    case 'subscription.created':
      console.log(`Nova assinatura criada: ${data.id}`);
      break;

    case 'subscription.activated':
      console.log(`Assinatura ativada: ${data.id}`);
      // Liberar acesso ao serviço
      // Enviar email de boas-vindas
      break;

    case 'subscription.renewed':
      console.log(`Assinatura renovada: ${data.id}, ciclo ${data.charge.billingCycle}`);
      // Atualizar período de acesso
      break;

    case 'subscription.payment_failed':
      console.log(`Falha no pagamento: ${data.id}`);
      // Notificar cliente sobre falha
      // Sugerir atualização de cartão
      break;

    case 'subscription.cancelled':
      console.log(`Assinatura cancelada: ${data.id}`);
      if (data.cancellationType === 'regret') {
        // Acesso revogado imediatamente
        // Estorno já foi processado
      } else {
        // Acesso continua até accessRevokedAt
      }
      break;

    case 'subscription.paused':
      console.log(`Assinatura pausada: ${data.id}`);
      // Pausar acesso ao serviço
      break;

    case 'subscription.expired':
      console.log(`Assinatura expirada: ${data.id}`);
      // Revogar acesso ao serviço
      // Enviar email de reativação
      break;

    default:
      console.log(`Evento desconhecido: ${event}`);
  }

  res.status(200).send('OK');
});

Ciclo de Vida da Assinatura

Tipos de Cancelamento

Tipo	Condição	Estorno	Acesso
regret	Até 7 dias após criação	Automático	Revogado imediatamente
regular	Após 7 dias	Não há estorno	Continua até fim do período

Nota: O período de arrependimento de 7 dias segue a legislação brasileira de defesa do consumidor.