WooCommerce Redsys Gateway REST API

Overview

The WooCommerce Redsys Gateway Premium plugin exposes two complementary machine-to-machine surfaces on top of the same signed Redsys pipeline that powers a normal checkout (PSD2/SCA on the shopper side, signed IPN on the bank side). Every automated payment still ends in a real WooCommerce order.

Both surfaces ship off by default and must be enabled by the merchant under WooCommerce → Settings → Redsys Advanced → Agentic Commerce. Until enabled, the endpoints return a service-unavailable error while the public discovery documents (Agent Card, UCP manifest) stay reachable so a client can still discover the surface.

There are also two internal namespaces — redsys-acp/v1 (Agentic Commerce Protocol bridge) and redsys-app/v1 (mobile/app helper routes). They follow the same OAuth model and are not covered endpoint-by-endpoint here.

Base URLs & namespaces

All REST routes are served from your store's WordPress REST root under the plugin namespaces. Discovery documents are additionally published at well-known paths at the site root.

# 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

For convenience, several UCP capabilities are also registered under capability-scoped aliases (for example redsys-ucp/checkout/v1, redsys-ucp/catalog/v1, redsys-ucp/orders/v1) that mirror the canonical redsys-ucp/v1 routes. Prefer the canonical namespace shown throughout this page.

Authentication

Both surfaces authenticate with OAuth 2.1 + PKCE bearer tokens issued by the UCP authorization server bundled in the same plugin. There are no static API keys. A token is sent on every request in the Authorization: Bearer header.

Register a client dynamically, then run the standard authorization-code + PKCE flow. A2A clients must register with a client_type beginning with a2a_; the server then issues a client_id of the form a2a_… and a one-time client_secret. A2A tokens carry a2a:payments:* scopes; a UCP-flavored token is rejected on the A2A surface and vice-versa — the surfaces are isolated on purpose.

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'

Scopes are matched exactly — a2a:payments:create does not imply a2a:payments:read. Every A2A request passes a five-gate chain: authenticate, authorize (scope), IP whitelist, hours window and per-client rate limit (default 60/min, 600/hour, 5000/day). A sandbox bearer credential is available for local testing but only resolves when WP_DEBUG is true and the merchant has explicitly enabled it; it is never honored on a production install.

A2A — Agent2Agent

A2A is a JSON-RPC 2.0 surface. Discovery is via the Agent Card; every operation is a single POST to the /rpc endpoint; long-running tasks report progress over 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 — discovery

The UCP manifest advertises the supported capabilities, their spec/schema URIs and the OAuth authorization server. Discovery requires no authentication.

UCP — catalog & products

Read-only catalog discovery for agentic shopping. Product ids are WooCommerce product ids. A pre-built JSON product feed is available for bulk ingestion.

UCP — cart sessions

A cart session holds line items before checkout. Create one, then read or update it by id.

UCP — checkout sessions

A checkout session turns a cart into a payable order. Complete it to trigger the signed Redsys payment, or cancel it. The same routes are also exposed under the generic /sessions alias.

Alias routes: POST /sessions, GET /sessions/{id}, PATCH /sessions/{id}, POST /sessions/{id}/complete, POST /sessions/{id}/cancel.

UCP — orders

Read orders created through the commerce surface and act on them. Order ids are WooCommerce order ids.

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

UCP — webhooks

Register HTTPS endpoints to receive signed event notifications (for example when an order is paid or refunded) instead of polling.

Error handling

UCP REST endpoints return standard HTTP status codes with a WordPress-style JSON error body (code, message, data.status). A2A endpoints return JSON-RPC error envelopes; transport-level failures additionally carry the matching HTTP status.

Representative A2A JSON-RPC error codes: -32002 scope_denied (with data.required_scope), -32003 rate_limited (with data.window and data.limit), and a2a_client_revoked when a real token maps to a revoked client.