Documentación para desarrolladores

Solución de problemas

Localiza primero la capa que falla: autenticación, creación de sesión, checkout alojado, rail o consumo del webhook.

Método de diagnóstico

Evidencia	Qué confirma
`request_id`	La petición concreta atendida por la API.
`x-andorpay-flow-id`	Las fases relacionadas de un mismo flujo operativo.
`event.id`	La entrega lógica que puede aparecer en varios intentos.
Estado en AndorPay	La verdad canónica después de procesar el callback del rail.
Estado en Redsys	La respuesta y operación del proveedor bancario.
Referencia de tu pedido	El efecto aplicado en el sistema del comercio.

No uses la página de retorno como evidencia financiera. Compara identificadores y timestamps entre las tres capas antes de repetir una operación.

La API rechaza la autenticación

Síntoma	Comprobación
Falta Authorization	Envía Authorization: Bearer seguido de la API key completa.
api_key_invalid	Comprueba que la clave no esté revocada y que no incluya espacios o saltos de línea.
merchant_inactive	Completa o revisa el estado del comercio en el dashboard.
Entorno incorrecto	ap_test_ sólo usa la cuenta Redsys de sandbox; ap_live_ sólo usa producción.
merchant_scope_mismatch	Elimina merchantId o utiliza el comercio que autentica la clave.

Validar una API key

bash

curl https://api.andorpay.com/v1/products \
  --header "Authorization: Bearer $ANDORPAY_API_KEY" \
  --header "Andorpay-Version: 2026-01-01"

No se crea o no carga el checkout

Código o síntoma	Corrección
checkout_idempotency_key_not_allowed	Elimina Idempotency-Key de POST /v1/checkouts.
price_id_not_allowed	Envía productId. AndorPay toma el precio activo del producto.
product_not_found	Copia un producto activo del mismo comercio.
checkout_amount_invalid	Envía un entero positivo en céntimos.
checkout_amount_not_allowed_with_trial	Elimina amount; el trial pertenece al precio recurrente.
payment_rail_unavailable	Comprueba cuenta Redsys, entorno, moneda EUR y método habilitado.
Campos de tarjeta vacíos	Comprueba inSite, dominio exacto, HTTPS, CSP, WAF y extensiones del navegador.
Sesión caducada	Crea una sesión nueva. expiresAt está 30 minutos después de la creación.

El pago permanece pendiente

Un challenge 3DS, Bizum o una respuesta incierta puede dejar el checkout en processing oreconciliation_required. No crees un segundo cobro hasta comprobar el pago anterior en AndorPay y Redsys.

Consulta GET /v1/payments con la misma API key y correlaciona order_id,rail_order_id, request_id y tu referencia. Si Redsys tiene resultado terminal pero AndorPay no, conserva la evidencia y escala la conciliación; no fuerces fulfillment desde el navegador.

El webhook falla o se reentrega

Síntoma	Comprobación
invalid_signature	Lee el cuerpo como texto antes de JSON y usa el secreto activo.
Timestamp fuera de tolerancia	Sincroniza el reloj del servidor y acepta como máximo 5 minutos.
301 o 302	Configura la URL final. AndorPay no sigue redirects.
Timeout	Responde en menos de 15 segundos o acepta el evento antes de trabajo prolongado según tu arquitectura.
Mismo event.id	Es una reentrega esperada. No repitas el mismo efecto de negocio.
Eventos desordenados	No dependas de orden global. Decide a partir del contenido y estado canónico.

WooCommerce no concilia el pedido

Abre WooCommerce, Estado, Registros y selecciona andorpay-card-gateway. Después revisa Acciones programadas por el grupo andorpay-card y comprueba que WP-Cron o el cron real ejecuta tareas vencidas.

Usa la acción Sincronizar pago con AndorPay desde el pedido. Si el webhook está degradado, verifica que/wp-json/andorpay/v1/webhook admite POST público sin login, CAPTCHA o redirección.

Preparar un caso para soporte

Incluye	No incluyas
request_id, event.id, flow_id, productId, payment id, hora y zona horaria	API keys, secreto webhook o secreto Redsys
Entorno, método, estado visible en cada sistema y pasos para reproducir	PAN, caducidad, CVV o token de wallet
Versión de SDK o plugin, framework y respuesta HTTP redacted	Payloads completos que contengan datos personales innecesarios