Enviar una solicitud de reembolso

información

El pago solo se puede devolver si está en estado Confirmado.

Puede consultar el estado del pago en el endpoint:

GET /payments/{id}

Tipos de Devolución

• Devolución total
• Devolución parcial

1. Inicio de la Devolución (a través de API)

Su sistema inicia la devolución de forma remota a través de la API de PayPay:

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

Endpoint

POST /terminals/{uuid}/refunds/{paymentId}

Ejemplo básico

{
  "amount": 100,
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
uuid	string	✅ Sí	UUID del terminal al que se enviará la solicitud de pago
paymentId	string	✅ Sí	ID del pago PayPay que desea devolver
amount	integer	✅ Sí	Importe que desea devolver

2. API PayPay se comunica con el terminal de forma asíncrona;
3. El terminal recibe y muestra automáticamente el importe al operador;

información

El terminal espera 1 minuto por la presentación de la tarjeta.

4. La API de PayPay devuelve la respuesta del éxito o fracaso de la solicitud asíncrona, mientras que el terminal espera a que se presente la tarjeta.

Respuesta de la API

{
    "date": "2025-09-01T12:46:22+01:00",
    "success": true,
    "data": {
        "id": "3",
        "clientId": "502056800",
        "type": "refund",
        "amount": 50,
        "initialPaymentId": "1",
        "stateDetails": {
            "state": "pending_confirmation",
            "createdAt": "2025-09-01T12:46:22+01:00"
        },
        "paymentMethod": {
            "code": "CC",
            "type": "TPA",
            "details": {
                "brand": "VISA",
                "last4Digits": "7193"
            }
        },
        "availableMethods": [
            {
                "code": "CC",
                "type": "TPA",
                "name": "Credit Debit card Physical TPA"
            }
        ],
        "bankAccount": {
            "code": "O9uFVmSZ",
            "bankName": "Banco",
            "last4digits": "8513"
        },
        "createdAt": "2025-09-01T12:46:22+01:00",
        "updatedAt": "2025-09-01T12:46:22+01:00"
    }
}

Estructura de la Respuesta

Campo	Tipo	Descripción
id	string	ID de la devolución PayPay
clientId	string	NIF de la entidad a la que se asoció el pago
type	string	Tipo de operación
stateDetails.state	string	Estado del pago
stateDetails.createdAt	datetime	Fecha del estado
paymentMethod	object	Método de pago del pago original
availableMethods	object	Formas de pago disponibles para la devolución
bankAccount	object	Identificación del banco que recibirá los fondos
createdAt	datetime	Fecha de creación del registro
updatedAt	datetime	Fecha de la última actualización

Flujo de devolución en el terminal

Una vez enviada la solicitud de devolución a través de la API, el proceso en el terminal sigue estos pasos:

2. Presentación de la Tarjeta

El cliente presenta la misma tarjeta utilizada en el pago original:

1. El terminal muestra el importe de la devolución al operador;
2. El cliente presenta la tarjeta mediante uno de los siguientes métodos:
   • Contactless: Acerca la tarjeta o el dispositivo móvil.
   • Chip: Introduce la tarjeta en el terminal.
   • Banda magnética: Pasa la tarjeta.
3. El terminal comprueba si la tarjeta coincide con el pago original.

aviso

La tarjeta debe ser la misma utilizada en el pago original. Si se presenta una tarjeta diferente, se rechazará la devolución.

3. Autenticación

Dependiendo del importe y del tipo de tarjeta, puede ser necesaria la autenticación:

1. Los datos de la tarjeta son leídos y validados por el terminal;
2. El sistema comprueba si es necesaria la autenticación:
   • En caso afirmativo: El cliente introduce el PIN.
     • Si el PIN es correcto: Continúa con el procesamiento.
     • Si el PIN es incorrecto: Nuevo intento o cancelación (máx. 3 intentos).
   • En caso contrario: Procesamiento directo para autorización.

Tipos de autenticación:

• PIN: Normalmente requerido para devoluciones.
• Sin autenticación: En algunos casos de valores bajos.

4. Procesamiento y Confirmación

El terminal se comunica con la red de pagos para procesar la devolución:

1. El terminal valida los datos y envía la solicitud a la red de pago;
2. La red se pone en contacto con el banco emisor para tramitar la devolución;
3. La respuesta se envía de vuelta al terminal:
   • Aprobada: Devolución procesada con éxito.
   • Rechazada: Mensaje de error mostrado.

5. Notificación al Sistema

Tras la confirmación, se le notificará a su sistema:

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 devolución.

consejo

Configure webhooks para recibir notificaciones automáticas del resultado de la devolución. La respuesta de la API solo indica que la solicitud se ha enviado al terminal, no el resultado final.