> ## 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 una suscripción

Localpayment te permite cancelar las suscripciones activas cuando los clientes ya no desean continuar con sus pagos recurrentes. Esta guía detalla el proceso para cancelar una suscripción a través de la API de Localpayment, incluyendo las opciones de cancelación inmediata y al final del período de facturación.

## Antes de comenzar

Asegúrate de tener:

> [card] [Credenciales de API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md)
>
> Credenciales API válidas y token de acceso para la autenticación.

> [card] [Configuración de la cuenta](https://docs.localpayment.com/es/docs/make-your-first-test-payment.md)
>
> Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

> [card] [Lista blanca de IP](https://docs.localpayment.com/es/docs/dashboard-whitelist-your-ips.md)
>
> Incluye en la lista blanca las direcciones IP de tus servidores para el acceso a la API.

> [card] [Endpoint del webhook](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura una URL de webhook para recibir notificaciones de pago.

***

## Paso 1: Cancelar una suscripción

Para cancelar una suscripción existente, envía una solicitud `PATCH` al endpoint [Cancelar una suscripción](https://docs.localpayment.com/es/reference/cancel-subscription.md).

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave:

| Parámetro | Descripción | Requerido |
| - | - | - |
| `status` | Debe establecerse en `CANCEL` para iniciar la cancelación | ✅ |

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `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**
>
> Una vez cancelada una suscripción, no se puede reactivar. Si el cliente desea reanudar el servicio, deberá crear una nueva suscripción.

***

## Paso 2: Gestionar la respuesta

### Respuesta exitosa

Una cancelación exitosa devuelve la confirmación de cancelación de la suscripción:

```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 respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `internalId` | Identificador único de transacción de Localpayment. | Seguimiento y soporte de transacciones. |
| `externalId` | Tu referencia única para la suscripción. | Reconciliación interna. |
| `status.code` | Código de estado de la cancelación (`903` para una cancelación exitosa). | Monitoreo del estado. |
| `status.description` | Descripción del estado legible para humanos. | Visualización de la interfaz de usuario. |
| `status.detail` | Información detallada sobre la cancelación. | Registro de auditoría. |

### Respuesta de error

Cuando falla la cancelación de una suscripción, recibirás información de error:

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

***

## Paso 3: Seguimiento del estado de la transacción

Tras cancelar una suscripción, supervisa su estado mediante estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

| Código | Estado | Descripción |
| :- | :- | :- |
| `400` | `ERROR` | La solicitud de cancelación ha fallado. |
| `903` | `CANCELLED` | La suscripción se ha cancelado correctamente. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Probando tu integración

### Escenarios de prueba

Verifica que tu integración gestione estos escenarios:

1. **Cancelación exitosa**: Cancela una suscripción activa con credenciales válidas.
2. **Suscripción ya cancelada**: Intenta cancelar una suscripción que ya ha sido cancelada.
3. **Suscripción inexistente**: Cancela una suscripción que no existe.
4. **Errores de autenticación**: Cancelar con autenticación no válida o faltante.
5. **Notificaciones de webhook**: Confirma que se han activado los webhooks de cancelación.

***

## Próximos pasos

Tras cancelar una suscripción, es posible que debas realizar acciones adicionales:

> [card] [Crear nueva suscripción](https://docs.localpayment.com/es/docs/create-a-subscription.md)
>
> Crea una nueva suscripción si el cliente desea reanudar el servicio con un
> plan o método de pago diferente.

> [card] [Configurar webhooks](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura webhooks para recibir notificaciones en tiempo real sobre los eventos de la
> suscripción.


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