Autenticación

La API pública de Paytami se autentica con una llave secreta en el header Authorization, estilo Bearer:

Authorization: Bearer sk_test_51a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6

No hay usuario, contraseña ni OAuth — una sola llave por integración.

Formato de la llave

sk_<ambiente>_<40 caracteres hexadecimales>

• sk_test_... — ambiente de prueba, no mueve dinero real.
• sk_live_... — ambiente de producción.

El ambiente en el que corre cada petición lo decide la llave: Paytami la busca primero en producción y, si no aparece ahí, en el ambiente de prueba. No hace falta indicar el ambiente en ningún otro lugar de la petición.

Cómo obtener tu llave

Las llaves se emiten desde el panel de Paytami (dash.paytami.com), en la sección de API Keys de tu comercio. Al crear una llave nueva, el valor completo se muestra una sola vez — Paytami solo guarda su hash, así que si la pierdes hay que revocarla y emitir una nueva.

Buenas prácticas

• Nunca expongas una llave secreta en código que corre en el navegador del cliente (JavaScript de frontend, apps móviles). Todas las llamadas autenticadas con sk_... deben originarse en tu servidor.
• Usa variables de entorno o un gestor de secretos — nunca hardcodees la llave en el repositorio.
• Si sospechas que una llave se filtró, revócala desde el panel y emite una nueva de inmediato; el hash previo deja de ser válido al instante.
• Usa sk_test_... durante todo el desarrollo e integración, y cambia a sk_live_... solo cuando estés listo para cobrar de verdad. Los datos de ambos ambientes están completamente separados: un pago creado en prueba nunca aparece en producción ni viceversa.

Respuesta cuando la autenticación falla

Una llave ausente, inválida, revocada, expirada o del tipo equivocado siempre responde igual:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "unauthorized",
    "message": "Credenciales inválidas"
  }
}

Paytami no distingue el motivo exacto en la respuesta a propósito: detallar "la llave expiró" vs. "la llave no existe" ayuda más a alguien sondeando llaves al azar que a una integración legítima, que ya sabe cuál llave emitió.

Endpoints que no requieren api_key

Algunas rutas las abre directamente el navegador del cliente final, que no tiene credenciales — por diseño no llevan Authorization:

• GET /v1/checkout/{id} y GET /v1/payments/{id}/checkout_session
• GET /v1/payment_links/{id} y POST /v1/payment_links/{id}/pay

Estas rutas solo exponen lo mínimo necesario para completar un pago ya creado por tu backend — nunca operaciones que muevan dinero sin que tu api_key haya intervenido antes.