Skip to main content

​
Nomenclatura de campos

Zonapagos usa húngaro ligero — los nombres de campos incluyen un prefijo que indica su tipo:
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

​
El formato de porcentaje

Algunos parámetros de cobro por transacción (50002, 50102) esperan un porcentaje en un formato no estándar:

Convención del formato de 4 dígitos

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:
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:
  • 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.