> ## 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 Payout

A veces necesitas detener un Payout después de iniciarlo; esta guía describe los procedimientos de cancelación.

Si necesitas cancelar un Payout debido a un error o a un cambio en los requisitos, puedes hacerlo siempre que el Payout se encuentre en uno de los siguientes estados: **Autorización pendiente**, **Recibido**, **En espera** o **Bloqueado**.

Puedes cancelar los pagos a través del [Business Portal](https://docs.localpayment.com/es/docs/dashboard-review-payout.md) o mediante programación a través de la API.

## Requisitos previos

Antes de cancelar un Payout, asegúrate de tener:

* Una **transacción de Payout activa** con estado: `PendingAuth`, `Received`, `OnHold` o `Locked`
* Credenciales de API válidas con los permisos adecuados
* El identificador de la transacción (`externalId`)

> [!WARNING]
>
> **Importante**
>
> Una vez que un Payout pasa al estado **En proceso** o **Completado**, no se puede cancelar a través de la API. Comunícate con soporte para recibir asistencia con las transacciones procesadas.

***

## Endpoint de la API

Para cancelar un Payout, envía una solicitud `PATCH` al endpoint [Cancelar un Payout](https://docs.localpayment.com/es/reference/void-a-payout.md).

### Solicitud de cancelación de Payout

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
PATCH https://api.stage.localpayment.com/api/payout/cancel
```

### Autenticación

Incluye tu token de acceso en los encabezados de la solicitud:

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

### Parámetros clave de la solicitud

| Parámetro | Tipo | Descripción | Requerido |
| - | - | - | - |
| `externalId` | string | El identificador único de la transacción en tu sistema | ✅ |

### Ejemplo de solicitud

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payout/cancel \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7"
     }'
```

***

## Gestión de respuestas

### Respuesta de éxito

Cuando la cancelación se realiza correctamente, recibirás una respuesta con el estado actualizado:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7",
  "internalId": "3d36811d-1c02-41ea-a576-68df62c4603a",
  "status": {
    "code": "900",
    "description": "Cancelled",
    "detail": "The payout was cancelled successfully"
  }
}
```

#### Campos de respuesta clave

| Campo | Tipo | Descripción |
| - | - | - |
| `externalId` | string | El identificador de la transacción en tu sistema |
| `internalId` | string | ID interno de la transacción de Localpayment |
| `status.code` | string | Código de estado (900 = Cancelled) |
| `status.description` | string | Descripción del estado legible por humanos |
| `status.detail` | string | Detalles adicionales sobre la cancelación |

### Respuestas de error

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "Status": 404,
  "Message": "This transaction does not exist.",
  "TraceId": "dae2d1cb-7e9e-48a5-8530-980f38b31712"
}
```

***

## Mejores prácticas de implementación

* Valida siempre el estado de la transacción antes de intentar la cancelación
* Utiliza HTTPS para todas las solicitudes a la API
* Guarda los tokens de acceso de forma segura y rótalos periódicamente
* Implementa un manejo de errores y una lógica de reintento adecuados
* Registra todos los intentos de cancelación con fines de auditoría

***

## Prueba de tu implementación

Antes de implementar en producción, prueba a fondo tu lógica de cancelación:

1. **Prueba con transacciones válidas** en estados que permitan la cancelación
2. **Prueba con transacciones no válidas** para gestionar los errores correctamente
3. **Prueba los fallos de autenticación** y la caducidad del token
4. **Verifica el manejo de webhooks** si lo has implementado
5. **Prueba la limitación de velocidad** y la lógica de reintento

***

## Recursos y próximos pasos

Maximiza el éxito de tu integración con estos recursos esenciales.

> [card] [Integración de webhooks](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura notificaciones en tiempo real para las actualizaciones del estado de las transacciones.

> [card] [Portal de informes empresariales](https://docs.localpayment.com/es/docs/balance-report.md)
>
> Accede a análisis detallados, herramientas de generación de informes y funciones de conciliación.

> [card] [Monitoreo de transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes)
>
> Aprende a consultar el estado de las transacciones e implementar un seguimiento exhaustivo.

> [card] [Referencia de la API](https://docs.localpayment.com/es/reference/exchange-bulk.md)
>
> Documentación completa del endpoint con ejemplos interactivos.

> [!NOTE]
>
> **Consejo profesional**
>
> Siempre prueba tu flujo de trabajo en nuestro entorno de pruebas antes de implementarlo en producción. Esto garantiza que el manejo de errores, el procesamiento de webhooks y el seguimiento del estado funcionen correctamente en todos los escenarios.

***

> [!NOTE]
>
> **¿Necesitas ayuda?**
>
> Ponte en contacto con nuestro [equipo de soporte](mailto:support@localpayment.com) si experimentas algún problema o necesitas ayuda con la integración.


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