Autenticación

Todas las peticiones autenticadas llevan el header x-wpay-key con la clave privada de tu sistema:

curl -X POST "https://api.wizpay.app/payment/init" \
  -H "x-wpay-key: TU_CLAVE_PRIVADA" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pedido #1", "amount": 100, "id_currency": 1 }'

La clave identifica a tu sistema (comercio). Si el sistema está suspendido por falta de pago, la API responde 401 hasta que se regularice.

Respuestas de autenticación

Caso	HTTP	Mensaje
Header ausente	`401`	`Se requiere el header x-wpay-key`
Clave inexistente o sistema no `ACTIVO`	`401`	`Clave inválida o sistema inactivo`

Pruébalo — deja la key vacía o escribe invalid:

POST/payment/init⚡ Simulador — se ejecuta en tu navegador

Ruta

Header x-wpay-key (prueba dejarlo vacío o poner “invalid”)

Body (JSON)

Ver cURL equivalente (producción)

curl -X POST "https://api.wizpay.app/payment/init" \
  -H "x-wpay-key: wpk_sandbox_demo" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pedido #1", "amount": 100, "id_currency": 1 }'

Endpoints públicos (sin key)

Estos endpoints los consume el navegador del cliente directamente, por eso no requieren key:

Método	Ruta	Uso
`GET`	`/status/:reference`	Estado de una transacción (páginas de éxito/fallo).
`GET`	`/qr/status/:numero_referencia`	Estado del QR en la red bancaria (polling).
`GET`	`/qr/stream/:reference`	Stream SSE de eventos del QR en tiempo real.
`POST`	`/3ds/callback`	Retorno del navegador tras el Step-Up 3DS (lo llama el proveedor 3DS).
`GET`	`/location/countries`	Catálogo de países para el formulario de facturación.
`GET`	`/location/states/:code`	Estados/departamentos de un país.
`GET`	`/subscriptions/cancel/:token`	Cancelación de suscripción por enlace firmado.

Rate limit

Cada sistema tiene un límite de peticiones por minuto (60 por defecto, configurable por sistema). Al excederlo:

HTTP 429 · Too Many Requests

{
  "message": "Rate limit excedido",
  "retryAfter": 42
}

La respuesta incluye el header Retry-After con los segundos que faltan para que se reinicie la ventana.

⚠️

Implementa backoff: si recibes 429, espera Retry-After segundos antes de reintentar. Los endpoints públicos no consumen tu límite.

Buenas prácticas de seguridad

Guarda la key en un secreto de entorno (WPAY_KEY), nunca en el código.
La key va solo en llamadas servidor → servidor. El navegador jamás la ve.
Usa una key distinta por sistema/ambiente. Si sospechas que una key se filtró, regenérala desde el panel.
Los webhooks salientes de WizPay pueden llevar Authorization: Bearer <key_auth> — configura esa verificación en tu receptor. Ver Webhooks.

Inicio rápido Pago con tarjeta (3DS)