Enviar una solicitud de reversión

información

El pago solo se puede revertir si está en estado Autorizado.

Puede consultar el estado del pago en el endpoint:

GET /payments/{id}

¿Qué es una Reversión?

Una reversión (reversal) cancela una transacción que aún no ha sido liquidada (settled). A diferencia de una devolución, la reversión impide que los fondos sean transferidos, cancelando la autorización antes del settlement.

aviso

La reversión solo puede realizarse antes del settlement diario. Después del settlement, debe utilizar una devolución (refund).

1. Inicio de la Reversión (vía API)

Su sistema inicia la reversión remotamente a través de la API PayPay:

1. El sistema envía la solicitud a la API PayPay:

Endpoint

PATCH /terminals/{uuid}/reversals/{paymentId}

Exemplo básico

{
  "remarks": {
    "text": "remarks text"
  }
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
uuid	string	✅ Sí	UUID del terminal donde se realizó el pago original
paymentId	string	✅ Sí	ID del pago PayPay que desea revertir
remarks.text	string	❌ No	Comentarios adicionales sobre la reversión

2. API PayPay se comunica con la red de pagos y procesa la reversión de forma síncrona;
3. API PayPay devuelve la respuesta con el resultado de la reversión.

Respuesta de la API

{
    "date": "2025-09-01T12:46:22+01:00",
    "success": true,
    "data": {
        "id": "4",
        "clientId": "502056800",
        "type": "reversal",
        "amount": 100,
        "initialPaymentId": "1",
        "stateDetails": {
            "state": "cancelled",
            "createdAt": "2025-09-01T12:46:22+01:00"
        },
        "cancellation": {
            "cancelled": true,
            "cancelledAt": "2025-09-01T12:46:22+01:00",
            "reason": "merchant_cancelled"
        },
        "paymentMethod": {
            "code": "CC",
            "type": "TPA",
            "details": {
                "brand": "VISA",
                "last4Digits": "7193"
            }
        },
        "createdAt": "2025-09-01T11:46:22+01:00",
        "updatedAt": "2025-09-01T11:46:22+01:00"
    }
}

Estructura de la Respuesta

Campo	Tipo	Descripción
id	string	ID de la reversión PayPay
clientId	string	NIF de la entidad asociada al pago
type	string	Tipo de operación
amount	integer	Importe revertido
initialPaymentId	string	ID del pago original
stateDetails.state	string	Estado de la reversión
stateDetails.createdAt	datetime	Fecha del estado
cancellation.cancelled	boolean	Éxito de la cancelación
cancellation.cancelledAt	datetime	Fecha de la cancelación
cancellation.reason	string	Motivo de la cancelación
paymentMethod	object	Método de pago original
createdAt	datetime	Fecha de creación del registro
updatedAt	datetime	Fecha de la última actualización

Procesamiento de la Reversión

Después de que la solicitud de reversión se envía a través de la API, el proceso sigue estos pasos:

1. El terminal recibe la solicitud de reversión;
2. El sistema envía la solicitud de cancelación a la red de pagos;
3. La red contacta con el banco emisor para cancelar la autorización;
4. La respuesta se envía de vuelta al terminal:
   • Aprobada: Reversión procesada con éxito, autorización cancelada.
   • Rechazada: Mensaje de error mostrado (ej: pago ya liquidado).

información

La reversión no requiere la presentación de la tarjeta, ya que es una cancelación de la autorización original.

3. Notificación al Sistema

Después de la confirmación, su sistema es notificado:

1. La transacción se sincroniza con el backoffice de PayPay en tiempo real;
2. PayPay notifica vía Webhook su sistema con los detalles de la reversión.

Reversión vs Devolución

Aspecto	Reversión	Devolución
Cuándo usar	Antes del settlement	Después del settlement
Tarjeta necesaria	No	Sí
Parcial	No	Sí
Movimiento de fondos	Cancela autorización	Devuelve fondos