Documentación para desarrolladores
Ciclo del pago
Separa la experiencia del navegador de la verdad financiera para evitar entregas prematuras y cobros duplicados.
Responsabilidades
| Actor | Responsabilidad |
|---|---|
| Tu servidor | Protege la API key, crea la sesión y procesa eventos ya verificados. |
| AndorPay | Mantiene la sesión, la operación financiera, el estado canónico y la entrega de webhooks. |
| Redsys | Autoriza o rechaza el pago y presenta 3DS cuando el emisor lo requiere. |
| El navegador | Abre el checkout, completa los pasos interactivos y muestra una pantalla de retorno. |
Flujo completo
- 1
Tu servidor crea una sesión
POST /v1/checkouts valida comercio, producto, entorno e importe y devuelve hostedUrl. - 2
El comprador abre AndorPay
La página alojada muestra tarjeta, Bizum, Apple Pay o Google Pay cuando el TPV y el dispositivo lo permiten. - 3
Redsys procesa la autorización
El flujo puede terminar de inmediato, solicitar una acción 3DS o quedar pendiente de confirmación bancaria. - 4
AndorPay concilia el resultado
Los callbacks firmados del rail actualizan el pago, el pedido, la factura y la suscripción cuando corresponda. - 5
Tu aplicación recibe un evento
Después de verificar la firma, aplica el efecto de negocio y responde con cualquier estado 2xx.
Éxito, cancelación y fallo en el navegador
| Situación | Qué hacer |
|---|---|
| El comprador llega a successUrl | Muestra una confirmación provisional. Espera payment.succeeded antes de entregar o activar acceso. |
| El comprador llega a failUrl | Permite volver al carrito o consultar el estado. No asumas que existe un fallo terminal sin estado canónico. |
| El comprador cierra o cancela | Conserva el pedido sin pagar y no crees otro cobro mientras el intento anterior siga sin conciliar. |
| El checkout muestra un rechazo | Espera payment.failed o consulta GET /v1/payments antes de habilitar un nuevo intento relacionado. |
Estados asíncronos y conciliación
Durante 3DS, Bizum o una respuesta incierta del proveedor, el checkout puede permanecer en procesamiento, pendiente de autorización bancaria o reconciliation_required. En ese estado AndorPay consulta y aplica la verdad del rail; el comprador no debe repetir el pago a ciegas.
| Estado de pago | Interpretación |
|---|---|
processing | La operación está abierta o esperando resultado. |
requires_action | Redsys requiere un paso interactivo, normalmente 3DS. |
succeeded | La operación fue confirmada. Se emite payment.succeeded. |
failed | La operación terminó sin cobro. Se emite payment.failed. |
cancelled | La operación se canceló. No existe un evento configurable específico para cancelación de pago. |
refunded / partially_refunded | Estado contable posterior. Los reembolsos Redsys no están habilitados en la implementación actual. |
Pagos recurrentes
Un producto recurrente puede crear una suscripción, un pago y una factura en la misma conciliación. Procesa cada evento por su significado: payment.succeeded confirma dinero, subscription.createdo subscription.updated describe acceso y periodo, y invoice.created describe el documento de cobro.
Los cobros posteriores son iniciados por AndorPay como MIT cuando el TPV dispone de tokenización y recurrencia. Un fallo puede generar payment.failed, invoice.payment_failed y, si hace falta intervención del comprador, payment_method.updated_required.