WooCommerce Redsys Gateway REST API

Visión general

El plugin WooCommerce Redsys Gateway Premium expone dos superficies máquina a máquina complementarias sobre el mismo pipeline firmado de Redsys que impulsa un checkout normal (PSD2/SCA del lado del comprador, IPN firmado del lado del banco). Cada pago automatizado sigue terminando en un pedido real de WooCommerce.

Ambas superficies vienen desactivadas por defecto y deben ser habilitadas por el comerciante en WooCommerce → Ajustes → Redsys Advanced → Agentic Commerce. Hasta que se habiliten, los endpoints devuelven un error de servicio no disponible mientras que los documentos públicos de descubrimiento (Agent Card, manifiesto UCP) siguen siendo accesibles para que un cliente pueda descubrir la superficie.

También existen dos namespaces internos — redsys-acp/v1 (puente Agentic Commerce Protocol) y redsys-app/v1 (rutas auxiliares para móvil/app). Siguen el mismo modelo OAuth y no se cubren endpoint por endpoint aquí.

URLs base y namespaces

Todas las rutas REST se sirven desde la raíz REST de WordPress de tu tienda bajo los namespaces del plugin. Los documentos de descubrimiento se publican además en rutas well-known en la raíz del sitio.

# A2A (JSON-RPC)
https://your-store.com/wp-json/wc-redsys-a2a/v1/

# UCP (REST) — canonical namespace
https://your-store.com/wp-json/redsys-ucp/v1/

# UCP OAuth 2.1 authorization server
https://your-store.com/wp-json/redsys-ucp/oauth/v1/

# Well-known discovery documents
https://your-store.com/.well-known/agent-card.json
https://your-store.com/.well-known/ucp.json
https://your-store.com/.well-known/oauth-authorization-server

Por comodidad, varias capacidades de UCP también se registran bajo alias acotados por capacidad (por ejemplo redsys-ucp/checkout/v1, redsys-ucp/catalog/v1, redsys-ucp/orders/v1) que reflejan las rutas canónicas redsys-ucp/v1. Usa preferentemente el namespace canónico que se muestra a lo largo de esta página.

Autenticación

Ambas superficies se autentican con tokens bearer OAuth 2.1 + PKCE emitidos por el servidor de autorización UCP incluido en el mismo plugin. No hay claves de API estáticas. En cada petición se envía un token en la cabecera Authorization: Bearer.

Registra un cliente de forma dinámica y luego ejecuta el flujo estándar authorization-code + PKCE. Los clientes A2A deben registrarse con un client_type que empiece por a2a_; el servidor emite entonces un client_id con la forma a2a_… y un client_secret de un solo uso. Los tokens A2A llevan scopes a2a:payments:*; un token de tipo UCP se rechaza en la superficie A2A y viceversa — las superficies están aisladas a propósito.

POST /wp-json/redsys-ucp/oauth/v1/register
{
  "client_name": "Concierge Bot",
  "client_type": "a2a_concierge",
  "redirect_uris": ["https://bot.example/oauth/callback"],
  "scopes": ["a2a:payments:read", "a2a:payments:create"]
}

curl https://your-store.com/wp-json/redsys-ucp/v1/discovery \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Los scopes se comparan de forma exacta — a2a:payments:create no implica a2a:payments:read. Cada petición A2A atraviesa una cadena de cinco controles: autenticar, autorizar (scope), lista blanca de IP, ventana horaria y límite de tasa por cliente (por defecto 60/min, 600/hora, 5000/día). Hay una credencial bearer de sandbox disponible para pruebas locales, pero solo se resuelve cuando WP_DEBUG es true y el comerciante la ha habilitado explícitamente; nunca se acepta en una instalación de producción.

A2A — Agent2Agent

A2A es una superficie JSON-RPC 2.0. El descubrimiento se realiza mediante la Agent Card; cada operación es un único POST al endpoint /rpc; las tareas de larga duración informan del progreso mediante Server-Sent Events.

POST /wp-json/wc-redsys-a2a/v1/rpc
Authorization: Bearer <token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tasks/send",
  "params": {
    "skill_id": "create_payment",
    "input": {
      "amount": 1250,
      "currency": "EUR",
      "order_reference": "ORDER-2026-001",
      "mode": "redirect"
    },
    "idempotency_key": "5d1c…"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task_id": "b9b3f9a4-…",
    "state": "input-required",
    "artifacts": {
      "sca_redirect_url": "https://your-store.com/checkout/order-pay/…"
    }
  }
}

UCP — descubrimiento

El manifiesto UCP anuncia las capacidades soportadas, sus URIs de especificación/esquema y el servidor de autorización OAuth. El descubrimiento no requiere autenticación.

UCP — catálogo y productos

Descubrimiento de catálogo de solo lectura para compra agéntica. Los ids de producto son ids de producto de WooCommerce. Hay disponible un feed de productos JSON pregenerado para ingestión masiva.

UCP — sesiones de carrito

Una sesión de carrito contiene las líneas de artículos antes del checkout. Crea una y luego léela o actualízala por id.

UCP — sesiones de checkout

Una sesión de checkout convierte un carrito en un pedido pagable. Complétala para desencadenar el pago firmado de Redsys, o cancélala. Las mismas rutas también se exponen bajo el alias genérico /sessions.

Rutas alias: POST /sessions, GET /sessions/{id}, PATCH /sessions/{id}, POST /sessions/{id}/complete, POST /sessions/{id}/cancel.

UCP — pedidos

Lee los pedidos creados a través de la superficie de comercio y actúa sobre ellos. Los ids de pedido son ids de pedido de WooCommerce.

{
  "order_id": 10432,
  "status": "refunded",
  "refunded_amount": 1250,
  "currency": "EUR"
}

UCP — webhooks

Registra endpoints HTTPS para recibir notificaciones de eventos firmadas (por ejemplo cuando se paga o reembolsa un pedido) en lugar de hacer polling.

Manejo de errores

Los endpoints REST de UCP devuelven códigos de estado HTTP estándar con un cuerpo de error JSON al estilo de WordPress (code, message, data.status). Los endpoints A2A devuelven sobres de error JSON-RPC; los fallos a nivel de transporte llevan además el estado HTTP correspondiente.

Códigos de error JSON-RPC de A2A representativos: -32002 scope_denied (con data.required_scope), -32003 rate_limited (con data.window y data.limit), y a2a_client_revoked cuando un token real se corresponde con un cliente revocado.