Skip to main content

​
Nomenclatura de campos

ZonaPagos usa húngaro ligero — los nombres de campos incluyen un prefijo que indica su tipo:
PrefijoTipoEjemplo
int_Enteroint_id_comercio, int_estado_pago
str_Cadenastr_id_pago, str_descripcion
flt_Decimalflt_total_con_iva, flt_valor_iva
dbl_Decimal (en responses)dbl_valor_pagado, dbl_total_pago
dat_Fecha/horadat_fecha
Aunque flt y dbl son ambos decimales, históricamente flt_ aparece en requests y dbl_ aparece en responses. Ambos aceptan los mismos valores.

​
Formato de valores numéricos

TipoFormatoEjemplo
EnterosSin separadores, sin decimales.50000
DecimalesPunto como separador decimal, máximo 2 decimales.83000.50, 7983.00
MonedaEn pesos colombianos por defecto (COP).50000 = $50.000 COP
Porcentajes en AdicionalesConfiguracionFormato propietario de 4 dígitos. Los 2 últimos son decimales. Ver abajo.0195 = 1.95%

​
El formato de porcentaje

Algunos parámetros de cobro por transacción (50002, 50102) esperan un porcentaje en un formato no estándar: 
"0195" → 1.95%
"0200" → 2.00%
"0050" → 0.50%
"1000" → 10.00%
"2500" → 25.00%
Esta convención es propietaria y propensa a errores. Envía siempre el valor como string (no como número), con ceros a la izquierda para completar 4 dígitos. Ver ejemplos completos en Cobro por transacción.

​
Formato de fechas

Las fechas en VerificacionPago (campo dat_fecha dentro de str_res_pago) vienen como: 
dd/mm/yyyy hh:mm:ss
Ejemplo: 21/04/2026 14:32:10 (hora Colombia, UTC-5).

​
Formato de str_res_pago

El campo str_res_pago del response de VerificacionPago no es JSON — es texto plano con separadores: 
campo1|campo2|campo3|...|campoN|;|campo1|campo2|...;|
  • Pipe simple | separa campos dentro de un pago.
  • Pipe-punto-y-coma-pipe |;| separa pagos distintos cuando hay varios intentos.
  • El orden de los campos es fijo y depende del medio de pago.
Ver Parsear str_res_pago con código listo para copiar.

​
Campos opcionales

Cuando un campo es opcional, puedes:
  • Omitirlo del JSON (recomendado).
  • Enviar null.
  • Enviar un string vacío "" (para campos de tipo string).
Los str_opcional1 a str_opcional5 de InformacionPago te permiten enviar metadata arbitraria que luego recibes de vuelta en VerificacionPago. Úsalos para trazabilidad: ID de pedido interno, campaña, canal de venta, etc.

​
Límites de tamaño

​
str_id_pago
string
required
Máximo 30 caracteres. No puede tener ceros a la izquierda (serían eliminados).
​
str_descripcion_pago
string
required
Máximo 70 caracteres.
​
str_email
string
Máximo 70 caracteres.
​
str_id_cliente
string
Máximo 30 caracteres.
​
str_nombre_cliente / str_apellido_cliente / str_telefono_cliente
string
Máximo 50 caracteres cada uno.
​
str_opcional1 a str_opcional5
string
Máximo 70 caracteres cada uno.
​
str_usuario / str_usr_comercio
string
Máximo 40 caracteres.
​
str_clave / str_pwd_Comercio
string
Máximo 50 caracteres.
​
str_url (en response)
string
Máximo 126 caracteres.

​
Reglas de negocio

​
str_id_pago único por transacción

Cada intento de pago debe usar un str_id_pago único dentro de tu comercio. Si reintenta un pago rechazado, usa un nuevo str_id_pago (puedes agregarle un sufijo: ORDEN-001-R1, ORDEN-001-R2).

​
int_modalidad — conocido problema de documentación

El instructivo oficial v6.0 tiene una contradicción: el texto dice que int_modalidad debe ser siempre -1, pero el ejemplo JSON oficial envía 1. Esta documentación refleja la inconsistencia hasta que TI confirme el valor correcto.Recomendación provisional: usa -1 siguiendo el texto normativo.

​
Callback del comercio

La URL de retorno se configura una sola vez al activar el comercio, o se envía dinámicamente en cada pago con el código 104 de AdicionalesConfiguracion. Si envías 104, ese valor prevalece.

​
Próximo paso

Endpoint /InicioPago →

La referencia del primer endpoint que llamarás.