Skip to main content
Todas las peticiones a Connect deben incluir tu clave en el header Authorization con esquema Bearer. La misma clave autentica todos los endpoints (payment intents, addresses, balances, payouts, etc.). El SDK del navegador no usa claves — sólo monta UI a partir de un payment_intent_id que tu servidor creó previamente.

​
Obtener tus claves

  1. Accede al panel de integración con tu cuenta de organización.
  2. En la sección de desarrolladores, genera una clave sandbox (sk_test_...) para pruebas.
  3. Cuando tu organización esté aprobada, genera una clave live (sk_live_...) para producción.
Guarda cada clave en un gestor de secretos. Solo se muestra una vez al crearla.

​
Formato de las claves

TipoPrefijoUso
Sandboxsk_test_Aislamiento de datos sandbox + acceso a helpers /test/...
Producciónsk_live_Datos de producción
Sandbox y producción operan sobre redes reales con dinero real. El prefijo controla el aislamiento de datos y el modo de los webhooks, no si la red es “fake”. Ver Entornos.

​
Ejemplo de petición

curl -X GET "https://api.zopay.cash/connect/v1/balances" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
Cuenta aprobada

Los endpoints que implican movimiento de fondos exigen que tu organización esté activa en Connect. Si aún está en pending_verification o suspended, recibirás HTTP 403 con código account_pending_approval.

​
Errores de autenticación

SituaciónHTTPCódigo
Sin header o formato incorrecto401authentication_required
Clave inválida o revocada401authentication_required
Clave con expires_at en el pasado401expired_credential
Organización no aprobada403account_pending_approval
Clave válida pero sin el scope requerido403forbidden_scope
Clave sk_live_… contra una ruta /test/...404(los helpers sandbox son invisibles a claves live)
El code es estable; haz match contra él en tu cliente en lugar de parsear message. La diferencia entre authentication_required y expired_credential es deliberada: la primera dice “revisa el header”, la segunda dice “rota la clave”.

​
Expiración y rotación de claves

Cada clave puede llevar un timestamp opcional expires_at (ISO 8601). Cuando se cumple, la API devuelve 401 expired_credential con un mensaje indicando la fecha. Cuando expires_at es null (default para claves legacy o minteadas sin TTL), la clave no expira.

​
Detectar expiración desde tu cliente

GET /connect/v1/health devuelve key_expires_at: 
curl -sS "https://api.zopay.cash/connect/v1/health" \
  -H "Authorization: Bearer $TOKEN" | jq .key_expires_at
# -> "2026-09-01T00:00:00Z"  (o null si no hay expiración)
Patrón recomendado: tu servicio chequea key_expires_at al arranque y alerta a ops si está dentro de tu ventana de rotación (p. ej. 14 días).

​
Envelope del error de expiración

{
  "error": {
    "type": "authentication_error",
    "code": "expired_credential",
    "message": "This API key expired at 2026-06-02T12:00:00+00:00. Mint a fresh key from the admin panel and update your client.",
    "doc_url": "https://docs.zopay.cash/errors/expired_credential"
  }
}
No compartas claves en repositorios públicos, logs ni capturas de pantalla. Rota la clave desde el panel si sospechas una filtración — la rotación invalida la anterior inmediatamente.