Reembolsos

La API de Reembolsos permite gestionar la devolución de pagos previamente procesados.
Incluye endpoints para:

• Listar reembolsos
• Obtener un reembolso específico
• Crear reembolsos completos
• Crear reembolsos parciales

---

Estructura de un Reembolso

Ejemplo de objeto de reembolso:

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

Campos

• _id: Identificador único del reembolso.
• paymentIntentId: ID de la intención de pago asociada.
• paymentId: ID del pago asociado.
• userId: ID del usuario propietario.
• receiverId: ID del cliente receptor.
• refundTo: Dirección donde se enviará el reembolso.
• amount: Monto del reembolso.
• status: Estado del reembolso.
• createdAt: Fecha de creación.
• updatedAt: Fecha de última actualización.

---

Endpoints

1. Listar reembolsos

[GET] /refunds

Retorna una lista paginada de reembolsos. Soporta filtrado y paginación.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
page	number	No	Número de página. Default: 1
pageSize	number	No	Cantidad de resultados por página. Default: 10
search	string	No	Condiciones de filtrado en formato "campo:valor,campo2:valor2"

Ejemplo de solicitud

const query = {
  page: 1,
  pageSize: 10,
  search: "receiverId:123"
};

Respuesta

{
  "refunds": [],
  "page": 1,
  "pageSize": 10,
  "totalPages": 5
}

---

2. Obtener reembolso por ID

[GET] /refunds/:id

Retorna un reembolso específico.

Parámetros de URL

• id: Identificador del reembolso.

Respuesta

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

---

3. Crear reembolso completo

[POST] /refunds

Crea un reembolso total para un pago existente.

Body

{
  "paymentId": "string",
  "refundTo": "string"
}

Parámetros

• paymentId: ID del pago a reembolsar.
• refundTo: Dirección donde se enviará el reembolso.

Respuesta

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

---

4. Crear reembolso parcial

[POST] /refunds/partial

Crea un reembolso parcial para un pago existente.

Body

{
  "paymentId": "string",
  "refundTo": "string",
  "amount": 50
}

Parámetros

• paymentId: ID del pago.
• refundTo: Dirección de destino.
• amount: Monto a reembolsar.

Respuesta

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 50,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

---

Validaciones

Las siguientes condiciones deben cumplirse:

• paymentId debe corresponder a un pago confirmado.
• refundTo debe ser una dirección Ethereum válida:
  • Debe comenzar con 0x
  • Debe tener 42 caracteres
• El monto no debe exceder el balance disponible.
• No se pueden procesar reembolsos si el pago fue retirado previamente.

---

Estados posibles

Estado	Descripción
PROCESSING	El reembolso está en proceso
COMPLETED	El reembolso fue completado
ERROR	El reembolso falló
REJECTED	El reembolso fue rechazado

---

Respuestas de error

Código	Descripción
400	Solicitud inválida o datos incorrectos
401	No autenticado
404	Reembolso o pago no encontrado
500	Error interno del servidor