Skip to main content

​
Modelo actual

ZonaPagos autentica cada request dentro del cuerpo JSON. No hay headers Authorization, ni API keys en la URL, ni JWT, ni OAuth. Cada endpoint espera tres campos de autenticación, con un detalle de naming que hay que conocer:
EndpointCampo IDCampo usuarioCampo clave
POST /InicioPagoint_id_comercio (dentro de InformacionSeguridad)str_usuariostr_clave
POST /VerificacionPagoint_id_comercio (raíz)str_usr_comerciostr_pwd_Comercio
Los nombres de los campos son diferentes entre los dos endpoints. str_usuario en uno y str_usr_comercio en el otro contienen el mismo valor. Lo mismo aplica para str_clave / str_pwd_Comercio. Hay que respetar el naming exacto de cada endpoint.

​
Obtener credenciales

Las credenciales se asignan al activar tu cuenta comercial. Son:
​
int_id_comercio
integer
required
Identificador único del comercio. Ej. 31416.
​
str_usuario / str_usr_comercio
string
required
Nombre de usuario técnico. Máximo 40 caracteres.
​
str_clave / str_pwd_Comercio
string
required
Clave. Máximo 50 caracteres. Se puede cambiar desde el portal de ZonaPagos.
Contacta a comercial@zonapagos.com si aún no las tienes.

​
Seguridad operativa

Usa siempre HTTPS. El API solo acepta conexiones TLS.
Guarda las credenciales en secret manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Vault de Hashicorp, variables de entorno cifradas). Nunca en código ni en repositorios.
Rota la clave periódicamente desde el portal de ZonaPagos.
Monitorea accesos a tus credenciales en tu infra. Una clave comprometida permite iniciar pagos a tu nombre (aunque el dinero va a tu cuenta comercial, no a la del atacante).
Limitaciones de seguridad actuales del API (conocer y planificar mitigaciones):
  • No existe mecanismo de firma HMAC de los requests.
  • No hay TOTP ni MFA para el cambio de clave.
  • El callback GET al comercio no incluye una firma verificable. El parámetro rut de la URL del ciclo de pago no se devuelve al comercio en el callback — solo id_comercio e id_pago. Debes verificar el estado final llamando VerificacionPago desde tu backend; nunca confíes en el callback como fuente de verdad.
[Pendiente con TI: evaluar incorporación de firma de request y verificación de callback.]

​
Errores de autenticación

SíntomaDiagnóstico
int_codigo: 2 con str_descripcion_error mencionando credencialesUsuario o clave incorrectos.
int_codigo: 2 con "Object reference not set to an instance of an object."int_id_comercio inválido, o estás usando credenciales dummie contra el API REST de producción.
HTTP 200 pero int_codigo: 2 sin descripción útilValidar que el JSON está bien formado y que todos los campos obligatorios están presentes.
Más detalle en Manejo de errores.

​
Próximo paso

Convenciones del API →

Tipos de dato, formatos numéricos y reglas generales.