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"
}
'

import requests

url = "https://your-app-domain.com/payments/refund"

payload = {
    "amountToRefund": 15000,
    "transactionId": "txn_abc123def456",
    "currency": "CLP",
    "reason": "Pedido cancelado",
    "orderId": "order_xyz789"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amountToRefund: 15000,
    transactionId: 'txn_abc123def456',
    currency: 'CLP',
    reason: 'Pedido cancelado',
    orderId: 'order_xyz789'
  })
};

fetch('https://your-app-domain.com/payments/refund', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://your-app-domain.com/payments/refund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amountToRefund' => 15000,
    'transactionId' => 'txn_abc123def456',
    'currency' => 'CLP',
    'reason' => 'Pedido cancelado',
    'orderId' => 'order_xyz789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://your-app-domain.com/payments/refund"

	payload := strings.NewReader("{\n  \"amountToRefund\": 15000,\n  \"transactionId\": \"txn_abc123def456\",\n  \"currency\": \"CLP\",\n  \"reason\": \"Pedido cancelado\",\n  \"orderId\": \"order_xyz789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://your-app-domain.com/payments/refund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amountToRefund\": 15000,\n  \"transactionId\": \"txn_abc123def456\",\n  \"currency\": \"CLP\",\n  \"reason\": \"Pedido cancelado\",\n  \"orderId\": \"order_xyz789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://your-app-domain.com/payments/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amountToRefund\": 15000,\n  \"transactionId\": \"txn_abc123def456\",\n  \"currency\": \"CLP\",\n  \"reason\": \"Pedido cancelado\",\n  \"orderId\": \"order_xyz789\"\n}"

response = http.request(request)
puts response.read_body

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

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"
}
'

import requests

url = "https://your-app-domain.com/payments/refund"

payload = {
    "amountToRefund": 15000,
    "transactionId": "txn_abc123def456",
    "currency": "CLP",
    "reason": "Pedido cancelado",
    "orderId": "order_xyz789"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amountToRefund: 15000,
    transactionId: 'txn_abc123def456',
    currency: 'CLP',
    reason: 'Pedido cancelado',
    orderId: 'order_xyz789'
  })
};

fetch('https://your-app-domain.com/payments/refund', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://your-app-domain.com/payments/refund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amountToRefund' => 15000,
    'transactionId' => 'txn_abc123def456',
    'currency' => 'CLP',
    'reason' => 'Pedido cancelado',
    'orderId' => 'order_xyz789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://your-app-domain.com/payments/refund"

	payload := strings.NewReader("{\n  \"amountToRefund\": 15000,\n  \"transactionId\": \"txn_abc123def456\",\n  \"currency\": \"CLP\",\n  \"reason\": \"Pedido cancelado\",\n  \"orderId\": \"order_xyz789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://your-app-domain.com/payments/refund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amountToRefund\": 15000,\n  \"transactionId\": \"txn_abc123def456\",\n  \"currency\": \"CLP\",\n  \"reason\": \"Pedido cancelado\",\n  \"orderId\": \"order_xyz789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://your-app-domain.com/payments/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amountToRefund\": 15000,\n  \"transactionId\": \"txn_abc123def456\",\n  \"currency\": \"CLP\",\n  \"reason\": \"Pedido cancelado\",\n  \"orderId\": \"order_xyz789\"\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

Estado de la devolución. Valores posibles: completed, pending, failed.

string

Identificador único de la devolución generado por la aplicación contenedora (opcional).

string

Código de la devolución para referencia (opcional).

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"

​Cuerpo de la solicitud

​Ejemplo de solicitud - Devolución total

​Ejemplo de solicitud - Devolución parcial

​Respuesta exitosa

​Ejemplo de respuesta exitosa

​Respuesta pendiente

​Respuesta fallida

​Códigos de estado

​Notas importantes

​Casos de uso

​Devolución total

​Devolución parcial

Authorizations

Body

Response

Cuerpo de la solicitud

Ejemplo de solicitud - Devolución total

Ejemplo de solicitud - Devolución parcial

Respuesta exitosa

Ejemplo de respuesta exitosa

Respuesta pendiente

Respuesta fallida

Códigos de estado

Notas importantes

Casos de uso

Devolución total

Devolución parcial