Devolver un pago

API Cloud soporta la devolución de fondos a un cliente a través de dos operaciones distintas. Elegir el método correcto depende de si el cliente está físicamente presente con su tarjeta o si estás procesando una devolución administrativa en remoto.

Método 1: Devolución referenciada (sin tarjeta)

Este es el método más común para devoluciones administrativas. Te permite devolver una transacción de forma programática utilizando el ID de pedido original (pedidoBase), sin requerir que el cliente inserte su tarjeta en el terminal.

• Endpoint: /devolucion
• Método: POST
• Caso de uso: Devoluciones de back-office, devoluciones de comercio electrónico o corrección de errores después de que el cliente se haya marchado.

Paso 1: Enviar la petición de devolución

Debes proporcionar el pedidoBase (el ID de pedido único generado por la API durante la venta original) y el importe a devolver.

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 140000",
    "datosOperacion": {
      "importe": "5.00",
      "factura": "REFUND-001",
      "pedidoBase": "916548"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Devoluciones parciales: Puedes devolver un importe menor que la transacción original (devolución parcial). No puedes devolver más del importe original.

Paso 2: Recibir la respuesta

Puesto que no se requiere interacción física, esta operación a menudo se completa de forma síncrona, devolviendo el resultado directamente en el payload de la respuesta si tiene éxito.

Ejemplo de respuesta de éxito:

{
  "info": {
    "resultado": { "codigo": "0" },
    "resultadoDevolucion": {
      "importe": "5.00",
      "resultado": "Autorizada",
      "estado": "F",
      "pedidoBase": "916548"
    }
  },
  "signature": "SERVER_SIGNATURE"
}

Método 2: Devolución con tarjeta presente

Si la política de tu negocio requiere que el cliente esté presente para verificar la tarjeta, utiliza el método de Tarjeta presente. Este flujo hace que el terminal solicite la inserción de la tarjeta.

• Endpoint: /devolucionTarjeta
• Método: POST
• Caso de uso: Devoluciones en tienda donde la verificación de la tarjeta es obligatoria.

Paso 1: Enviar la petición

El payload es casi idéntico al de la devolución referenciada, pero debes incluir una URL de notificación porque el proceso se vuelve asíncrono (a la espera del terminal).

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 143000",
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/refunds"
    },
    "datosOperacion": {
      "importe": "5.00",
      "factura": "REFUND-STORE-002",
      "pedidoBase": "916548"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Paso 2: Gestionar la notificación

La API enviará una petición POST a tu urlNotificacion una vez que se lea la tarjeta y el banco autorice la devolución.

Requisitos del recibo

Los recibos de devolución tienen un requisito de cumplimiento normativo específico que difiere de los recibos de ventas.

Firma del comercio requerida: Para los recibos de devolución proporcionados al cliente, debes imprimir un recuadro de firma. A diferencia de una venta donde el cliente firma, el comercio debe firmar o sellar el recibo de devolución para confirmar la devolución de los fondos al cliente.

Solución de problemas

Próximos pasos

• Consultar el historial de transacciones: Verifica el estado del pedido original para obtener el pedidoBase correcto antes de realizar la devolución.
• Especificaciones de impresión de recibos: Consulta el diseño específico para los recibos de devolución.