Conceptos clave
El modelo detrás de la API de Vecnet — dos rieles, un libro mayor de partida doble y multi-tenencia por comercio.
Vecnet es una plataforma de pagos con una sola API, un solo libro mayor y una sola bitácora de auditoría para cobros en línea y presenciales. Esta página explica el modelo para que el resto de la documentación tenga sentido.
Dos rieles
Cada pago pertenece exactamente a un riel (rail). El riel describe cómo
se presentó la tarjeta.
| Riel | Valor | Qué cubre |
|---|---|---|
| En línea | online_cnp | Tarjeta no presente: checkout alojado y ligas de pago. |
| Presencial | inperson_cp | Tarjeta presente: terminales físicas en sucursales. |
Cada fila de transactions lleva siempre su rail, así que puedes filtrar y
conciliar el dinero en línea contra el presencial con un solo campo. Los dos
rieles comparten la misma forma de transacción, los mismos estados, el mismo
libro mayor y los mismos webhooks: integras una sola vez.
El libro mayor de partida doble
El movimiento de dinero se registra en un libro mayor de partida doble. Cada transacción es el registro visible hacia afuera; el libro mayor es la verdad contable debajo, con cargos y abonos balanceados entre cuentas y pólizas.
El libro mayor es lo que hace confiables la conciliación y la liquidación: los saldos, la reserva rotativa, las comisiones y las corridas de liquidación se calculan a partir de él.
Los montos van siempre en unidades mínimas
Todos los montos son enteros en las unidades mínimas de la moneda
(centavos). La moneda por defecto es MXN.
Nunca envíes un monto con decimales. Para cobrar MXN 250.00, envía el
entero 25000. Para mostrar un monto guardado, divide entre 100.
Multi-tenencia por comercio
La plataforma es multi-tenant, con dos categorías de usuario:
- Operadores: trabajan a través de varios comercios desde el panel y
limitan cada petición a un comercio con el encabezado
X-Merchant-Id. - Usuarios de comercio: están anclados a su propio comercio y nunca pueden ver los datos de otro.
Cada recurso del comercio (transacciones, terminales, liquidaciones, webhooks y
demás) se filtra por merchant_id. Consulta Autenticación
para ver cómo se identifica a cada quien.
Trazabilidad
Cada petición a la API y cada evento de pago se escribe en una bitácora de
auditoría de solo escritura. Todo el ciclo de vida de un pago queda enlazado por
un mismo correlation_id, y cada llamada HTTP individual por un
request_id (devuelto en el encabezado X-Request-Id). Consulta
Trazabilidad.
Siguientes pasos
Autenticación
Cómo se autentican tu integración y los operadores del panel.
Convenciones
URLs base, montos, IDs con prefijo, el sobre de lista y marcas de tiempo.
Pagos en línea
El riel de tarjeta no presente: checkout alojado y ligas de pago.
Pagos presenciales
El riel de tarjeta presente: terminales y conciliación.