Autenticacion

La API publica de SimplePay usa bearer API keys:

request

Authorization: Bearer spk_sandbox_...

Las API keys pertenecen a un tenant y a un ambiente. SimplePay valida la key, resuelve el tenant y aplica scopes antes de ejecutar la solicitud.

Usa solo la API publica documentada y no pongas API keys en frontend, repos, screenshots, logs o artefactos de evidencia.

Ambientes

Ambiente	Key	Uso
Sandbox	`spk_sandbox_...`	Desarrollo, QA, pruebas de webhooks y datos no reales.
Live	`spk_live_...`	Pagos reales despues de aprobacion, policy gates y webhooks validados.

Scopes

Algunos endpoints declaran scopes en la especificacion OpenAPI con x-simplepay-required-scopes.

Scope	Permite
`products:read`	Leer productos, configuracion Bookable y preflight.
`products:write`	Crear o actualizar productos y bundles.
`catalog:read`	Leer catalogo publico CMS.
`customer_hub:read`	Leer customers, timeline, imports y sync sources del Customer Hub.
`customer_hub:write`	Crear o actualizar customers, addresses, relationships, external refs, links, imports y sync sources del Customer Hub.
`customer_hub.contacts:write`	Agregar o actualizar contactos del Customer Hub.
`customer_hub.notes:write`	Agregar notas del Customer Hub.
`customer_hub.segments:read`	Leer tags del Customer Hub.
`customer_hub.segments:write`	Crear tags del Customer Hub.
`customer_hub.provider_sync:write`	Disparar la proyeccion al provider del Customer Hub.
`availability:read`	Leer slots, recursos, schedules y disponibilidad.
`availability:write`	Crear o modificar recursos, schedules, rules, overrides y event types.
`bookings:read`	Leer bookings.
`bookings:write`	Crear holds, checkouts, cancelaciones, refunds y reschedules.
`webhooks:read`	Leer endpoints webhook.
`webhooks:write`	Crear, borrar y reintentar webhooks.
`policies:read`	Leer y evaluar politica efectiva de pagos.

Hosted Checkout, Payment Links, Bookable Payments y Refunds tambien pasan por autenticacion bearer y por politica interna de tenant, aunque algunas rutas no expongan un scope explicito en la spec.

Headers recomendados

request

Authorization: Bearer spk_sandbox_...
Content-Type: application/json
Idempotency-Key: order_1001_checkout_v1

Usa Idempotency-Key para cualquier operacion que crea o muta estado.

Manejo de secrets

Guarda keys en tu secret manager

Usa variables de entorno o el secret manager de tu plataforma. No las serialices en config publica.

Usa una key por ambiente

Mantener sandbox y live separados reduce accidentes y hace mas simple revocar acceso.

Aplica minimo privilegio

Para un integration test de Bookable no necesitas scopes de catalogo si solo creas holds y bookings.

Rota ante sospecha

Si una key aparece en logs o chat, revocala y emite una nueva.

Ejemplo de backend

server.ts

export async function createCheckoutSession(order: {
  id: string;
  amount: number;
  email: string;
}) {
  const response = await fetch("https://api.simplepay.mx/v1/hosted-checkout/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SIMPLEPAY_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `${order.id}_checkout_v1`,
    },
    body: JSON.stringify({
      currency: "mxn",
      customer_email: order.email,
      success_url: `https://example.com/orders/${order.id}/success`,
      cancel_url: `https://example.com/orders/${order.id}`,
      client_reference_id: order.id,
      line_items: [{ name: "Orden", amount: order.amount, quantity: 1 }],
      metadata: { order_id: order.id },
    }),
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}

Quickstarts

Fundamentos

Aceptar pagos

Bookable Payments

Webhooks

LLMs y DX

Ambientes

Scopes

Headers recomendados

Manejo de secrets

Ejemplo de backend

​Ambientes

​Scopes

​Headers recomendados

​Manejo de secrets

​Ejemplo de backend

Ambientes

Scopes

Headers recomendados

Manejo de secrets

Ejemplo de backend