Autenticación
Una API key secreta en tu servidor. La key identifica el negocio y el entorno (prueba o producción) y trae sus permisos.
Cabecerahttp
Authorization: Bearer kuti_live_…- Obligatoria en los endpoints de API (cobros, clientes, webhooks, saldo, …): Authorization: Bearer kuti_…
- Checkout público (GET /checkout-sessions/{id}): no uses la secret key; pasa el client_secret de la sesión como ?client_secret=… o header X-Kuti-Token.
- Sin key o inválida → 401 UNAUTHORIZED.
- kuti_test_… = prueba; kuti_live_… = producción. No mezcles datos entre entornos.
- Key sin el permiso del endpoint → 403 INSUFFICIENT_SCOPE. Endpoint solo del panel → 403 API_KEY_NOT_ALLOWED.
Cómo obtener la key
Dashboard KUTI → Desarrolladores → API keys. El plaintext solo se muestra al crearla. Guárdala en un secreto de servidor.
Claves live: el negocio debe tener el sello KUTI habilitado (verificación en Ajustes). Si no, la API responde 403 KYB_REQUIRED. Las de prueba se pueden crear desde el inicio.
Permisos de la key
Al crear la key eliges qué puede hacer: Lectura y escritura (tu backend), Solo lectura (asistentes de IA, reportes, diagnóstico) o Personalizado, recurso por recurso. Cada endpoint pide su permiso; sin él responde 403 INSUFFICIENT_SCOPE.
| Permiso | Leer | Escribir |
|---|---|---|
| payment_intents (Cobros) | GET /payment-intents, GET /fee-preview | crear, anular, enviar por WhatsApp/correo |
| payment_links (Links de pago) | GET /payment-links | crear, editar, activar/desactivar |
| subscriptions (Suscripciones) | GET /subscriptions | crear, editar, pausar, reanudar, cancelar, reintentar, enviar el monto |
| receivables (Cartera) | GET /receivables | crear, cancelar |
| customers (Clientes) | GET /customers, GET /customer-fields, GET /customers/{id}/payment-methods | crear, editar, borrar, desvincular medios guardados |
| checkout | GET /checkout-sessions/{id} | POST /checkout-sessions |
| payment_exceptions (Pagos para revisar) | GET /payment-exceptions | marcar como resuelto |
| webhooks | GET /webhook-endpoints | registrar, borrar, reintentar entregas |
| merchant (Datos del negocio) | GET /merchants/{id} | PATCH /merchants/{id} |
| payments (Pagos) | GET /payments/{id} | — |
| balance (Saldo y liquidaciones) | GET /balance, /balance-transactions, /payouts, /payout-accounts | — |
| events (Eventos) | GET /events | — |
Solo desde el panel (una API key recibe 403 API_KEY_NOT_ALLOWED aunque tenga todos los permisos): cambiar la cuenta bancaria de liquidación, crear negocios, marca, verificación KUTI, plan y automatizaciones. Así una key filtrada nunca puede desviar tus liquidaciones.
¿Y en el navegador?
Nunca pongas una API key en el frontend. KUTI.js y el checkout funcionan con el client_secret del cobro, que tu backend crea con su key secreta y le pasa al navegador. Por eso no existen claves publicables: en el frontend no va ninguna key.
Ejemplo
cURLbash
-primary-dark)">curl -s https://api.kuti.pe/v1/payment-intents \
-H 'Authorization: Bearer kuti_test_…' \
-H 'Content-Type: application/json'Siguiente
- SDKs — Node, PHP y Python
- Plugins — WooCommerce 1.0.0
- Prueba vs producción — test vs live
- Crear cobro — POST /payment-intents