Saltar al contenido principal
Toda solicitud a la API de Z2Pay se autentica mediante una API key, enviada en el header x-api-key. 
curl https://api.sandbox.z2pay.com/transactions \
  -H "x-api-key: z2_psp_sk_suachavesecreta"
La secret key (sk) otorga acceso total a su cuenta. Nunca la exponga en el frontend, en aplicaciones móviles, en repositorios públicos ni en logs. Úsela exclusivamente en su servidor.

​
Formato de la clave

Las claves siguen el patrón z2_{escopo}_{tipo}_{aleatorio} (256 bits de entropía): 
z2_psp_sk_Kx8y9pQ1n3...      secret key do produto PSP
z2_chk_pk_AbC9dEf2...        publishable key do produto Checkout
ParteValoresSignificado
Escopopsp, chk, stl, afProducto (PSP, Checkout, Settle, Antifraude).
Tiposk (secret), pk (publishable)Nivel de acceso.

​
Secret (sk) × Publishable (pk)

Secret key (sk)

Acceso completo (crear, leer, actualizar, reembolsar). Solo en el backend.

Publishable key (pk)

Acceso restringido a operaciones públicas (ej.: tokenización en el frontend). Puede ser expuesta en el navegador.

​
Cómo obtener su clave

  1. Acceda al Dashboard de Z2Pay.
  2. Para claves de prueba, ingrese al entorno de sandbox y genere las credenciales allí.
  3. Para claves de producción, genérelas en el entorno de producción.
  4. Copie la clave en el momento de su creación — por seguridad, se muestra una sola vez (luego queda enmascarada, ej.: z2_psp_sk_KxY8…3pQ1).
Las claves de sandbox y de producción tienen el mismo formato, pero se generan en entornos distintos y no son intercambiables. Una clave de sandbox solo funciona en *.sandbox.z2pay.com.

​
Respuestas de autenticación

SituaciónStatusRespuesta
Header x-api-key ausente o inválido401{ "error": { "code": "UNAUTHORIZED", ... } }
Clave válida, pero sin permiso para la operación403{ "error": { "code": "FORBIDDEN", ... } }
Consulte el formato completo en Errores.

​
Buenas prácticas

Use variables de entorno

Cargue la clave desde una variable de entorno o secret manager, nunca escrita directamente en el código.

Rote si hay una filtración

¿Sospecha de una filtración? Genere una nueva clave y revoque la anterior desde el Dashboard.

Una clave por entorno

Separe claramente las claves de sandbox y de producción en su aplicación.

Restrinja en el frontend

En el navegador o app utilice únicamente la pk. La sk nunca debe salir del servidor.