> ## 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 un pago de APM

Localpayment te permite cancelar pagos de APM pendientes mediante la integración de tu API. Esta guía describe el proceso completo de cancelación de transacciones de APM utilizando el método de cancelación directa, que solo requiere el externalId de la transacció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.

### Requisitos adicionales de cancelación:

* Rol de usuario con permisos de cancelación (consulta la documentación sobre [roles de usuario](https://docs.localpayment.com/es/docs/user-roles-and-permissions.md)).
* La transacción original debe estar en un estado que permita su cancelación.
* El `externalId` de la transacción de pago de APM que deseas cancelar.
* Completa la información del beneficiario para los reembolsos que requieren datos.

***

## Cancelación directa para pagos de APM

Las cancelaciones de pagos de APM se procesan como **cancelaciones directas**, lo que significa que solo necesitas el `externalId` de la transacción original y el parámetro `status` establecido en `CANCELLED`. El sistema detiene de inmediato cualquier procesamiento posterior del pago.

> [!WARNING]
>
> **Importante**
>
> Los pagos de APM solo se pueden cancelar mientras estén en estado pendiente o en curso. Una vez que un pago de APM se haya completado o liquidado, deberás procesar un reembolso en lugar de una cancelación.

***

## Paso 1: Cancelar el pago de APM a través de la API

Para cancelar un pago de APM, envía una solicitud `PATCH` al endpoint [Cancelar](https://docs.localpayment.com/es/reference/cancel-payin.md).

### Parámetros clave de la solicitud

La solicitud requiere varios parámetros clave:

| Parámetro | Descripción | Requerido |
| - | - | - |
| `externalId` | El externalId de la transacción original | ✅ |
| `status` | Debe establecerse en `CANCELLED` 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/transactions/{{externalId}}/status' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "CANCELLED"
  }'
```

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/cancel-payin.md) en la solicitud.

***

## Paso 2: Gestionar la respuesta

### Respuesta exitosa

Un pago de APM cancelado correctamente devuelve los detalles de confirmación:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "1c364061-1f3d-4b94-c270-bf915c22e8f5",
  "internalId": "8a9abd31-31e0-429a-32a6-cca8b9e1e536",
  "status": {
    "code": "900",
    "description": "CANCELLED",
    "detail": "The payin was cancelled"
  }
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `externalId` | Tu referencia para la transacción original. | Conciliación y seguimiento. |
| `internalId` | Identificador único de reembolso de Localpayment. | Fines de apoyo y auditoría. |
| `status.code` | Código de estado de la cancelación (`900` para una cancelación exitosa). | Monitoreo del estado. |

### Respuesta de error

Cuando falla una solicitud de cancelació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 operation"
  }
}
```

### Escenarios de errores comunes

| Error | Descripción | Solución |
| - | - | - |
| Transacción no encontrada | El `externalId` proporcionado no existe o no es válido | Verifica que el externalId sea correcto y que la transacción exista en tu historial de transacciones. |
| Estado no válido | La transacción original no se encuentra en un estado que permita su cancelación | Comprueba el estado de la transacción y asegúrate de que siga pendiente o en curso antes de intentar la cancelación |
| Permiso denegado | Tu rol de usuario carece de los permisos necesarios para realizar reembolsos. | Comunícate con el administrador de tu cuenta para otorgar los permisos de reembolso adecuados para tu rol. |
| Ya completada | La transacción ya se completó y no se puede cancelar | Procesa un reembolso en lugar de una cancelación para las transacciones completadas |
| Parámetro no válido | El parámetro `status` falta o no está establecido en `CANCELLED` | Asegúrate de que el cuerpo de la solicitud contenga `{"status": "CANCELLED"}` exactamente como se indica |

***

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

Tras iniciar una cancelación, supervisa su progreso 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 de cancelación comunes

| Código | Estado | Descripción |
| :- | :- | :- |
| `400` | `ERROR` | La solicitud de cancelación falló debido a errores de validación o parámetros no válidos. |
| `900` | `CANCELLED` | El payin se canceló 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 un pago de APM pendiente con un externalId válido.
2. **Transacción no válida**: Intenta cancelar un externalId inexistente.
3. **Ya completada**: Intenta cancelar una transacción completada.
4. **Validación de permisos**: Realiza pruebas con usuarios que tengan diferentes niveles de permisos.
5. **Parámetro de estado faltante**: Intenta la cancelación sin el campo status obligatorio.

***

## Próximos pasos

> [card] [Ver estado de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado actual de las transacciones y cancelaciones mediante la
> API de estado de transacciones.

> [card] [Procesar reembolsos](https://docs.localpayment.com/es/docs/refund-apm-payment.md)
>
> Aprende cómo procesar reembolsos de pagos de APM completados que no se pueden
> cancelar.


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