Pular para o conteúdo principal
DELETE
/
credit-card
/
v1
/
subscription
/
{subscriptionId}
Cancelar Assinatura
curl --request DELETE \
  --url https://api-gateway.firebanking.dev/credit-card/v1/subscription/{subscriptionId} \
  --header 'x-api-key: <api-key>'
{
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "planUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "basicValue": {
    "type": "MONTHLY",
    "valuePerMonth": 30
  },
  "startDate": "2023-12-25",
  "nextBillingDate": "2023-12-25",
  "createdAt": "2023-11-07T05:31:56Z"
}
Cancelar uma assinatura ativa. Isso interrompe todas as cobranças futuras da assinatura mas não emite reembolsos para o período de cobrança atual.

​
Parâmetros de Caminho

​
subscriptionId
string
required
O UUID da assinatura a ser cancelada

​
Comportamento do Cancelamento

​
Efeitos Imediatos

  • Mudança de status: Status da assinatura se torna cancelled
  • Cobrança para: Nenhuma cobrança futura será processada
  • Acesso mantido: Cliente mantém acesso até o período atual terminar

​
O Que Acontece com o Acesso

  • Período atual: Cliente mantém acesso até o período expirar
  • Sem reembolsos: Período de cobrança atual não é automaticamente reembolsado
  • Período de carência: Serviço continua até a próxima data de cobrança

​
Exemplo de Requisição

cURL
curl -X DELETE "https://api-gateway.firebanking.com.br/credit-card/v1/subscription/subscription-uuid-12345" \
  -H "x-api-key: SUA_CHAVE_DE_API"

​
Exemplo de Resposta

Resposta
{
  "uuid": "subscription-uuid-12345",
  "status": "cancelled",
  "planUuid": "plan-uuid-12345",
  "basicValue": {
    "type": "MONTHLY",
    "valuePerMonth": 30
  },
  "buyerUuid": "buyer-uuid-67890",
  "startDate": "2024-02-01",
  "cancelledAt": "2024-02-15T14:30:00Z",
  "accessExpiresAt": "2024-03-01T00:00:00Z",
  "cancellationReason": "customer_request",
  "remainingValue": 15
}

​
Campos da Resposta

​
cancelledAt
string
Timestamp quando a assinatura foi cancelada
​
accessExpiresAt
string
Quando o acesso do cliente expirará
​
cancellationReason
string
Motivo do cancelamento (customer_request, payment_failed, etc.)
​
remainingValue
integer
Valor não utilizado em reais para o período de cobrança atual

​
Tipos de Cancelamento

​
Iniciado pelo Cliente

  • Cliente solicita cancelamento
  • Normalmente efetivo no fim do período atual
  • Pode qualificar para reembolsos rateados

​
Administrativo

  • Comerciante cancela assinatura
  • Pode ser devido a violações de política
  • Término imediato de acesso possível

​
Iniciado pelo Sistema

  • Falhas de pagamento excedem limites de retry
  • Fechamento ou suspensão de conta
  • Gerenciamento automatizado de risco

​
Tratamento de Reembolso

Cancelamento não emite automaticamente reembolsos. Trate reembolsos separadamente usando os endpoints de estorno de pagamento.

​
Reembolsos Rateados

Se você quiser emitir reembolsos rateados:
  1. Calcular dias não utilizados no período de cobrança atual
  2. Determinar valor do reembolso baseado no uso diário
  3. Emitir reembolso usando a API de estorno de pagamento
  4. Atualizar cliente sobre o processamento do reembolso

​
Política de Não Reembolso

Muitos negócios operam com:
  • Acesso até fim do período
  • Sem reembolsos para períodos parciais
  • Termos claros comunicados antecipadamente

​
Pós-Cancelamento

​
Comunicação com Cliente

  • Email de confirmação sobre cancelamento
  • Data de expiração de acesso claramente comunicada
  • Opções de reativação se aplicável

​
Tratamento de Dados

  • Dados da assinatura permanecem no sistema para relatórios
  • Métodos de pagamento podem ser mantidos ou removidos
  • Histórico do cliente preservado para suporte

​
Reativação

Assinaturas canceladas não podem ser reativadas diretamente. Para restaurar serviço:
  1. Criar nova assinatura com os mesmos ou diferentes termos
  2. Usar comprador existente e métodos de pagamento se disponíveis
  3. Aplicar descontos aplicáveis para clientes que retornam

​
Múltiplas Assinaturas

Se cancelando assinaturas específicas para clientes com múltiplos planos:
Cancelar Plano Específico
curl -X DELETE "https://api-gateway.firebanking.com.br/credit-card/v1/subscription/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: SUA_CHAVE_DE_API"
Cada assinatura tem seu próprio UUID. Certifique-se de que está cancelando a assinatura correta para clientes com múltiplos planos.

​
Notificações de Webhook

Cancelamento dispara eventos de webhook:
  • subscription.cancelled
  • subscription.access_expired (quando acesso expira)

​
Melhores Práticas

  1. Confirmar intenção - Verificar duas vezes requisições de cancelamento
  2. Oferecer alternativas - Apresentar opções de downgrade antes de cancelar
  3. Salvar feedback - Coletar motivos de cancelamento para melhoria
  4. Comunicação clara - Explicar o que acontece após cancelamento
  5. Reativação fácil - Tornar simples para clientes retornarem
  6. Monitorar métricas - Rastrear taxas e motivos de cancelamento

​
Cenários de Erro

  • Assinatura não encontrada: UUID de assinatura inválido
  • Já cancelada: Assinatura já está com status cancelado
  • Permissão negada: Chave de API não tem acesso à assinatura
  • Status inválido: Alguns status podem prevenir cancelamento

​
Casos de Uso

Solicitação do Cliente

Cliente quer cancelar serviço

Problemas de Pagamento

Múltiplas tentativas de pagamento falhadas

Violação de Política

Violações dos termos de serviço

Fechamento de Conta

Cliente fechando conta inteira

Authorizations

​
x-api-key
string
header
required

Chave de API para autenticação

Path Parameters

​
subscriptionId
string<uuid>
required

ID da assinatura a cancelar

Response

200 - application/json

Assinatura cancelada com sucesso

​
uuid
string<uuid>

UUID da assinatura

​
status
string

Status da assinatura

​
planUuid
string<uuid>

UUID do plano

​
basicValue
object
​
startDate
string<date>

Data de início

​
nextBillingDate
string<date>

Próxima data de cobrança

​
createdAt
string<date-time>

Timestamp de criação