Skip to main content
POST
/
payments
/
refund
Reversa y devoluciones
curl --request POST \
  --url https://your-app-domain.com/payments/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amountToRefund": 15000,
  "transactionId": "txn_abc123def456",
  "currency": "CLP",
  "reason": "Pedido cancelado",
  "orderId": "order_xyz789"
}
'
{
  "status": "completed",
  "refundId": "refund_987654",
  "refundCode": "REF-2024-001234",
  "message": "Devolución procesada exitosamente"
}
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

​
Ejemplo de solicitud - Devolución total

{
  "amountToRefund": 15000,
  "transactionId": "txn_abc123def456",
  "currency": "CLP",
  "reason": "Pedido cancelado",
  "orderId": "order_xyz789"
}

​
Ejemplo de solicitud - Devolución parcial

{
  "amountToRefund": 5000,
  "transactionId": "txn_abc123def456",
  "currency": "CLP",
  "reason": "Entrega incompleta - faltaron 2 productos",
  "orderId": "order_xyz789"
}

​
Respuesta exitosa

​
status
string
required
Estado de la devolución. Valores posibles: completed, pending, failed.
​
refundId
string
Identificador único de la devolución generado por la aplicación contenedora (opcional).
​
refundCode
string
Código de la devolución para referencia (opcional).
​
message
string
Mensaje descriptivo sobre el resultado de la devolución (opcional).

​
Ejemplo de respuesta exitosa

{
  "status": "completed",
  "refundId": "refund_987654",
  "refundCode": "REF-2024-001234",
  "message": "Devolución procesada exitosamente"
}

​
Respuesta pendiente

Si la devolución queda en estado pendiente: 
{
  "status": "pending",
  "message": "Devolución en proceso, se notificará el resultado"
}

​
Respuesta fallida

Si la devolución falla: 
{
  "status": "failed",
  "message": "Error al procesar la devolución: [descripción del error]"
}

​
Códigos de estado

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

Authorizations

​
Authorization
string
header
required

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.

Body

application/json

Propuesta de esquema de solicitud. Estructura propuesta para las devoluciones que Justo enviará a la aplicación contenedora.

​
amountToRefund
number
required

Monto a devolver al usuario. Puede ser parcial o total

Example:

15000

​
transactionId
string
required

Identificador único de la transacción original generado por Justo

Example:

"txn_abc123def456"

​
currency
string
required

Moneda de la transacción

Example:

"CLP"

​
reason
string

Razón de la devolución

Example:

"Pedido cancelado"

​
orderId
string

Identificador del pedido asociado a la transacción

Example:

"order_xyz789"

Response

La solicitud fue procesada

Propuesta de esquema de respuesta. Estructura propuesta que la aplicación contenedora debe retornar a Justo después de procesar una devolución.

​
status
enum<string>
required

Estado de la devolución

Available options:
completed,
pending,
failed
Example:

"completed"

​
refundId
string

Identificador único de la devolución generado por la aplicación contenedora

Example:

"refund_987654"

​
refundCode
string

Código de la devolución para referencia

Example:

"REF-2024-001234"

​
message
string

Mensaje descriptivo sobre el resultado de la devolución

Example:

"Devolución procesada exitosamente"