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

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

​
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

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:
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

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.