Documentación API

Payzen expone una API REST JSON bajo /api/v1. Cada workspace (tu cuenta / empresa) tiene sus propios datos aislados: la clave API y la sesión siempre operan sobre un solo tenant.

URL base para tus llamadas: https://api.payzen.cl/api/v1

En producción sustituye por el dominio real de tu despliegue (p. ej. https://api.tudominio.com/api/v1). En local suele ser http://localhost:3001/api/v1. Si usas túnel HTTPS, define API_DOCS_BASE_URL en billing_ui para que el asistente muestre la URL pública correcta.

• Content-Type: application/json en cuerpos POST / PATCH.
• Respuestas con envoltorio { "data": … } en recursos principales; errores con { "error": { "code", "message" } }.
• Idempotencia: en operaciones que crean cobros o efectos laterales (p. ej. POST …/payments/:id/attempt), envía un UUID único en Idempotency-Key para poder reintentar sin duplicar el intento.
• Fechas en ISO 8601 (UTC) salvo que el campo indique lo contrario.

1. Cliente: POST /api/v1/customers (o reutiliza uno existente buscando por email).
2. Suscripción: POST /api/v1/subscriptions con items: [{ price_id, quantity }].
3. Factura: POST /api/v1/invoices con customer_id, subscription_id e ítems.
4. Pago: POST /api/v1/payments con invoice_id, luego POST /api/v1/payments/:id/attempt con Idempotency-Key para iniciar el cobro con el proveedor (Mercado Pago, Transbank, etc.).
5. Consulta el estado con GET /api/v1/payments/:id o espera el webhook que Payzen envía a tu URL (ver abajo).

curl -sS -X GET "https://api.payzen.cl/api/v1/customers" \
  -H "Accept: application/json" \
  -H "X-Api-Key: sk_live_tu_clave"

Para que un comprador pague sin iniciar sesión en Payzen, usa el enlace de checkout del plan (token firmado ck). El flujo usa endpoints públicos bajo /api/v1/public/checkout/… (sin X-Api-Key en el cliente final).

Opcionalmente puedes configurar API_KEY en el servidor del checkout Next solo para ciertos flujos; la documentación detallada está en el asistente de inicio.

Payzen envía notificaciones HTTP POST a tu servidor cada vez que ocurre un evento relevante (pago aprobado, suscripción cancelada, etc.). Esto permite que tu sistema reaccione en tiempo real sin tener que consultar la API periódicamente.

POST https://tu-servidor.com/webhook
Content-Type: application/json
X-Billing-Signature: t=1712800000,v1=a1b2c3d4...
Idempotency-Key: <event_id>

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "data": {
    "payment_id": "pay_xyz",
    "amount": 15000,
    "currency": "CLP",
    "customer_id": "cus_456"
  },
  "occurred_at": "2026-04-10T20:00:00Z"
}

# Ejemplo en Ruby
sig = request.headers["X-Billing-Signature"]
match = sig.match(/t=(\d+),v1=([a-f0-9]+)/i)
timestamp = match[1]
received_hmac = match[2]

data = "#{timestamp}.#{request.raw_post}"
expected = OpenSSL::HMAC.hexdigest("SHA256", ENV["WEBHOOK_SECRET"], data)

if ActiveSupport::SecurityUtils.secure_compare(expected, received_hmac)
  # Firma válida → procesar evento
else
  head :unauthorized
end

# Ejemplo en Node.js / Express
const crypto = require("crypto");

app.post("/webhook", (req, res) => {
  const sig = req.headers["x-billing-signature"];
  const [, t, v1] = sig.match(/t=(\d+),v1=([a-f0-9]+)/i) || [];

  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) {
    return res.status(401).send("Timestamp expired");
  }

  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(t + "." + req.rawBody)
    .digest("hex");

  if (expected !== v1) return res.status(401).send("Invalid signature");

  // Procesar evento...
  res.status(200).json({ ok: true });
});

No confundir con los webhooks que envía Mercado Pago a Payzen: esos van a la ruta de proveedor en la API de Payzen y usan la firma x-signature de MP.

La referencia completa de paths, esquemas y códigos de error está en el archivo OpenAPI del monorepo:

billing_platform/docs/openapi/openapi.yaml

Incluye la API clásica (X-Api-Key) y la capa pública de integración bajo /api/v1/public/… (tag PublicIntegration). Puedes importarlo en Postman, Insomnia o generar un SDK con openapi-generator.

Guías Markdown: billing_platform/docs/integration-external-apps.md (API servidor) y public-subscription-integration.md (SDK / público).

El monorepo incluye un servidor Model Context Protocol (stdio) en mcp-server/: expone esta guía y consultas al OpenAPI como herramientas para asistentes (p. ej. Cursor).

• Instalación: en el repo, cd mcp-server && npm install && npm run build.
• Variable opcional: PAYZEN_REPO_ROOT con la ruta absoluta al monorepo; si no se define, se infiere desde la ubicación del paquete.
• Herramientas: payzen_integration_guide, payzen_openapi_summary, payzen_openapi_list_paths, payzen_openapi_get_operation.
• Cursor: en ajustes MCP, comando node con argumento la ruta a mcp-server/dist/index.js (tras el build). Detalle y ejemplos JSON en mcp-server/README.md del repositorio.

• Claves con el menor alcance (scopes) posible y rotación periódica.
• Timeouts y reintentos con backoff; respeta 429 si existiera rate limit.
• Registra X-Request-Id o el cuerpo de error para soporte.
• En producción usa siempre HTTPS y certificados válidos en tu endpoint de webhook.