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

# Reembolsar un pago con tarjeta

Localpayment te permite procesar reembolsos de pagos con tarjeta, lo que te permite devolver fondos a las tarjetas de crédito o débito de los clientes mediante la integración de la API y la interfaz del Business Portal. Esta guía abarca todo el proceso de reembolso para transacciones con tarjeta.

## 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 para el reembolso:

* Debes tener saldo suficiente en tu cuenta de Localpayment para cubrir el importe del reembolso.
* Rol de usuario con permisos de reembolso (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 estado `Completed`.
* El `externalId` de la transacción de pago original.

***

## Guía de implementación

Localpayment ofrece dos métodos para procesar reembolsos de tarjetas: integración mediante API para el procesamiento automatizado y Business Portal para operaciones manuales.

> [card] [Procesamiento de reembolsos mediante API](https://docs.localpayment.com/es/reference/refund-a-payin.md)
>
> Procesa reembolsos mediante programación a través de la API REST para flujos de trabajo automatizados e integración con tus sistemas.

> [card] [Procesamiento de reembolsos del Business Portal](https://docs.localpayment.com/es/docs/dashboard-create-manual-refund.md)
>
> Gestiona manualmente los reembolsos a través del Business Portal de Localpayment, que cuenta con una interfaz fácil de usar.

***

## Reembolsos directos para pagos con tarjeta

En las transacciones con tarjeta, los reembolsos se procesan como **reembolsos directos**, es decir, solo necesitas el `externalId` de la transacción original. No se requieren datos adicionales del beneficiario ni datos bancarios, ya que los fondos se devuelven a la tarjeta original utilizada para el pago.

***

## Paso 1: Procesar el reembolso a través de la API.

Para reembolsar un pago con tarjeta mediante la API, envía una solicitud `PATCH` al endpoint de [reembolso](https://docs.localpayment.com/es/reference/refund-a-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. | ✅ |

### 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/{{externalId}}/refund' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "comment": "Refund API Credit Card"
  }'
```

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

***

## Paso 2: Gestionar la respuesta

### Respuesta exitosa

Un reembolso procesado correctamente devuelve los detalles de confirmación:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "d260ae17-0978-4429-bda1-8dfed9da6c6b",
  "internalId": "53c91969-147e-4273-a659-ee5012ce9c83",
  "status": {
    "code": "902",
    "description": "REFUNDED",
    "detail": "The payin was refunded"
  }
}
```

### 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 del reembolso (`902` para un reembolso exitoso). | Monitoreo del estado. |

### Respuesta de error

Cuando falla una solicitud de reembolso, 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 |
| - | - | - |
| Fondos insuficientes | El saldo de tu cuenta de Localpayment es insuficiente para cubrir el importe del reembolso. | Agrega fondos a tu cuenta de Localpayment o espera a que se liquiden los pagos pendientes. |
| 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 está en un estado reembolsable (debe ser `Completed`) | Verifica el estado de la transacción y asegúrate de que se haya procesado correctamente antes de intentar el reembolso. |
| 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. |
| Reembolso duplicado | Intentar reembolsar una transacción que ya ha sido reembolsada. | Verifica que la transacción no haya sido reembolsada previamente consultando el estado del reembolso. |
| Cantidad no válida | Intentar un reembolso parcial cuando solo se permiten reembolsos completos. | Procesar el reembolso únicamente por el importe total de la transacción. |

***

## Reembolsos del Business Portal

Los reembolsos de tarjetas también se pueden procesar a través de la interfaz del Business Portal de Localpayment. Este método proporciona un flujo de trabajo visual para gestionar los reembolsos y es particularmente útil para:

* **Reembolsos ocasionales** que no requieren automatización mediante API.
* **Supervisión administrativa** cuando se requieren flujos de trabajo de aprobación.
* **Procesamiento rápido de reembolsos** sin necesidad de recursos de desarrollo.

Para obtener instrucciones detalladas sobre cómo procesar reembolsos a través del Business Portal, incluyendo guías paso a paso y tutoriales sobre la interfaz, consulta la [Guía de Reembolsos del Business Portal](https://docs.localpayment.com/es/docs/dashboard-create-manual-refund.md).

> [!WARNING]
>
> **Se requiere aprobación**:
>
> Todos los reembolsos iniciados a través del Business Portal de Localpayment requieren aprobación mediante el flujo de trabajo de autorización designado. Asegúrate de contar con los permisos de usuario necesarios antes de intentar realizar reembolsos a través del Business Portal.

***

## Paso 3: Seguimiento del estado del reembolso

Tras iniciar un reembolso, 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 reembolso comunes

| Código | Estado | Descripción |
| :- | :- | :- |
| `400` | `ERROR` | La solicitud de reembolso falló debido a errores de validación o parámetros no válidos. |
| `902` | `REFUNDED` | El payin se reembolsó correctamente. |

> [!NOTE]
>
> **Los reembolsos no son inmediatos para el cliente.** El monto reembolsado puede tardar varios días en aparecer en el estado de cuenta de la tarjeta del cliente después de que solicitas el reembolso. El tiempo exacto depende del proveedor de pagos y del emisor de la tarjeta.

> [!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. **Reembolso exitoso**: Procesa un reembolso con un `externalId` válido y fondos suficientes.
2. **Fondos insuficientes**: Intentar realizar un reembolso con saldo insuficiente en la cuenta.
3. **Transacción no válida**: Intenta reembolsar un `externalId` inexistente.
4. **Reembolso duplicado**: Intento de reembolsar una transacción que ya ha sido reembolsada.
5. **Validación de permisos**: Realiza pruebas con usuarios que tengan diferentes niveles de permisos.

***

## 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 los reembolsos mediante la API de
> estado de transacciones.

> [card] [Configurar webhooks](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura webhooks para recibir notificaciones en tiempo real sobre los cambios de
> estado de los reembolsos.

> [card] [Revisar los roles de usuario](https://docs.localpayment.com/es/docs/user-roles-and-permissions.md)
>
> Gestiona los permisos y roles de usuario para las funciones de procesamiento de reembolsos.


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