> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getjusto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reversa y devoluciones
> Endpoint para procesar devoluciones parciales o totales de transacciones
Este endpoint permite a Justo realizar devoluciones y reversas de transacciones. Desde Justo contamos con un sistema de reversas y devoluciones que permite gestionar incidencias en pedidos, como entregas incompletas o fallidas debido a problemas diversos.
Este endpoint debe soportar tanto devoluciones parciales (por entregas incompletas) como reversas/devoluciones totales.
## Cuerpo de la solicitud
Monto a devolver al usuario. Puede ser parcial o total.
Identificador único de la transacción original generado por Justo.
Moneda de la transacción (ej: "CLP", "USD", "MXN").
Razón de la devolución (opcional). Ej: "Entrega incompleta", "Pedido cancelado", "Producto defectuoso".
Identificador del pedido asociado a la transacción (opcional).
## Ejemplo de solicitud - Devolución total
```json theme={null}
{
"amountToRefund": 15000,
"transactionId": "txn_abc123def456",
"currency": "CLP",
"reason": "Pedido cancelado",
"orderId": "order_xyz789"
}
```
## Ejemplo de solicitud - Devolución parcial
```json theme={null}
{
"amountToRefund": 5000,
"transactionId": "txn_abc123def456",
"currency": "CLP",
"reason": "Entrega incompleta - faltaron 2 productos",
"orderId": "order_xyz789"
}
```
## Respuesta exitosa
Estado de la devolución. Valores posibles: `completed`, `pending`, `failed`.
Identificador único de la devolución generado por la aplicación contenedora (opcional).
Código de la devolución para referencia (opcional).
Mensaje descriptivo sobre el resultado de la devolución (opcional).
## Ejemplo de respuesta exitosa
```json theme={null}
{
"status": "completed",
"refundId": "refund_987654",
"refundCode": "REF-2024-001234",
"message": "Devolución procesada exitosamente"
}
```
## Respuesta pendiente
Si la devolución queda en estado pendiente:
```json theme={null}
{
"status": "pending",
"message": "Devolución en proceso, se notificará el resultado"
}
```
## Respuesta fallida
Si la devolución falla:
```json theme={null}
{
"status": "failed",
"message": "Error al procesar la devolución: [descripción del error]"
}
```
## Códigos de estado
La solicitud fue procesada. Revisar el campo `status` en el cuerpo de la respuesta para conocer el resultado.
Error de validación. Los datos enviados no son válidos o la devolución no puede ser procesada (ej: monto mayor al original, transacción no encontrada).
No autorizado. El token de autenticación es inválido o ha expirado.
Error interno del servidor de la aplicación contenedora.
## Notas importantes
Es responsabilidad de la aplicación contenedora validar que la suma de las devoluciones no exceda el valor total de la transacción original. Aunque Justo cuenta con un mecanismo que verifica esto, la aplicación debe implementar esta validación también.
Durante este paso, la aplicación contenedora debe:
* Revertir el monto de la cuenta del destinatario (comercio)
* Acreditar el monto en la cuenta del usuario
* Generar un registro de la devolución para auditoría
* Mantener un historial de todas las devoluciones realizadas sobre una transacción
En caso de no contar con un sistema de reversas y utilizar el formato de recaudación centralizada de Justo, será Justo quien solicite al cliente final los datos necesarios para realizar la devolución de manera manual, proceso que se ejecutará una vez por semana.
Para los casos en que un tercero gestione la recaudación, este será responsable de realizar las devoluciones directamente, eximiendo a Justo de toda responsabilidad en dicho proceso.
## Casos de uso
### Devolución total
Cuando un pedido es cancelado completamente o no puede ser entregado, se debe devolver el monto total de la transacción.
### Devolución parcial
Cuando un pedido tiene problemas parciales (ej: faltan algunos productos, productos defectuosos), se puede realizar una devolución por el monto correspondiente a los items afectados.
## OpenAPI
````yaml post /payments/refund
openapi: 3.0.0
info:
title: Embedded Ordering API
version: 1.0.0
description: >
**Propuesta de API que debe ser implementada por la aplicación contenedora**
Este documento describe una propuesta de los endpoints que las marcas
(aplicaciones contenedoras)
deben implementar para que Justo pueda operar e integrar el marketplace
dentro de sus aplicaciones.
Los endpoints, esquemas y especificaciones aquí descritos son una propuesta
y pueden adaptarse
a los requerimientos específicos de cada sistema, siempre y cuando se
mantenga la funcionalidad
necesaria para que Justo pueda realizar las operaciones requeridas.
servers:
- url: https://your-app-domain.com
description: >-
Servidor de la aplicación contenedora (debe ser configurado por cada
implementación)
security: []
tags:
- name: auth
description: Endpoints de autenticación y onboarding
- name: payments
description: Endpoints de pagos
- name: notifications
description: Webhooks de notificaciones
paths:
/payments/refund:
post:
tags:
- payments
summary: Reversa y devoluciones
description: >
**Propuesta de endpoint** para procesar devoluciones parciales o totales
de transacciones.
Este endpoint debe ser implementado por la aplicación contenedora para
que Justo pueda realizar
devoluciones y reversas de transacciones cuando sea necesario.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefundPaymentRequest'
responses:
'200':
description: La solicitud fue procesada
content:
application/json:
schema:
$ref: '#/components/schemas/RefundPaymentResponse'
'400':
description: >-
Error de validación. Los datos enviados no son válidos o la
devolución no puede ser procesada
'401':
description: No autorizado. El token de autenticación es inválido o ha expirado
'500':
description: Error interno del servidor de la aplicación contenedora
security:
- bearerAuth: []
components:
schemas:
RefundPaymentRequest:
type: object
description: >
**Propuesta de esquema de solicitud.** Estructura propuesta para las
devoluciones que
Justo enviará a la aplicación contenedora.
required:
- amountToRefund
- transactionId
- currency
properties:
amountToRefund:
type: number
description: Monto a devolver al usuario. Puede ser parcial o total
example: 15000
transactionId:
type: string
description: Identificador único de la transacción original generado por Justo
example: txn_abc123def456
currency:
type: string
description: Moneda de la transacción
example: CLP
reason:
type: string
description: Razón de la devolución
example: Pedido cancelado
orderId:
type: string
description: Identificador del pedido asociado a la transacción
example: order_xyz789
RefundPaymentResponse:
type: object
description: >
**Propuesta de esquema de respuesta.** Estructura propuesta que la
aplicación contenedora debe
retornar a Justo después de procesar una devolución.
required:
- status
properties:
status:
type: string
enum:
- completed
- pending
- failed
description: Estado de la devolución
example: completed
refundId:
type: string
description: >-
Identificador único de la devolución generado por la aplicación
contenedora
example: refund_987654
refundCode:
type: string
description: Código de la devolución para referencia
example: REF-2024-001234
message:
type: string
description: Mensaje descriptivo sobre el resultado de la devolución
example: Devolución procesada exitosamente
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
**Propuesta de esquema de autenticación.** Token de autenticación que
debe ser coordinado entre
Justo y la aplicación contenedora. El mecanismo específico debe
acordarse entre ambos equipos técnicos.
````