> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancelar uma assinatura

O Localpayment permite cancelar assinaturas ativas quando os clientes não desejam mais continuar com os pagamentos recorrentes. Este guia detalha o processo de cancelamento de uma assinatura por meio da API do Localpayment, incluindo cancelamentos imediatos e opções de cancelamento no final do período de faturamento.

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint de webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Passo 1: Cancelar uma assinatura

Para cancelar uma assinatura existente, envie uma solicitação `PATCH` para o endpoint [Cancelar uma assinatura](https://docs.localpayment.com/pt-br/reference/cancel-subscription.md).

### Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `status` | Deve ser definido como `CANCEL` para iniciar o cancelamento | ✅ |

### Exemplo de solicitação

Abaixo está um exemplo usando `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payin/subscriptions/{externalId}/status \
 		 --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data-raw '{
    "status": "CANCEL"
}'

```

> [!WARNING]
>
> **Importante**
>
> Uma vez cancelada, a assinatura não pode ser reativada. Será necessário criar uma nova assinatura caso o cliente deseje retomar o serviço.

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Um cancelamento bem-sucedido retorna a confirmação de cancelamento da assinatura:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "a2966037-52a1-4a73-9173-b682969b34ff",
    "internalId": "1ef01791-0e51-4b66-9d45-229895cd49d0",
    "status": {
        "code": "903",
        "description": "CANCELLED",
        "detail": "The subscription was canceled - merchant request"
    }
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador único de transação do Localpayment. | Rastreamento e suporte de transações. |
| `externalId` | Sua referência exclusiva para a assinatura. | Conciliação interna. |
| `status.code` | Código de status do cancelamento (`903` para cancelamento bem-sucedido). | Monitoramento de status. |
| `status.description` | Descrição do status em linguagem acessível a humanos. | Exibição da interface do usuário. |
| `status.detail` | Informações detalhadas sobre cancelamento. | Registro de auditoria. |

### Resposta de erro

Quando o cancelamento de uma assinatura falhar, você receberá as seguintes informações de erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "400",
        "description": "ERROR",
        "detail": "Invalid externalID Subscription Not Found"
    }
}
```

***

## Etapa 3: Rastrear o status da transação

Após cancelar uma assinatura, monitore o status através destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

| Código | Status | Descrição |
| :- | :- | :- |
| `400` | `ERROR` | O pedido de cancelamento falhou. |
| `903` | `CANCELLED` | A assinatura foi cancelada com sucesso. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Cancelamento bem-sucedido**: Cancele uma assinatura ativa com credenciais válidas.
2. **Assinatura já cancelada**: Tentativa de cancelar uma assinatura já cancelada.
3. **Assinatura inexistente**: Cancelar uma assinatura que não existe.
4. **Erros de autenticação**: Cancelar com autenticação inválida ou ausente.
5. **Notificações de Webhook**: Os webhooks de confirmação de cancelamento são acionados.

***

## Próximos passos

Após cancelar uma assinatura, você poderá precisar realizar ações adicionais:

> [card] [Criar nova assinatura](https://docs.localpayment.com/pt-br/docs/create-a-subscription.md)
>
> Crie uma nova assinatura se o cliente quiser retomar o serviço com um
> plano ou método de pagamento diferente.

> [card] [Configurar webhooks](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure webhooks para receber notificações em tempo real sobre eventos da
> assinatura.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.